Skip to content

Configuring nsd

nsd is an authoritative name server. nsd comes as part of openbsd base so no installation will be necessary.

Advantages of nsd:

Audited by the OpenBSD team

Simpler than BIND

Disadvantages of nsd:

More difficult to fork compared to delphinusdnsd

NOTICE: This guide assumes you have a basic understanding of [TCP/IP networking|openbsd/tcpip]], [IPv4|IPv4.Overview]] and [[IPv6|IPv6.Overview]] addressing, the [domain name system, [resource records, and [zone files. NOTICE: This guide assumes you have a basic understanding of [TCP/IP networking|openbsd/tcpip]], [IPv4|IPv4.Overview]] and [[IPv6|IPv6.Overview]] addressing, the [domain name system, [resource records, and [zone files.

Introduction

Please read through the [nsd|https://man.openbsd.org/nsd]], nsd.conf, [nsd-checkconf, and [nsd-control man pages. Please read through the [nsd|https://man.openbsd.org/nsd]], nsd.conf, [nsd-checkconf, and [nsd-control man pages.

nsd.conf

Edit these sections in /var/nsd/etc/nsd.conf:

server:
        hide-version: yes
        verbosity: 2
        database: "" # disable database
        username: _nsd
        logfile: "/var/log/nsd.log"

You'll want to hide the version, change verbosity to 2 to get errors and warnings about failed transfers. We don't want a database so we leave it blank, we drop to the user _nsd after binding the socket, and we want to log to /var/log/nsd.log.

## bind to a specific address/port
        ip-address: 198.51.100.1
#       ip-address: 192.0.2.53@5678
        ip-address: 2001:db8::

We bind to our public IPv4 address 198.51.100.1 and our public IPv6 address 2001:db8:: (substitute these with your real public IP addresses.md).

Note: If you forget your real public IP addresses, you can check [ifconfig|openbsd/ifconfig]], your hostname.if0, or check your [BuyVM or [VMM install guides. Note: If you forget your real public IP addresses, you can check [ifconfig|openbsd/ifconfig]], your hostname.if0, or check your [BuyVM or [VMM install guides.

remote-control:
        control-enable: yes
        control-interface: /var/run/nsd.sock

This will allow using nsd-control to control the server.

Master-Only Server

The DNS system requires you to specify master and slave servers. Internet standards require every zone to have at least two name servers, so you'll normally need to configure both a master and a slave.

To start off, we'll configure just a master name server. This will let us quickly test to see if our name server is working:

## master zone example
zone:
       name: "example.ircnow.org"
       zonefile: "master/example.ircnow.org"
#       notify: 192.0.2.1 NOKEY
#       provide-xfr: 192.0.2.1 NOKEY

We'll uncomment the zone. The name is the name of our domain or subdomain. It might look like username.fruit.ircnow.org or it could be a domain you registered, such as example.com. The zonefile might look like "master/username.fruit.ircnow.org" or "master/example.com" if you registered your own domain.

Write the Zone File

Write your DNS zone into the zone that you specified above, /var/nsd/zones/master/example.ircnow.org:

$ORIGIN example.ircnow.org.
example.ircnow.org.     3600   SOA   ns1.example.ircnow.org. admin.example.ircnow.org. (
                            2021020301   ; serial YYYYMMDDnn
                            1800        ; refresh
                            3600         ; retry
                            86400       ; expire
                            3600 )      ; minimum TTL
        3600    IN      MX      10 mail
        3600    IN      A       198.51.100.1
        3600    IN      AAAA    2001:db8::
        3600    IN      NS      ns1
        3600    IN      NS      ns2
ns1     3600    IN      A       198.51.100.1
        3600    IN      AAAA    2001:db8::
ns2     3600    IN      A       198.51.100.1
        3600    IN      AAAA    2001:db8::
www     3600    IN      A       198.51.100.1
        3600    IN      AAAA    2001:db8::
irc     3600    IN      A       198.51.100.1
        3600    IN      AAAA    2001:db8::
imap    3600    IN      A       198.51.100.1
        3600    IN      AAAA    2001:db8::
smtp    3600    IN      A       198.51.100.1
        3600    IN      AAAA    2001:db8::
mail    3600    IN      A       198.51.100.1
        3600    IN      AAAA    2001:db8::

For an explanation of how to interpret this zone file, please see the section on DNS zones.

Start NSD and Test

At this point, we can start nsd:

$ doas rcctl enable nsd
$ doas rcctl start nsd

If all was configured correctly, we should now be able to query our nameserver with host or [dig: If all was configured correctly, we should now be able to query our nameserver with host or [dig:

$ host www.example.ircnow.org example.ircnow.org
Using domain server:
Name: example.ircnow.org
Address: 198.51.100.1#53
Aliases: 
www.example.ircnow.org has address 198.51.100.1
www.example.ircnow.org has IPv6 address 2001:db8::

This will query the name server example.ircnow.org for the resource records in www.example.ircnow.org.

Delegate Zone

Once you've confirmed nsd works, you want to delegate authority for the zone to your nameserver. If you're using an ircnow.org subdomain, you'll need to ask the sysadmin in charge to finish this step. If you registered a domain elsewhere, make sure that the nameserver for the domain points to your nameserver (ns1.example.com and ns2.example.com) and that the glue records are defined.

Troubleshooting

If at any step you are not getting proper results, you should first check the conf and zones using these helpful tools:

$ doas nsd-checkconf /var/nsd/etc/nsd.conf
/var/nsd/etc/nsd.conf:34: at 'name:': error: syntax error
read /var/nsd/etc/nsd.conf failed: 1 errors in configuration file

The error is found on line 34 of /var/nsd/etc/nsd.conf:

#zone:
       name: "example.ircnow.org"
       zonefile: "master/example.ircnow.org"

Here we forgot to uncomment zone:. Once that is done, try again. If there are no errors, nsd-checkconf will not return any output -- no news is good news!

You'll also want to check if the zone is valid:

$ doas nsd-checkzone example.ircnow.org /var/nsd/zones/master/example.ircnow.org
[2021-02-02 03:49:14.921] nsd-checkzone[32265]: error: /var/nsd/zones/master/example.ircnow.org:8: out of zone data: out.of.zone.com. is outside the zone for fqdn example.ircnow.org.

The error is on line 8 of /var/nsd/zones/master/example.ircnow.org:

out.of.zone.example.com.        3600    IN      A       10.0.0.1

Here we specify a FQDN out.of.zone.example.com. which is outside of the zone for this file (example.ircnow.org). This is invalid so nsd refuses to look any further and quits. In this case, we need to delete this line (or perhaps move it to the proper zone file.md). Once that is done, run the test again:

$ doas nsd-checkzone example.ircnow.org /var/nsd/zones/master/example.ircnow.org
zone example.ircnow.org is ok

You can also run nsd in the foreground or view the logs:

$ doas nsd -d -V 3 
/var/nsd/etc/nsd.conf:34: at 'name:': error: syntax error
read /var/nsd/etc/nsd.conf failed: 1 errors in configuration file
[2021-02-02 03:33:50.261] nsd[93210]: error: could not read config: /var/nsd/etc/nsd.conf

This is the same error message as before when we ran nsd-checkconf above.

Suppose we had deleted /var/nsd/zones/master/example.ircnow.org. When we check /var/log/nsd.log, we see:

[2021-02-02 07:31:43.898] nsd[37575]: info: zonefile master/example.ircnow.org does not exist

Tip: Whenever you encounter an error with nsd, always check /var/log/nsd.log.

See Also

Nameserver Check