Wildcard DNS in your Ubuntu hosts file using dnsmasq

Today we are going to add a wildcard DNS entry to our systems DNS resolver, to allow for easy local web application development (on Ubuntu 12.04). So, if we have a project called “LeaseWebLabs” that is (or will be) hosted on http://www.leaseweb.com/labs, we might want to develop it on http://www.leaseweblabs.dev. To achieve this we need to change the DNS resolving (resolving = hostname to IP address conversion) of specific hostnames. We want to achieve that anything ending with “.dev” resolves to the IP address (which is the localhost).

Goal: *.dev ==[resolves-to]==>

Before we go into the details, let me give you an overview of the applications involved. The applications and/or files that have a part in DNS resolving (on Ubuntu) are:

  1. /etc/hosts (this file is used to override the resolver)
  2. network-manager (the network icon on your desktop)
  3. dnsmasq-base (local resolver, installed by default, unconfigurable)
  4. dnsmasq (full configurable version that can be added manually)
  5. resolvconf (manages the contents of the file “/etc/resolv.conf”)
  6. avahi-daemon (a.k.a. ZeroConf or Bonjour, this uses .local)
  7. apache2 (the webserver needs to respond to the .dev hostname)

Long instructions

You can add “ leaseweblabs.dev” to your “/etc/hosts” and the problem is solved. Easy right? This works, but it is NOT possible to have a wildcard DNS entry in the ‘hosts’ file. This means you will have to update the ‘hosts’ file for every hostname you want to use. This can be a problem when your web application works with dynamically generated subdomains. Fortunately, there is a workaround.

To understand the workaround we first need to understand how Ubuntu does DNS resolving. From version 12.04 onward, it uses the “dnsmasq-base” package to do DNS resolving, which is started by the “network-manager” service. This base version does not allow you to use a “/etc/dnsmasq.conf” file for configuring and will just serve the contents of the “/etc/hosts” file (and rules added by the network manager).

Wildcard DNS entries are possible in the dnsmasq config file “/etc/dnsmasq.conf”. The format of the wildcard entries in “/etc/dnsmasq.conf” is “address=/dev/”, where “dev” is the wildcard domain (e.g. *.dev). You should try to avoid running an open resolver and add the line “listen-address=” and “bind-interfaces”. Note that you should not use “.local”, since avahi-daemon is using that. You can make it work, but it will be slower, since ZeroConf (mdns) has to check your local network for devices first.

To disable the non-configurable dnsmasq-base, we can simply comment out the line “dns=dnsmasq” in “/etc/NetworkManager/NetworkManager.conf”. Next we can install the full dnsmasq using “sudo apt-get install dnsmasq”. Note that it won’t start because the old dnsmasq is still running. When you want to start using the full dnsmasq it will complain that it failed to create a listening socket, like this:

dnsmasq: failed to create listening socket: Address already in use

Now we can find the process-id of dnsmasq (base) and kill it using the word kill and the process-id.

NB: Your process-id will be different.

maurits@nuc:~$ sudo netstat -plant | grep :53
tcp        0      0  *               LISTEN      3101/dnsmasq
maurits@nuc:~$ sudo kill -9 3101

Now restart the dnsmasq service using “sudo service dnsmasq restart” to start the full dnsmasq without any problems. Now to make sure your connections will use your new resolver, you must make sure it is added to network connections. You do this by adding the “prepend domain-name-servers;” line to “/etc/dhcp/dhclient.conf”. After that you have to disconnect and reconnect all connections (also wired) or restart the network manager (which does the same) using “sudo service network-manager restart”. Now when you click on “Connection Information” in the network manager menu you should see that “Primary DNS” is set to “”.

NB: It is important you configure Apache to respond to the new “.dev” hostname in its virtualhost configuration. In our case we changed the servername to “ServerName leaseweblabs.dev” in “/etc/apache2/sites-available/leaseweblabs”. After modifying this you need to reload apache2 with “sudo service apache2 reload”.


