There is preliminary support for DNS in Aegir's backend that allows it to manage zonefiles dynamically when sites are created. There are still a few major bits missing (described in this meta-ticket) so we generally recommend people use the wildcard approach for now.

That said, while perhaps not yet ready for production use, Aegir's DNS functionality can be quite useful for local development environments. If you run Aegir locally, you're probably in the habit of hacking /etc/hosts regularly, or if you're more adventurous, you've set up a local DNS forwarder, such as dnsmasq. With Aegir's DNS feature, you can avoid this hassle, and let Aegir handle it transparently.

While Aegir supports both BIND and dnsmasq, this documentation will focus on the former. The first step is to install BIND. On Debian-based distros, this will look like:

apt-get install bind9

Next we need to allow the aegir user to run rndc (the name server control utility). On recent Debian systems, this will involve editing /etc/sudoers.d/aegir, whereas on older releases this would be /etc/sudoers. Modify the aegir line to read:

aegir ALL=NOPASSWD: /usr/sbin/apache2ctl, /usr/sbin/rndc

Then we need to make sure the bind user has access to read Aegir's files, so we'll add bind to the aegir group:

adduser bind aegir

We're now ready to activate the feature in Aegir's frontend. Go to Hosting >> Features (admin/hosting/features) and select "DNS Support" under the "Experimental" fieldset, and save the configuration.

Finally, we need to activate DNS on the Aegir server. Visit the server node (hosting/c/server_master) and click the edit tab (which should bring you to node/2/edit). Then under "DNS Service", select "Bind" and then save.

This should trigger a verify of the server (and then probably the platforms on it too), after which Aegir will be managing your local BIND server, and it's zonefile(s). If you have installed Aegir in /var/aegir, put this line in the file /etc/bind/named.conf.local:

include "/var/aegir/config/bind.conf";

Aegir is now a full-fledged DNS server that you can use to resolve addresses locally. This can be accomplished on Debian-like systems by editing /etc/resolv.conf to include "nameserver". If you're running Aegir in a VM, you can just point this to the address of the virtual machine.


You need to have a working DNS/bind/named server for AEgir to take control of. What follows is rough documentation to reach that stage. It is currently UNTESTED in a production environment.

