How to create local wildcard domains in MacOS using dnsmasq?

Introduction

Recently I was looking around for tutorials to setup local wildcard domains in MacOS for development purpose. Most tutorials were similar and I just could not resolve the local domains. If you are having the same issue, your should take a look of your DNS server settings.

Preparation

Install dnsmasq

Dnsmasq is a DNS server which allows you to create DNS records locally. Besides, it also forwards domain queries to upstream servers, such that we can resolve public domains as well.

By default, dnsmasq looks for upstream servers in /etc/resolv.conf.

brew install dnsmasq

Verify your homebrew prefix

Dnsmasq service is installed in a different location based on your Mac's chip (Intel / Apple Silicon). You can check it by running command brew --prefix.

Since I am using M1 Macbook, the installation path is /opt/homebrew. If you are using intel Macbook, be careful of the path settings and make changes accordingly.

Modify the dnsmasq.conf file

vi $(brew --prefix)/etc/dnsmasq.conf

Go to the end of the file, uncomment the line conf-dir=/opt/homebrew/etc/dnsmasq.d/,*.conf.

Now dnsmasq will look for local DNS records in /opt/homebrew/etc/dnsmasq.d/.

Create a DNS record

I will use test as my local domain name. And I want dnsmasq to resolve any test domain queries to IP 127.0.0.1. Dnsmasq will also try to resolve subdomain records as well, such as a.test, b.c.test, which is very convenient.

bash -c "echo 'address=/test/127.0.0.1' > $(brew --prefix)/etc/dnsmasq.d/test.conf"

The name of the conf file does not matter, it is just good for management, having one file for each domain.

Setup DNS servers

To let your Macbook knows sending query to dnsmasq. Left click your wifi icon in the menu bar -> "Wi-Fi settings" -> "Details" -> go to "DNS" section.

Take a record of your existing DNS servers and remove all of them. Then add "127.0.0.1" as your topmost entry such that DNS query will be sent to dnsmasq first.

It is very important because if your query is send to other DNS servers first, it may respond with record is not found which explains why you are unable to query local domains.

Lastly you can add back all your existing DNS servers.

Now if you take a look of the /etc/resolv.conf file, you can see that it is actually generated from the settings of the "DNS" section.

(Re)start dnsmasq

To reflect your dnsmasq changes, you need to restart it.

# brew services start dnsmasq
brew services restart dnsmasq

Conclusion

It is a short article. Thanks for reading!