Using Dnsmasq to Route Wildcard TLD-lookups to Localhost on OS X

Every web developer needs a simple way to resolve “fake” domain names to their local development environment. For developers using OS X, Dnsmasq makes manually managing their hosts file a thing of the past. This how-to guide walks through the process step-by-step.

Dnsmasq is a lightweight DNS forwarder created by Simon Kelly in 2001 and written in C, suitable for use in resource constrained environments such as firewalls and routers, it is included in most Linux distributions by default. Available on MacOS via Homebrew, Dnsmasq supports Wildcard domains, sub-domains, and even entire TLDs which makes it a perfect solution for configuring local web development environments.

Using Homebrew to install Dnsmasq

If you need to install Homebrew, use the Ruby installer:

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

To install Dnsmasq on MacOS, using Homebrew:

$ brew update
$ brew install dnsmasq

Check the Dnsmasq installation:

$ brew info dnsmasq

dnsmasq: stable 2.80 (bottled)
Lightweight DNS forwarder and DHCP server
http://www.thekelleys.org.uk/dnsmasq/doc.html
/usr/local/Cellar/dnsmasq/2.80 (8 files, 531.3KB) *
  Poured from bottle on 2019-07-07 at 14:19:31
From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/dnsmasq.rb
==> Dependencies
Build: pkg-config ✔
==> Caveats
To have launchd start dnsmasq now and restart at startup:
  sudo brew services start dnsmasq
==> Analytics
install: 7,583 (30 days), 22,732 (90 days), 110,109 (365 days)
install_on_request: 7,401 (30 days), 22,052 (90 days), 104,456 (365 days)
build_error: 0 (30 days)

Configuring Dnsmasq

The Dnsmasq installation information no longer shows the location of the dnsmasq.conf file, but it’s in the same place. Edit the Dnsmasq configuration file:

$ vim /usr/local/etc/dnsmasq.conf

At the bottom of dnsmasq.conf, add a pointer to a custom configuration file located in your home directory and replace YOUR_HOME_DIRECTORY with your username:

# This file will be added to the configuration
conf-file=/Users/YOUR_HOME_DIRECTORY/.dnsmasq/dnsmasq.conf

Now create the directory (replace YOUR_HOME_DIRECTORY with your username) and open a new file in a text editor:

$ mkdir /Users/YOUR_HOME_DIRECTORY/.dnsmasq
$ vim /Users/YOUR_HOME_DIRECTORY/.dnsmasq/dnsmasq.conf

Add the following lines to the new dnsmasq.conf file:

# The wildcard TLD (*.lcl) and all domains and subdomains will be resolved as 127.0.0.1
address=/lcl/127.0.0.1
listen-address=127.0.0.1

Configuring MacOS X

Most UNIX-like operating systems control the way DNS queries are performed with a configuration file called /etc/resolv.conf. OS X allows you to configure additional resolvers via configuration files in the /etc/resolver/ directory. Since it’s unlikely this directory exists on your system, create it:

$ sudo mkdir -p /etc/resolver

Now create a new file in this directory with the same name as your new top-level domain in the /etc/resolver/ directory and add a nameserver:

$ sudo vim /etc/resolver/lcl

Then add the following contents:

nameserver 127.0.0.1

Here lcl is the top-level domain name we want Dnsmasq to respond to and 127.0.0.1 is the IP address of the nameserver.

Starting Dnsmasq

You can now launch Dnsmasq and set it to start on every restart:

$ sudo brew services start dnsmasq

Testing Dnsmasq

You can test Dnsmasq by simply pinging any name with your TLD you will get a response that says no route to host, but the fact it resolves means it’s working:

$ ping example.lcl
PING example.lcl (0.0.0.0): 56 data bytes
ping: sendto: No route to host
ping: sendto: No route to host
Request timeout for icmp_seq 0
ping: sendto: No route to host
Request timeout for icmp_seq 1
çping: sendto: No route to host
Request timeout for icmp_seq 2

If it’s not working you will get the following:

$ ping example.dev
ping: cannot resolve example.dev: Unknown host