caddy-mdns

A Caddy plugin that automatically advertises .local site blocks over mDNS (multicast DNS), making them reachable by hostname on your local network — no router or DNS configuration needed.

How it works

mDNS (RFC 6762) lets devices on the same LAN resolve .local hostnames without a central DNS server. This plugin reads the live Caddy HTTP app config at startup and registers an mDNS service for every site block whose hostname ends in .local (or is a plain single-label name like printer).

Installation

xcaddy build --with git.mere.cloud/bngreer/caddy-mdns

Usage

Add mdns to the global options block — that's it. Hostnames are discovered automatically from your site blocks.

{
    mdns
}

myserver.local {
    respond "Hello from mDNS!"
}

files.local {
    root * /var/www/files
    file_server browse
}

Both myserver.local and files.local are advertised on your LAN automatically. No per-site configuration is needed.

What gets advertised?

Site block hostname	Advertised as
myserver.local	myserver.local ✅
files.local	files.local ✅
printer	printer.local ✅
example.com	(ignored) ❌
localhost	(ignored) ❌

Optional configuration

All sub-options are optional. mdns with no block is valid.

{
    mdns {
        extra_hostnames   scanner nas   # advertise names with no site block
        exclude_hostnames internal      # suppress a name from being advertised
        port              8080          # override the advertised port for all names
        iface             eth0          # restrict mDNS to one network interface
    }
}

Option	Default	Description
extra_hostnames	(none)	Extra names to advertise (.local suffix optional)
exclude_hostnames	(none)	Names to suppress, e.g. bare single-label site blocks not meant for mDNS
port	from listen address	Override the advertised TCP port for all names
iface	all interfaces	Restrict mDNS to a specific network interface

Notes

• mdns must appear in the global options block. It cannot be used inside a site block.
• Port 443 site blocks advertise _https._tcp; everything else uses _http._tcp.
• On Linux, ensure UDP port 5353 is open in your firewall.
• mDNS only works on the local network — it does not cross routers.

License

BNG - private

contact the author for licensing usage