Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A plugin to manage DNS records for vagrant environments
Ruby Shell


vagrant-dns allows you to configure a dns-server managing a development subdomain. It works much like pow, but manages Vagrant machines.


$ vagrant plugin install vagrant-dns


In addition to your networking config, configure a toplevel domain and a hostname for your machine. Optionally, configure a set of free matching patterns. Global configuration options can be given through the VagrantDNS::Config object:

Vagrant.configure("2") do |config|

  config.dns.tld = "dev"

  config.vm.hostname = "machine"

  config.dns.patterns = [/^.*$/, /^.*$/] :private_network, ip: ""

# optional
VagrantDNS::Config.logger ="dns.log")

Then, register the DNS server as a resolver:

$ vagrant dns --install

On OS X, this will create a file /etc/resolver/dev, which tells OS X to resolve the TLD .dev by using the nameserver given in this file. You will have to rerun --install every time a tld is added.

You can delete this file by running:

$ vagrant dns --uninstall

To also delete the created config file for this TLD (~/.vagrant.d/tmp/dns/resolver/dev in our example) run:

$ vagrant dns --purge

Then, run the DNS server:

$ vagrant dns --start

And test it:

$ scutil --dns
resolver #8
  domain   : dev
  nameserver[0] :
  port     : 5300
$ dscacheutil -q host -a name

You can now reach the server under the given domain.

Note: Mac OS X is quite different from Linux regarding DNS resolution. As a result, do not use dig or nslookup, but dscacheutil instead. Read this article for more information.

Finally, stop the server using:

$ vagrant dns --stop

The DNS server will start automatically once the first VM is started.

VM options

  • vm.dns.tld: Set the tld for the given virtual machine. No default.
  • vm.dns.tlds: Set multiple tlds. Default: [tld]
  • vm.dns.patterns: A list of domain patterns to match. Defaults to [/^.*{host_name}.{tld}$/]

Global Options

  • VagrantDNS::Config.listen: an Array of Arrays describing interfaces to bind to. Defaults to [[:udp, "", 5300]].
  • VagrantDNS::Config.auto_run: (re)start and reconfigure the server every time a machine is started. On by default.


  • A records only
  • No IPv6 support
  • OS X only (please read: Platform Support before ranting about this).
  • Not visible inside the box
Something went wrong with that request. Please try again.