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

The Delphinusdnsd Handbook

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


  1. Constructing a structured config file
  2. Operating dd-convert
  3. Performing a ZSK Key Rollover
  4. Reverting back to BIND

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" {
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 ::1;
        port 53;
        versionstring "delphinusdnsd-sampleconfig 20171001";

axfr-for "these hosts" {

axfrport "10053";

notify "these hosts" {

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
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
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.

Performing a ZSK Key Rollover

in the last section we said that a key can't be rolled. As of 20180227 this is not true anymore (at least for ZSK). The code was written with the new dddctl utility. Basically dddctl is dd-convert with a few other functions. It introduces the -S flag which for the sign part allowing you to select which key to sign with based on the keytag (pid) to perform a pre-publish method key rollover. I have taken my test zone and rolled a new ZSK into it. The screenshot from looks like this after the new key was introduced:

The command to perform this was the following:

dddctl sign -z  -S 50093 -a 10 -B 2048 \
-k -z -i \
-n -o
As you can see -S selects key 50093.

After waiting for the time-to-live I'm going to re-sign with the new key. This means that I'm selecting (with -S) key 51263. It looks like so:

dddctl sign -z  -S 51263 -a 10 -B 2048 \
-k -z -i \
-n -o
The screenshot looks like this:

Finally the old key is discarded and this is what the final command is:

dddctl sign -z -k \
-i -n -o
We have successfully rolled the DNSSEC ZSK with the id 50093 to the new key with the id 51263.

I'm basing the process on how to do this on RFC 6781 section which has a Figure one which after reading this a little is straight forward.

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.

As of May 12th, 2018 there is two ways one can revert the zone file back to a BIND format. The recent "dddctl bindfile" method is the preferred way. Should this way have programming bugs and can't restore a BIND zone file there is the dig with AXFR method.

With dddctl the syntax is "dddctl bindfile domainname zonefile" and the output is on stdout. This method has been used in regression to check for anomalies with other DNS software verification tools.

In dig you can convert 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.

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, and now you can revert.