All the versions of this article: [English] [français]

Le 20/1/2012, 10:11
DNS & AlternC - How does it work?

Now that AlternC 1.0 is released, you know, that free software, control panel for web and mail hosting on Debian GNU/Linux, you may be interested in knowing that the DNS system has been completely rewritten by Alan, aka Fufroma.

Here are some explanations on the way the DNS works with AlternC 1.0 and later.

We will assume that your AlternC installation is at 1.0 or later, and that you installed your data in /var/alternc, which is the default.

AlternC has always based its DNS management on 2 tables : alternc.domaines and alternc.sub_domaines.

As those names are, the domaines table list the domains you are hosting. The gesdns field tells if the DNS are hosted on this server (or not). So a 0 means that bind will not host that domains’ DNS,

If the value is 1, bind will be authoritative for that zone, located in /var/alternc/bind/zones/

The zone file is, as almost every configuration in AlternC, created from a template located in

 /etc/alternc/templates/bind/templates/zone.template

After having created the file from the template, and substituted some variables (like %%fqdn%% during install time, and @@SERIAL@@ each time the zone is updated), AlternC make a list of the subdomains of the domain, and create the ressource record accordingly.

The DNS entries in sub_domaines

To create those records, we are using the domain types. This is one big news: with AlternC 1.0, you can create your own domain types.

Historically, we have 4 domain types in AlternC : hosting (which target is a folder in your webspace), webmail (pointing that subdomain to a webmail), IPv4 (pointing that subdomain to a specific IPv4 address) and http redirect (pointing to a folder where a .htaccess file redirect the user to another web page).

In AlternC 1.0 or later, those types can be customized and created through some files:

- a line in the domaines_types table.
- a template file that can exist in /etc/alternc/templates/apache2/
- a shell-script that can exist in /etc/alternc/functions_hosting

As a result, each domain type can define very precisely his behavior. We will not talk about it more here, we just talk about DNS, Domain Types in AlternC will likely be detailed in another article.

So, for each line in sub_domaines, we are referring to a specific domain type, defined in the "type" field.

Finally, in the domaines_types table, the "entry" field simply defines the text to enter in the DNS zone file.

This text can contain some variables that will be substituted at runtime

For example, %sub% will be substituted by the subdomain name, %TARGET% by the value of the target field in the sub_domaine table, and the variables enclosed in @@ are substituted from the /etc/alternc/local.sh configuration file (like @@PUBLIC_IP@@ for the public IPv4 of the server).

All that means that, using domaines_types, you can define any kind of domain type that will create an entry in the DNS zone, but you can even create many DNS entries at the same time, by entering many lines of text in that field!

Zone Reloading

When a user creates a subdomain, AlternC will (through its famous update_domaines.sh shell script) change the zone file. But we must tell him so. The field "dns_action" in the "domaines" table must be set to "UPDATE" to tell AlternC to recreate that zone file.

Si, if you want to ask AlternC to completely recreate a zone file for a domain, for example example.com, the following SQL query is enough :

# mysql alternc
mysql> UPDATE domaines SET dns_action="UPDATE" WHERE domaine="example.com";
Then you launch the update_domaines (don't need to wait for the cron):
# /usr/lib/alternc/update_domaines.sh

You will see that the zone file is completely rewritten each time that field is set. So, if you want to manually add some records in the zone, it looks like it’s not possible... But of course it is: Fufroma knows that you want to be able to edit your zone files manually!

Manually edit a zone file in AlternC

If you want to manage manually a DNS zone in AlternC, you can do it with 2 tricks :

- manage your entire zone file manually. In that case, AlternC will never touch that zone file again (unless you uninstall that domain name)
- manage some resource records manually, and don’t interfere with the SOA and the records created automatically by AlternC.

The first case is simple: each zone hosted by AlternC starts by a prologue like this one:

$TTL 1D
;
; BIND data file for domain @@DOMAINE@@
;
;; This file is automatically regenerate by Alternc
;; Please insert your manual entry after the last comment.
;; If you want to forbid automatic generation, change the LOCKED var
;; LOCKED:NO
;

So, just put LOCKED:YES in there, that’s all!

AlternC will never touch that zone file ever again.

That simple isn’t it?

Warning: when we are telling you that AlternC will never touch that zone ever again, it’s serious business: if you create edit or delete some subdomains in AlternC panel for this domain, the zone file will not be changed automatically! Do this only when you know what you are doing!

If you want to give the control back to AlternC for that zone, just set LOCKED to NO and ask AlternC to regenerate the zone (see earlier in that article)

The second case is also simple :) If you just want to manage some resource records manually, you can add them AFTER the last comment of the zone file.

This comment, if not present (notably for servers you upgraded from AlternC <1.0) can be added by yourself. It’s the following line :

;;; END ALTERNC AUTOGENERATE CONFIGURATION

The good news is that AlternC will never touch any line AFTER that comment. So, if you want to create some DNS records manually, just add them after that comment, change the serial number (+1) and launch as root : "rndc reload example.com"

That’s all folks!

As you can see, AlternC 1.0 brings a real flexibility to system administrors who want to be able to use automation provided by AlternC control panel, and be able to set manually some things at the same time!

What about IPv6?

Last point: I recently tried to patch AlternC for an extended support of IPv6. The first thing to do, and that works like a charm, is to edit the DNS entries created by the standard domain types: vhost url and webmail types.

I did it that way (this is an example with one of our servers’ IP):

# mysql alternc
mysql> UPDATE domaines_type SET entry="%SUB% IN A @@PUBLIC_IP@@\n%SUB% IN AAAA 2001:67c:288::6" WHERE type IN ("vhost","url","webmail");
mysql> UPDATE domaines SET dns_action="UPDATE";
# /usr/lib/alternc/update_domaines.sh

Warning: this example is provided without any guarantee :) however, I invite you to test that and to change it for good on June 5th 2012, so that all your website will be available using IPv6 on June 6th!