yum -y install bind-chroot bind-utils bind-libs bind
chkconfig named on
ln -s /var/named/chroot/var/named/named.conf /etc/named.conf
cat >> /etc/named.conf << EOF
controls {
        inet allow {
} keys {
options {
        listen-on port 53 { any; };
        listen-on-v6 port 53 { ::1; };
        directory       "/var/named";
        dump-file       "/var/named/data/cache_dump.db";
        statistics-file "/var/named/data/named_stats.txt";
        memstatistics-file "/var/named/data/named_mem_stats.txt";

        // Those options should be used carefully because they disable port
        // randomization
        // query-source    port 53;
        // query-source-v6 port 53;
        forwarders {; };
        forward only;
//      allow-query     { localhost; };
//      allow-query-cache { localhost; };

logging {
        channel default_debug {
                file "data/named.run";
                severity dynamic;

view localhost_resolver {
        match-clients      { any; };
        match-destinations { any; };
        recursion yes;
        include "/etc/named.rfc1912.zones";

    // Add local zone definitions here.

    include "/var/aegir/config/bind.conf";

include "/etc/rndc.key";
service named start

Additional Notes

Additional documentation can be found in the Provision DNS module: http://drupalcode.org/project/provision.git/blob/HEAD:/dns/NOTES.

DNS Wildcard Configuration

Why run a wildcard DNS server?

A wildcard DNS setup lets you automatically have subdomains for a given domain. For example, say you own the domain widgets.com and you want to setup an unlimited number of subdomains like dev.widgets.com, test.widgets.com, customers.widgets.com, etc.... Typically you would have to set these all up individually. A wildcard DNS can let you bypass a lot of configuration. In a development environment it can let you setup any number of test/development sites very quickly and easily. Drupal developers in particular can leverage Drupal's multisite installation feature to setup lots of sites for development or production very quickly.

Creating a DNS wildcard with hosted DNS

Many of the popular domain registration companies allow you to manage your DNS records through a web interface. If you have access to such a facility, adding a DNS wildcard is easy: you just create an A record called '*', pointing to your server's IP address.

For convenience, here are instructions for some popular hosting providers: GoDaddy, hosting.com (which uses the popular cPanel system) and 123-reg.co.uk. It is likely that your host will have a similar system to one of these.

How to configure DNS wildcards on your own server


OS X Snow Leopard

Setting up a Wildcard DNS configuration on Ubuntu/Debian

Overview of Steps on Ubuntu/Debian

I. Install Bind 9 II. Add a zone to /etc/bind/named.conf.local. Check the syntax of named.conf.local with named-checkconf III. Add a zone file & Check the syntax of your zone files for errors with named-checkzone IV. Edit /etc/resolv.conf V. Start up Bind VI. Check setup with dig VII. Troubleshoot if needed

I. Install Bind 9

$ sudo apt-get install bind9

II. Edit /etc/bind/named.conf.local to add a zone.

We need to add a zone to /etc/bind/named.conf.local. A zone is a record for a domain. In this case we'll use a fake domain for development purposes. Our domain can be called anything. Let's call it mydev. (I was really tempted to call the domain bullshit - would have been great for screencasts). So at a shell prompt do:

$ sudo nano /etc/bind/named.conf.local

Add this to the end of the file:

zone "mydev" {
type master;
   file "/etc/bind/db.mydev";

Save the file with Control - O and enter. Exit from nano with Control X.

Check the syntax of the file as follows:

$ named-checkconf /etc/bind/named.conf.local

If the file is syntactically correct the shell prompt will return nothing. If there is an error - make sure you did not miss a quote or semicolon and recheck the file.

III. Add a zone file & Check the syntax of your zone files for errors with named-checkzone

$ sudo nano /etc/bind/db.mydev

Add this to the file replacing with your IP address

mydev. 86400 IN SOA mydev. hostmaster.mydev. (
               20091028 ; serial yyyy-mm-dd
               10800; refresh every 15 min
                3600; retry every hour
                 3600000; expire after 1 month +
                86400 ); min ttl of 1 day
  IN NS mydev.
          IN MX 10 mydev.
        IN A
*.mydev. IN A

Save the file with Control - O and enter. Exit from nano with Control X. Check the syntax with the following:

$ named-checkzone mydev /etc/bind/db.mydev

If the syntax of the file is correct you should see something like:

zone mydev/IN: loaded serial 20091028

If not review the file for errors. In particular whenever referring to a domain, it must end in a . , thus mydev.

IV. Edit /etc/resolv.conf

resolv.conf tells applications like browsers where to look for DNS info. By default it may have your ISPs info. We need to tell it to check our local DNS server first then the ISP.

$ sudo nano /etc/resolv.conf

Add/change the following

domain mydev
search mydev
nameserver (your isp nameserver or open dns)

If you are receiving an IP address via DHCP then you need to edit /etc/dhcp3/dhclient.conf too.

$ sudo nano  /etc/dhcp3/dhclient.conf

Look for the lines send host-name, supersede domain-name, and prepend domain-name-servers and set them as follows (and make sure they are uncommented ) :

send host-name "mydev";
supersede domain-name "mydev";
prepend domain-name-servers;
sudo dhclient

Whew! Almost there.

V. Start up Bind (or Restart)

$ sudo /etc/init.d/bind9 restart

VI. Check setup with ping and dig

$  ping testing.mydev
PING testing.mydev ( 56(84) bytes of data.
64 bytes from ubuntu.local ( icmp_seq=1 ttl=64 time=0.041 ms
64 bytes from ubuntu.local ( icmp_seq=2 ttl=64 time=0.039 ms
64 bytes from ubuntu.local ( icmp_seq=3 ttl=64 time=0.0

If ping works then you should be good to go. If not try dig and part V. To stop the ping action press [Ctrl]+[c].

VII. Troubleshoot

I found the section on Troubleshooting Bind in O'Reilly's "Linux System Administration" helpful. Fortunately, this part of the book is viewable on Google books as of this writing (10/29/2009): http://books.google.com/books?id=-jYe2k1p5tIC&lpg=PP1&dq=Linux%20System%... . See page 66

Getting a Wildcard DNS running on OSX Snow Leopard

Note: it took me several tries to get this working. If you are new to DNS be patient with yourself - you'll get it, but may take a few tries.

In this example I will concentrate on setting a development environment with OSX using wildcard DNS

Overview of Steps

I. Edit /etc/named.conf to add a zone.
II. Add a zone file at /var/named/ III. Check the syntax of named.conf and your zone files for errors IV. Edit /etc/resolv.conf V. Set your computers network settings to use as a name server VI. Start up Bind VII. Check setup with dig VIII. Reboot if needed

Before we start a few more notes.

I tend to use the nano text editor to edit Unix configuration files you could use Emacs, VI, Textmate, BBEdit or the editor of your choice.

Backup all these files we are editing so you can start over if you mess up. I didn't do this and it added more time to the project. For example to backup /etc/named.conf do:

$ sudo cp /etc/named.conf /etc/named.conf.bck

Last, most of the files we need to edit are owned by root so you will need to use sudo to edit these files. If you get tired of typing sudo you can become root by doing this:

$ sudo -s

Be careful when working as root or using sudo. You can mess up your system so make sure to backup. All example here are run as root.

I. Edit /etc/named.conf to add a zone

We need to edit named.conf to add our zone.

$ nano /etc/named.conf

I called my zone vmdev so I added this to named.conf

zone "vmdev" IN {
        type master;
        file "db.vmdev";

I added this right before the zone 0.0.127.inaddr.apra and saved the file. So we told Bind to look in /var/named/db.vmdev for this zone.

II. Add a zone file at /var/named/

$ nano /var/named/db.vmdev
vmdev. 7200    IN       SOA     vmdev. root.vmdev. (
                                        2008031801 ;    Serial
                                        15      ; Refresh every 15 minutes
                                        3600    ; Retry every hour
                                        3000000 ; Expire after a month+
                                        86400 ) ; Minimum ttl of 1 day
                IN      NS      vmdev.
                IN      MX      10 vmdev.

                IN      A
*.vmdev.        IN      A

You can just copy this but be sure to change to you Mac's IP address

III. Check the syntax of named.conf and your zone files for errors

Run this to check your named.conf file:

$ named-checkconf /etc/named.conf 

If it returns nothing, your named.conf file is at least syntactically correct. If there is an error, then well you have to diagnose and fix the error.

Now run this to check your zone file:

$ named-checkzone vmdev /var/named/db.vmdev

It should return something like this:

zone vmdev/IN: loaded serial 2008031801

If there are errors then diagnose and fix them.

IV. Edit /etc/resolv.conf

$ nano /etc/resolv.conf
# Mac OS X Notice
# This file is not used by the host name and address resolution
# or the DNS query routing mechanisms used by most processes on
# this Mac OS X system.
# This file is automatically generated.
domain vmdev.

V. Set your computers network settings to use as a name server

Do this at System Preferences -> Network. You may want to use your ISPs Name server as the second name server

VI. Start up Bind

$ launchctl load -w /System/Library/LaunchDaemons/org.isc.named.plist

The -w option tells OSX to enable Bind at startup

VII. Check setup with dig

$ dig faker.vmdev 

Should return something like this:

; <<>> DiG 9.6.0-APPLE-P2 <<>> faker.vmdev
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 45640
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 1

;faker.vmdev.                   IN      A

faker.vmdev.            7200    IN      A

vmdev.                  7200    IN      NS      vmdev.

vmdev.                  7200    IN      A

;; Query time: 0 msec
;; WHEN: Wed Oct 14 19:28:56 2009
;; MSG SIZE  rcvd: 75

The key here is status NOERROR; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 45640 If you get an error then check previous steps.

Now try:

$ ping faker.vmdev

should return:

PING test.vmdev ( 56 data bytes
64 bytes from icmp_seq=0 ttl=64 time=0.059 ms
64 bytes from icmp_seq=1 ttl=64 time=0.087 ms

but if it does not got to VIII.

VIII. Reboot if needed.

I needed to reboot to get everything to take. Whoila! Have a cookie or something.