🐬 Lightweight caching DNS server/forwarder
Go Shell
Pull request Compare This branch is 1 commit ahead, 14 commits behind janeczku:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
cache
hostsfile
resolvconf
scripts
server
stats
.gitignore
Dockerfile
Dockerfile.build
LICENSE
README.md
main.go

README.md

go-dnsmasq

Docker Pulls

Version 1.0.5

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

Features

  • 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] 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 addresses must be enclosed in brackets. (defaults to /etc/resolv.conf value) - $DNSMASQ_SERVERS
--stubzones, -z Use a different nameserver for specific domains. Flag can be passed multiple times to specify more zones. domain[,domain]/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] (defaults to /etc/resolv.conf value) - $DNSMASQ_SEARCH
--append-search-domains, -a Resolve queries by appending search domains False $DNSMASQ_APPEND
--rcache, -r Capacity of the response cache (‘0‘ to disable cache) 0 $DNSMASQ_RCACHE
--rcache-ttl TTL for entries in the response cache 60 $DNSMASQ_RCACHE_TTL
--no-rec Disable recursion False $DNSMASQ_NOREC
--fwd-ndots Minimum number of dots a name must have before the query is allowed to be forwarded to upstream nameservers 0 $DNSMASQ_FWD_NDOTS
--ndots Number of dots a name must have before an initial absolute query will be made (defaults to /etc/resolv.conf value) 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 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: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:

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.