DELPHINUSDNSD    

Index | About | Source | News | Credits | Handbook | Implementation


The Delphinusdnsd Handbook

Here I'm going to explain how to use delphinusdnsd.

Constructing a structured config file

In the configuration, delphinusdnsd breaks the RFC 1034/1035 protocol by syntax of the zone configuration file. We use a CSV format for storing the config file. So a minimum zone config may look like:
zone "myzone.tld" {
	myzone.tld,soa,86400,ns1.myzone.tld.,hostmaster.myzone.tld.,2017083002,3600,1200,1209600,86400
	myzone.tld,a,86400,172.16.0.1
}
A SOA RR should always be present. Notice the trailing .'s, in delphinusdnsd they can be omitted or placed, it doesn't matter. It matters however that every hostname must be expanded completely, it can't be relative to @ like in BIND.

So how does a real running delphinusdnsd look like? Obviously a zone config file is not the only thing that we need for configuration... Here is an attempt at a config file (in /etc/delphinusdns.conf):

; sample config file that is in production.
;
version "7";

options "sample config" {
        ratelimit-pps 12;
        bind 127.0.0.1;
        bind ::1;
        port 53;
        log;
        dnssec;
        versionstring "delphinusdnsd-sampleconfig 20171001";
}

axfr-for "these hosts" {
        ::1/128;
        127.0.0.1/32;
}

axfrport "10053";

notify "these hosts" {
        ::1;
}

include "/etc/delphinusdns/myzone.tld.signed";
As you can see the myzone.tld.signed file is "include"'ed. This is important for a structured config. We can include the myzone.tld.signed file right in the config file itself but there is obvious benefits to the way it is shown here. For example when using the dd-convert tool that comes with delphinusdns one can only sign one zone, so it may as well be placed in a file called "myzone.tld".


Operating dd-convert

DNSSEC came to delphinusdnsd a few years ago. Our implementation is somewhat incomplete but we gotta do the best of it as we can. And as time becomes available more completeness will happen. To make delphinusdnsd zones be DNSSEC aware the option "dnssec;" must be placed in the delphinusdns config file. Also the zones will have to be "signed" with dd-convert, in order to produce DNSKEY, RRSIG etc resource records. A delphinusdnsd with the dnssec option can also serve non-signed zones or a mix of both.

Signing a zone

Let's look at what we must do to create 2 keys (ZSK and KSK) and sign a zone. A KSK is a key-signing key, and a ZSK is a zone-signing key, for those that need help in the basics of DNSSEC.

omega$ ls
myzone.tld run
omega$ cat run
dd-convert -K -Z -i myzone.tld -n myzone.tld -o myzone.tld.signed
omega$ sh run
omega$ ls -clrt
total 40
-rw-r--r--  1 pjp  pjp   149 Oct  1 11:16 myzone.tld
-rw-r--r--  1 pjp  pjp    66 Oct  1 11:18 run
-rw-------  1 pjp  pjp  1776 Oct  1 11:18 Kmyzone.tld.+008+50056.private
-rw-r--r--  1 pjp  pjp   602 Oct  1 11:18 Kmyzone.tld.+008+50056.key
-rw-------  1 pjp  pjp  1776 Oct  1 11:18 Kmyzone.tld.+008+48846.private
-rw-r--r--  1 pjp  pjp   603 Oct  1 11:18 Kmyzone.tld.+008+48846.key
-rw-r--r--  1 pjp  pjp  3821 Oct  1 11:18 myzone.tld.signed
-rw-r--r--  1 pjp  pjp   164 Oct  1 11:18 dsset-myzone.tld.

The run file contains the dd-convert command with -Z and -K options. These create a ZSK and a KSK respectively. As you can see one key-pair is named Kmyzone.tld.+008+50056.private and Kmyzone.tld+008+50056.key, looking into this file we see the following:

