The Domain Name System (DNS) is arguably the best (and most used) service that the internet has spawned.  Why leave all the fun Top Level Domain (TLD) stuff to ICANN & your registrar?  You can have your own TLD using Dnsmasq.

This is part one of a three part series covering Dnsmasq’s uses regarding:

  1. Local Development DNS
  2. Local Area Network (LAN) DNS
  3. Virtual Private Network (VPN) routing

The only prerequisites for running Dnsmasq is a Unix-based operating system (including Mac OSX).  The only prerequisite for reading this article in the series is interest in doing any sort of web development locally.  I’m going to cover a simple example using WordPress, but the principle is the same for any web site or service software written in any language.  Basically, if your normal local development addresses look something like http://localhost/~me/bobscountrybunker/ then Dnsmasq is for you.

Installing & Starting Dnsmasq

I’m going to cover installation & configuration for Ubuntu 12.04, but over time I haven’t seen a lot of changes in the way Dnsmasq is configured.  So configuration should apply to OSX and other Linux distros.

To install on a Debian-based system:

$ sudo apt-get install dnsmasq

Dnsmasq will probably start automatically the next time you boot, but to start it now execute:

$ sudo service dnsmasq start

Systems that don’t use upstart will probably start it like this

$ sudo /etc/init.d/dnsmasq start

Even with no configuration changes, your computer still should work as normal, but if you inspect your /etc/resolv.conf it probably now has a line like this:


Dnsmasq is already up and running, taking in DNS requests from your computer and at this point just forwarding most of them to your upstream DNS provider. Nothing groundbreaking, but now we can control DNS ourselves and have a little fun.

Configuring Dnsmasq

The configuration files will be in /etc/dnsmasq.conf and/or /etc/dnsmasq.d. The addition of the /etc/dnsmasq.d directory is new to Ubuntu 12.04 (not sure which Dnsmasq version it corresponds to), and it’s a welcome addition because you can put your customized files in there without worrying about /etc/dnsmasq.conf getting overwritten during the next release upgrade.

The files in /etc/dnsmasq.d are executed by the order of their filename, so it would be wise to number your most important configuration with a `01` prefix, such as /etc/dnsmasq.d/01_localhost

Top Level Domains – not just for the big-boys (anymore)

You can invent a new Top Level Domain for use on your local system.  On some distributions the convention is to use ‘.lan’ but you could name it what ever you’d like. I don’t recommend anything too long or the ‘.local’ extension which is used by multicast dns.  Here’s a simple /etc/dnsmasq.d/01_localhost configuration file:


Now every address that ends in ‘.lan’ will belong to your local IP.  After (re)starting Dnsmasq, try it out:

$ ping wordpress.lan
PING wordpress.lan ( 56(84) bytes of data.
64 bytes from localhost ( icmp_req=1 ttl=64 time=0.021 ms

Pairing Dnsmasq & Apache Web Server

Now let’s combine this with some Apache configuration for a real-world development example. I don’t want to get into the specifics of Apache configurations amongst different OSes and distributions, but on Ubuntu I put a config file in /etc/apache2/sites-available and symlink it to /etc/apache2/sites-enabled, however it can really go anywhere that Apache will read it:

<VirtualHost *:80>
    ServerName wordpress.lan
    ServerAlias *.wordpress.lan

    DocumentRoot /home/justin/wordpress
    <Directory /home/justin/wordpress/>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all

Once I’ve restarted/reloaded Apache, I can visit http://wordpress.lan in my browser on my local system to bring up an instance of WordPress. You may have noticed the ServerAlias *.wordpress.lan line in the configuration. With mod_rewrite enabled in Apache, I can take the set up a step further and turn this single WordPress installation into a subdomain network installation. This is a great set up if you are working on several sites but want to maintain a single main codebase for your content management software.

4 thoughts on “Pimpin’ your dev env with Dnsmasq

  1. Pingback: Pimp your LAN with OpenWrt & Dnsmasq « Business Unusual

  2. Pingback: (Re)routing VPN traffic with Dnsmasq « Business Unusual

  3. Actually, at least in the dnsmasq which ships with ubuntu 12.04 there is no sorting on the reading of files in dnsmasq.d, they are read in the order an “ls -alU” would print them. So putting 01 prefixes will not guarantee any particular order.

    I got around this by having a set of top level configs which I wanted processed first and them used the conf-dir directive to point to a sub dir. For example a top level dns config would have :

    which would then have dnsmasq read the files in that directory (in arbitrary order) but at least after the top level file.


Leave a Reply