Using a local nameserver for the .test domain on MacOS

When working with more complex setups for testing and developing one often needs a way to assign multiple domain names to locally running services. This allows to use name based virtual hosting, be it with a simple Nginx based proxy or a locally running Kubernetes cluster. MacOS allows to redirect the DNS queries to different nameservers based on the queried domain.

DNS configuration in MacOS

Disclaimer: I did not follow up to the authoritative documentation about this. So please take this with a certain level caution.

It seems the way to go to configure DNS servers in MacOS is currently by using the CLI tool scutil. It seems that the information in /etc/resolv.con reflects the configured primary DNS server and is updated automatically by the system whenever this changes. There is also configuration in /etc/resolver/... which seems to be a deprecated way of configuring the DNS system.

How to do it

The man pages for the tools and the help command in the interactive shell of scutil are a good companion, they explain everything in detail.

Here is one example:

sudo scutil

# Overview of commands
help

# List of DNS related configuration entries
list .*DNS

# Preparing a dataset
d.init
d.add ServerAddresses * 127.0.0.1
d.add SupplementalMatchDomains * test

# It seems to be possible to set the port number
# d.add ServerPort # 1234

set State:/Network/Service/local-dns-test-domain/DNS
quit

How to verify

Dump packages via tcpdump is the best way to observe this:

sudo tcpdump -n -i lo0 port 53

If you run ping something.test then you would see the following output:

IP 127.0.0.1.55741 > 127.0.0.1.53: 584+ A? something.test. (32)

Note

It may be required to flush a few DNS related caches:

sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

Pointers