omega$ more Kmyzone.tld.+008+50056.key
; This is a key-signing key, keyid 50056, for myzone.tld.
; Created: 20171001091849 (Sun Oct  1 09:18:49 2017)
; Publish: 20171001091849 (Sun Oct  1 09:18:49 2017)
; Activate: 20171001091849 (Sun Oct  1 09:18:49 2017)
myzone.tld. 3600 IN DNSKEY 257 3 8 AwEAAeD5dm+18GCIR4fiI8peU4zNY3JuH7zpLemabRBF
m5gmInKz4XmlqeoUjpiXDv03vZEy39tC3Up/KHjX2nkA0uxvTIRyGXbheNfSbh+f+1Krl1kr2qSqB8k
h3OYrI5Ykf6yQz9E1B7woXgK8waK1N3zukv4l6nXqGfoHTWAr5NR9S4ofuRsOtV11SlV0fc6X+gXF+m
e4OtREd4mkf9Kle1dzmzAE6VBiaYaASPpJ4Y6UuKj+SHS0U94W0sFKeG/3IGObA+cIx4qCBgHg7b0qq
IggQFYywAsw3mEpLIz5pPbXT1iFakLsuyt1xDotuCLPWSUloHAU5pJZnK8TYqMZlhc=
So we now know that the KEY pair that has the 50056 identifier is the KSK. This is important for the future when we re-sign the zone. The .key files can be shared with anyone in the public, the .private keys must be kept secret as they contain sensitive values. Sharing a .private key is like sharing the password to DNSSEC.

We also have a myzone.tld.signed file, this is the DNSSEC zone file for the myzone.tld zone. A dsset-myzone.tld file exists as well. This one can be shared with the registrar or upstream zone (the one that delegates for you) as it's the DS record.

omega$ more dsset-myzone.tld.                                                  
myzone.tld.             IN DS 50056 8 1 02ACF5A6360729E8E720F2C3EC28029E0165CA2B
myzone.tld.             IN DS 50056 8 2 BDC432E84E0556B85DEDA06B7845623047E2A060
566177BC4543986A0EC4BE0C
Sometimes the registrar asks you for the .key file contents (DNSKEY) of the KSK, this is alright since the DS key can be derived from a DNSKEY record, and you're not revealing anything. (just keep the .private key to yourself).

Once these are done, we can give it a spin. Copy the .signed zone file to /etc/delphinusdns/myzone.tld.signed and start/restart delphinusdnsd.

Re-Signing a Zone

For re-signing we need to change the "run" file by replacing the -Z and -K flags with -z Kmyzone.tld.+008+48846 and -k Kmyzone.tld.+008+50056 respectively. So it looks like this:
omega$ cat run
dd-convert -z Kmyzone.tld.+008+48846 -k Kmyzone.tld.+008+50056 -i myzone.tld -n myzone.tld -o myzone.tld.signed
omega$ sh run
omega$ ls -lcrt
total 40
-rw-r--r--  1 pjp  pjp   149 Oct  1 11:16 myzone.tld
-rw-------  1 pjp  pjp  1776 Oct  1 11:18 Kmyzone.tld.+008+50056.private
-rw-r--r--  1 pjp  pjp   602 Oct  1 11:18 Kmyzone.tld.+008+50056.key
-rw-------  1 pjp  pjp  1776 Oct  1 11:18 Kmyzone.tld.+008+48846.private
-rw-r--r--  1 pjp  pjp   603 Oct  1 11:18 Kmyzone.tld.+008+48846.key
-rw-r--r--  1 pjp  pjp   112 Oct  1 11:41 run
-rw-r--r--  1 pjp  pjp  3821 Oct  1 11:41 myzone.tld.signed
-rw-r--r--  1 pjp  pjp   164 Oct  1 11:41 dsset-myzone.tld.
As you can see by the ls flags that run, myzone.tld.signed and dsset-myzone.tld have changed. The dsset-myzone.tld file doesn't really change but it is re- created anew every run. Also what we didn't do is edit the SOA RR in myzone.tld to re-sign. This must be done, give it a higher sequence value. The sequence value is what we had originally called "2017083002", increasing this by one will work, or you could see that it is a date and change it to the appropriate date.

At this point the "run" file does not have to be changed again in order to re-sign. In future versions of delphinusdnsd there may be key-rollover'ing which will change the syntax minutely. But we're not there yet unfortunately. Also note that with time the private key becomes weaker, since we can't introduce a new key we're stuck with this one until the code is written. This must be mentioned.


Reverting back to BIND

Unfortunately delphinusdnsd is not complete. For those that wander to us and run it, and then realise they need a certain feature there is a way to go back. You can convert (with dig) a delphinusdnsd config file to BIND format, just make an AXFR transfer and modify it by taking out the trailing SOA record. You now have a BIND config file. Also the dd-convert keys are shaped after BIND tools so you should be able to reuse them without changing them much. Another option of course is to make delphinusdnsd a hidden master that only serves AXFR's, but it won't help much when you absolutely need to change a DNSSEC key for example. As a last word, we were built with our own goals in mind not others, hence you may find something that you don't like perhaps.