Skip to content
🐬 Lightweight caching DNS server/forwarder
Branch: master
Clone or download
Pull request Compare This branch is even with janeczku:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Latest Version Github All Releases Docker Pulls License

go-dnsmasq is a lightweight (1.2 MB) DNS caching server/forwarder with minimal filesystem and runtime overhead.

Application examples:

  • Caching DNS server/forwarder in a local network
  • Container/Host DNS cache
  • DNS proxy providing DNS search capabilities to musl-libc based clients, particularly Alpine Linux


  • Automatically set upstream nameservers and search domains 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 search domain treatment not supported by musl-libc based Linux distributions
  • Supports virtually unlimited number of search paths and 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

Resolve logic

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
  • Multiple search domains are tried in the order they are configured.
  • Single-label queries (e.g.: "redis-service") are always qualified with the search domains
  • Multi-label queries (ndots >= 1) are first tried as absolute names before qualifying them with the search domains

Command-line options / environment variables

Flag Description Default Environment vars
--listen, -l Address to listen on host[:port] $DNSMASQ_LISTEN
--default-resolver, -d Update resolv.conf to make go-dnsmasq the host's nameserver False $DNSMASQ_DEFAULT
--nameservers, -n Comma delimited list of nameservers host[:port]. IPv6 literal address must be enclosed in brackets. (supersedes etc/resolv.conf) - $DNSMASQ_SERVERS
--stubzones, -z Use different nameservers for given domains. Can be passed multiple times. domain[,domain]/host[:port][,host[:port]] - $DNSMASQ_STUB
--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 domain[,domain] (supersedes /etc/resolv.conf) - $DNSMASQ_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 the host:port of the Graphite server

Default: go-dnsmasq
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 -e flag.

Serving A/AAAA records from a hosts file

The --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: db1.db.local *.db.local

Queries for db2.db.local would be answered with an A record pointing to, while queries for db1.db.local would yield an A record pointing to

You can’t perform that action at this time.