go-dnsmasq is a lightweight (1.2 MB) DNS caching server/forwarder with minimal filesystem and runtime overhead.
- Caching DNS server/forwarder in a local network
- Container/Host DNS cache
- DNS proxy providing DNS
musl-libcbased clients, particularly Alpine Linux
- Automatically set upstream
searchdomains from resolv.conf
- Insert itself into the host's /etc/resolv.conf on start
- Serve static A/AAAA records from a hosts file
- Provide DNS response caching
- Replicate the
searchdomain treatment not supported by
musl-libcbased Linux distributions
- Supports virtually unlimited number of
nameservers(related Kubernetes article)
- Configure stubzones (different nameserver for specific domains)
- Round-robin of DNS records
- Send server metrics to Graphite and StatHat
- Configuration through both command line flags and environment variables
DNS queries are resolved in the style of the GNU libc resolver:
- The first nameserver (as listed in resolv.conf or configured by
--nameservers) is always queried first, additional servers are considered fallbacks
searchdomains are tried in the order they are configured.
- Single-label queries (e.g.: "redis-service") are always qualified with the
- Multi-label queries (ndots >= 1) are first tried as absolute names before qualifying them with the
Command-line options / environment variables
|--listen, -l||Address to listen on
|--default-resolver, -d||Update resolv.conf to make go-dnsmasq the host's nameserver||False||$DNSMASQ_DEFAULT|
|--nameservers, -n||Comma delimited list of nameservers
|--stubzones, -z||Use different nameservers for given domains. Can be passed multiple times.
|--hostsfile, -f||Path to a hosts file (e.g. ‘/etc/hosts‘)||-||$DNSMASQ_HOSTSFILE|
|--hostsfile-poll, -p||How frequently to poll hosts file for changes (seconds, ‘0‘ to disable)||0||$DNSMASQ_POLL|
|--search-domains, -s||Comma delimited list of search domains
|--enable-search, -search||Qualify names with search domains to resolve queries||False||$DNSMASQ_ENABLE_SEARCH|
|--rcache, -r||Capacity of the response cache (‘0‘ disables caching)||0||$DNSMASQ_RCACHE|
|--rcache-ttl||TTL for entries in the response cache||60||$DNSMASQ_RCACHE_TTL|
|--no-rec||Disable forwarding of queries to upstream nameservers||False||$DNSMASQ_NOREC|
|--fwd-ndots||Number of dots a name must have before the query is forwarded||0||$DNSMASQ_FWD_NDOTS|
|--ndots||Number of dots a name must have before making an initial absolute query (supersedes /etc/resolv.conf)||1||$DNSMASQ_NDOTS|
|--round-robin||Enable round robin of A/AAAA records||False||$DNSMASQ_RR|
|--systemd||Bind to socket(s) activated by Systemd (ignores --listen)||False||$DNSMASQ_SYSTEMD|
|--verbose||Enable verbose logging||False||$DNSMASQ_VERBOSE|
|--syslog||Enable syslog logging||False||$DNSMASQ_SYSLOG|
|--multithreading||Enable multithreading (experimental)||False|
|--help, -h||Show help|
|--version, -v||Print the version|
Enable Graphite/StatHat metrics
Set to thehost:port` of the Graphite server
Set a custom prefix for Graphite metrics
Set to your StatHat account email address
Run from the command line
Download the binary for your OS from the releases page.
go-dnsmasq is available in two versions. The minimal version (
go-dnsmasq-min) has a lower memory footprint but doesn't have caching, stats reporting and systemd support.
sudo ./go-dnsmasq [options]
Run as a Docker container
Docker Hub trusted builds are available.
docker run -d -p 53:53/udp -p 53:53 janeczku/go-dnsmasq:latest
You can pass go-dnsmasq configuration parameters by setting the corresponding environmental variables with Docker's
Serving A/AAAA records from a hosts file
--hostsfile parameter expects a standard plain text hosts file) with the only difference being that a wildcard
* in the left-most label of hostnames is allowed. Wildcard entries will match any subdomain that is not explicitly defined.
For example, given a hosts file with the following content:
192.168.0.1 db1.db.local 192.168.0.2 *.db.local
db2.db.local would be answered with an A record pointing to 192.168.0.2, while queries for
db1.db.local would yield an A record pointing to 192.168.0.1.