By default, dnsmasq will look for upstream DNS servers when resolving. To debug this solution you may want to uncomment “#log-queries” in “/etc/dnsmasq.conf” and see in real-time what is happening using “tail -f /var/log/syslog”. You can also type “cat /run/resolvconf/interface/NetworkManager” at any time, to see what effective list of resolvers is being used. To force an update of the resolver configuration you can execute “resolvconf -u”, but this is normally not needed.

Use “dig leaseweblabs.dev” or “telnet leaseweblabs.dev 80” and do the same with a public website: “dig google.com” or “telnet google.com 80”. If there are answers to the “dig” requests and telnet connects successfully, you should probably be looking at your virtual host configuration.

Short instructions

$ sudo nano /etc/NetworkManager/NetworkManager.conf
- search for "dns=dnsmasq"
- replace with "#dns=dnsmasq"
$ sudo apt-get install dnsmasq
$ sudo nano /etc/dnsmasq.conf
- append line: "listen-address="
- append line: "bind-interfaces"
- append line: "address=/dev/"
$ sudo netstat -plant | grep :53
- look for "NUMBER/dnsmasq"
$ sudo kill -9 NUMBER
- fill in the number you found for "NUMBER"
$ sudo service dnsmasq restart
$ sudo nano /etc/dhcp/dhclient.conf
- append line: "prepend domain-name-servers;"
$ sudo service network-manager restart

Did you try this, but you didn’t succeed? Do you have improvements? Let me know!


21 thoughts on “Wildcard DNS in your Ubuntu hosts file using dnsmasq”

  1. I think the title is a bit misleading/incorrect. I thought this would make it possible to add wildcard entries to the hosts file.

  2. @Karel: Thank you for your comment. The title indeed implies something that is not possible. The blog suggests a workaround though. I hope you valued the post.

  3. How about registering a real domain name (for instance leaseweblabs-dev.com) for this? That will save you a lot of configuring. 😉

  4. @Mark: Thank you for your comment. Excellent out-of-the-box idea!

  5. I found your post quite useful and appreciate your taking the time to write it. Also, I’m cracking up at your politely snarky responses.

  6. If you bind-interfaces to lo you can run dnsmasq without affecting your other resolvers. This is helpful if you are running network bridges for virtual machines.

  7. Great write up of a simple idea that saves devs so much time.

    I thought I would add that you can use the Apache vhost_alias module to configure apache for wildcard domain matching. It allows you to create a sub directory for each wildcard domain and have it served up.

    So, your changes to dnsmasq make anything.dev and example.dev resolve to

    Then under Apache you can create a /var/www/dev document root and create anything and example in there. That’s all you need to do to have live sites on those domain names, no further changes the Apache config, no new vhost entries and no restarting Apache.

  8. It is possible to allow wildcards such as *.mydomain.com in DNSMasq, by editing, /etc/dnsmasq.conf and add line(s) like this


  9. Thank you very much, this is EXACTLY what I was seeking to successful create my local WordPress Multisite Development Environment.

  10. @RaMaEl: You are welcome, thank you for leaving a note.

  11. These are the simplest and most straigtforwad instructions I have found for setting up a wildcard DNS to use with WordPress on Ubuntu 14.04. Many thanks for publishing this as it has saved me hours of trying to workout how to set up dnsmasq(the full version).

  12. @Chris: Glad it helped you and thank you for leaving a note, it is much appreciated!

  13. NetworkManager’s slave dnsmasq is now configurable by `/etc/NetworkManager/dnsmasq.d/`.

    This should make things more simple.

  14. @Shahar: Thank you, great news! From which version on is it? What file do you add there and what should it contain?

  15. @John: Thank you for your comment. I do not think that that is a DNS problem. Are you listening on port 443?

  16. I’m trying to keep things isolated in docker containers. Do you think I could configure this in an ubuntu based, docker container, or this something I have to do on my local ubuntu? Thanks!

  17. @Monty: Good question! I believe this needs to be applied locally as your dnsmasq only answers local DNS queries.

Leave a Reply

Your email address will not be published. Required fields are marked *