DDNSadmin

This is a web interface for DNS zone management using TSIG keys (RFC2845). To use it you must have a valid TSIG key and configure your DNS zone master name server to allow AXFR and DDNS requests signed by your key.

DNS management interface is split in two parts - frontend written in JavaScript and backend written in PHP.

Backend is completely stateless and is used only to convert HTTP requests to DNS queries. Single backend can be safely used by multiple users managing different DNS zones.

To try it out, drop index.html, ddnsadmin.js, dnsproxy.php and Net.phar to your PHP enabled web server and navigate your browser to index.html.

To try it out on local machine without a full blown web server you can use PHP built-in web server. Start it from this project directory, with:

php -S 127.0.0.1:8080

And point your browser to http://127.0.0.1:8080/.

Frontend settings

Backend does not require any initial setup and can be used as it is. On the frontend user have following settings:

• DNS zone - Domain name of zone that is being managed, example: example.net
• Key name - Name of key that is used to sign DNS requests, must be the identical to the key name configured on a DNS server, example: key.example.net.
• Key type - Algorithm that is used to generate signature, must be the same as configured on a DNS server, example: sha512
• Key - Secret key used to sign requests, must be base64 encoded, example: UNhY4JhezH9gQYqvDMWrWH9CwlcKiECVqejMrND2VFw=

Advanced settings:

• DNS Server - IP address of zone master name server. DNS requests are being sent to this address. This field is filled usually automatically after DNS zone is entered. It can be entered manually if system fails to detect it automatically.
• Proxy URL - Backend URL (relative or absolute). Default is search for backend on the same web server, same directory. It should be changed if backend and frontend are on different web servers.
• Filter RRs - List of resource record types (comma separated) to filter out before displaying zone records.

System architecture

Frontend files:

• index.html
• ddnsadmin.js

Backend files:

• dnsproxy.php
• Net.phar (file) or Net (directory) for Net_DNS2 library

+--------------+         +--------------+      +------------+
|              | HTTP/S  |              | DNS  |            |
| Web browser  |-------->| PHP backend  |----->| Master     |
|              |         |              |      | Nameserver |
| index.html   |<--------| dnsproxy.php |<-----|            |
| ddnsadmin.js |    ^    | Net.phar     |   ^  |            |
+--------------+    |    +--------------+   |  +------------+
                    |                       |
   JSON request over HTTP (key is send      |
   in plaintext here, except for HTTPS)     |
                                            |
                           Signed DNS request (AXFR or DNS update)
                       (key is not sent here, only request signature)

In each request frontend passes your zone key to the backend. It is important to use HTTPS or start backend on your local machine using PHP built-in web server to avoid eavesdropping.

Net_DNS2

Backend uses Net_DNS2 library for DNS packet crafting. This repository includes Net.phar archive of Net_DNS2 library files.

Backend checks for Net.phar archive or Net directory for library sources.

If you do not trust bundled Net.phar archive you can easily download library code from upstream and use sources directly or pack your own Net.phar archive.

There is Makefile with library download and packing code. To delete provided Net.phar archive and download library sources following commands:

make clean      # Remove Net.phar and library sources
make Net        # Download and extract library sources

To build your own Net.phar use commands:

make            # Create Net.phar
make distclean  # Delete library sources

DNS server configuration examples

Key generation

Generate a new random key (256 bit length) and base64 encode it:

$ dd if=/dev/urandom bs=32 count=1 2>/dev/null | base64
UNhY4JhezH9gQYqvDMWrWH9CwlcKiECVqejMrND2VFw=

In the examples below we will use sha512 HMAC algorithm and will name our key uberkey.

TSIG key information summary:

Key name: uberkey

Key type: hmac-sha512

Key: UNhY4JhezH9gQYqvDMWrWH9CwlcKiECVqejMrND2VFw=

Bind 9 DNS server

Bind 9 configuration snippet for "example.net" zone:

key uberkey {
	algorithm hmac-sha512;
	secret "UNhY4JhezH9gQYqvDMWrWH9CwlcKiECVqejMrND2VFw=";
};
zone "example.net" {
	type master;
	file "/etc/bind/db.example.net";
	allow-transfer { key uberkey; };
	allow-update { key uberkey; };
};

PowerDNS server configuration

Zone transfer (AXFR) with TSIG key is supported since PowerDNS server 3.0. Documentation.

DDNS updates with TSIG key is supported since PowerDNS server 3.4. Documentation.

Knot DNS server

Knot configuration snippet for "example.net" zone:

keys {
  uberkey hmac-sha512 "UNhY4JhezH9gQYqvDMWrWH9CwlcKiECVqejMrND2VFw=";
}
remotes {
  any-with-key {
    address 0.0.0.0/0;
    key uberkey;
  }
}
zones {
  example.net {
    file "/etc/knot/example.net.zone";
    xfr-out any-with-key;
    update-in any-with-key;
  }
}

YADIFA DNS server

YADIFA configuration snippet for "example.net" zone:

<key>
	name       uberkey
	algorithm  hmac-md5
	secret     UNhY4JhezH9gQYqvDMWrWH9CwlcKiECVqejMrND2VFw=
</key>
<zone>
	type            master
	domain          example.net
	file            example.net.zone
	allow-transfer  key uberkey
	allow-update    key uberkey
</zone>

Note! YADIFA 1.0.3 supports only hmac-md5 TSIG key algorithm!

Configuration testing

To test your name server configuration you can perform AXFR queries using dig tool and DDNS updates using nsupdate tool.

Perform AXFR using dig:

$ dig -y hmac-sha512:uberkey:UNhY4JhezH9gQYqvDMWrWH9CwlcKiECVqejMrND2VFw= -t axfr example.net @127.0.0.1

Perform DDNS update using nsupdate:

$ nsupdate -y hmac-sha512:uberkey:UNhY4JhezH9gQYqvDMWrWH9CwlcKiECVqejMrND2VFw=
> server 127.0.0.1
> zone example.net
> update add ddnstest.example.net 300 IN A 192.0.2.1
> send
> quit

If nsupdate do not print any error messages it means DDNS update was performed successfully.

In both examples replace 127.0.0.1 with your name server IP address.