go-dnsmasq
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
searchcapabilities tomusl-libcbased clients, particularly Alpine Linux
Features
- Automatically set upstream
nameserversandsearchdomains 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 bymusl-libcbased Linux distributions - Supports virtually unlimited number of
searchpaths andnameservers(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
searchdomains are tried in the order they are configured. - Single-label queries (e.g.: "redis-service") are always qualified with the
searchdomains - Multi-label queries (ndots >= 1) are first tried as absolute names before qualifying them with the
searchdomains
Command-line options / environment variables
| Flag | Description | Default | Environment vars |
|---|---|---|---|
| --listen, -l | Address to listen on host[:port] |
127.0.0.1:53 | $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
EnvVar: GRAPHITE_SERVER
Default:
Set to the host:port of the Graphite server
EnvVar: GRAPHITE_PREFIX
Default: go-dnsmasq
Set a custom prefix for Graphite metrics
EnvVar: STATHAT_USER
Default:
Set to your StatHat account email address
Usage
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:latestYou 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:
192.168.0.1 db1.db.local
192.168.0.2 *.db.local
Queries for 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.