NSNOTIFYD(1) General Commands Manual NSNOTIFYD(1) NAME nsnotifyd -- handle DNS NOTIFY messages by running a command SYNOPSIS nsnotifyd [-46dtVw] [-l facility] [-P pidfile] [-u user] [-R min:max] [-r min:max] [-T max] [-S authority] [-s authority] [-a addr] [-p port] <command> <zone>... DESCRIPTION The nsnotifyd daemon monitors a set of DNS zones and runs a command when any of them change. It listens for DNS NOTIFY messages so it can respond to changes promptly. It also uses each zone's SOA refresh and retry para- meters to poll for updates if nsnotifyd does not receive NOTIFY messages more frequently. The root zone can be specified as `.' or `root'. Note: nsnotify (without `d') is a client for sending DNS NOTIFY messages whereas nsnotifyd (with `d') is a daemon for handling DNS NOTIFY messages. OPTIONS -4 Use IPv4 only (apart from the system resolver). -6 Use IPv6 only (apart from the system resolver). -a address Listen on address for NOTIFY messages. The default is 127.0.0.1. You can specify an IP address or hostname. A hostname is looked up using the system resolver. If it resolves to multiple addresses then one arbitrary address is chosen, constrained by the -4 or -6 options. -d Debugging mode. Use once to prevent nsnotifyd from daemonizing and to make it print log messages to stderr. Use twice to get dumps of DNS packets. -l facility Set the syslog(3) facility. The default is daemon. -P path Write the nsnotifyd PID to the given path after daemonizing and be- fore dropping privilege. -p port Listen on port, which may be a service name or a port number. The default is the domain service, port 53. -R interval Override SOA refresh interval. -R min:max Restrict SOA refresh intervals to be between min and max. -r interval Override SOA retry interval. -r min:max Restrict SOA retry intervals to be between min and max. -S authority The authoritative server to use for SOA queries following NOTIFY messages and for periodic zone refreshes. You can specify an IP address or hostname. A hostname is looked up using the system resolver, constrained by the -4 or -6 options. -s authority Like the -S option, but the authoritative server is used for peri- odic zone refresh SOA queries only. -T interval Set the read timeout for TCP connections. -t Listen for TCP connections instead of UDP. -u user Drop privilege to user after daemonizing. -V Print details about this version of nsnotifyd. -w Accept NOTIFY messages for unknown zones that are not given on the command line. (Wildcard mode.) Interval syntax Time parameters for the -T, -R and -r options are in seconds, or you can use a combination of the following time units, as in DNS master files. For example, 1h1m1s is 3661 seconds. The usage message printed by nsnotifyd -? includes the default intervals. w weeks d days h hours m minutes s seconds DETAILS Startup Before daemonizing, nsnotifyd makes SOA queries for each zone to initialize its refresh and retry timers. Daemonizing is configured using the -P pidfile and -u user options, or dis- abled with the -d debugging option. When daemonizing, nsnotifyd does not change its working directory. This allows the command to be context-sensitive. Server The nsnotifyd daemon acts as a very simple UDP-only or TCP-only DNS server. (BIND sends NOTIFY messages over UDP, whereas Knot DNS uses TCP.) If you need to support both UDP and TCP, you can run two copies of nsnotifyd with and without the -t option. The only DNS queries handled by nsnotifyd are NOTIFY messages. It rejects other queries with a REFUSED response code, or FORMERR if the query is too mangled. In UDP-only mode (the default), nsnotifyd handles one query at a time, which includes waiting for the script to finish. In TCP-only mode (the -t option), nsnotifyd accepts one TCP connection at a time, and handles one query at a time on that connection in a similar manner to UDP-only mode. The TCP connection is dropped if a complete request does not arrive within the -T read timeout interval. Normally nsnotifyd only accepts NOTIFY messages for zones given on the com- mand line. NOTIFY messages are accepted for unknown zones if you use the -w wildcard option. Messages are logged via syslog(3). Zone refresh When nsnotifyd receives a NOTIFY, it sends a SOA query to the source of the NOTIFY to find out if the zone has changed. When a refresh or retry timer expires, it makes a SOA query using the system recursive resolver (which can return a cached response). Alternatively, the -S and -s options spec- ify the authoritative server to use for notified and/or refresh queries. If the NOTIFY message was accepted for an unknown zone because you used the -w wildcard option, nsnotifyd makes a SOA query to verify the zone exists and to get its serial number, and runs the command if it succeeds. (It is unable to verify the zone has changed in this case.) Some jitter is applied to SOA refresh and retry timers, so polling can oc- cur up to 10% earlier than specified. Command invocation When the SOA reply indicates the zone's serial number has increased, nsnotifyd runs the command with two or three arguments: 1. the zone name without the trailing dot, except for the root zone `.'; 2. its new serial number; 3. the source address of the NOTIFY, or no third argument if the update was found via a periodic refresh or retry. When the command exits successfully, nsnotifyd updates its copy of the zone's SOA parameters. It will next poll the zone on its refresh interval. If the SOA query or command fails, nsnotifyd does not update its SOA para- meters, and and will next poll the zone on its retry interval. Unknown zones that were not mentioned on the command line are not polled. Performance considerations The speed of your command determines how fast nsnotifyd can process NOTIFY messages. When NOTIFYs arrive faster than they can be processed, nsnotifyd relies on network buffers to hold the queue of pending requests. The time to clear the queue is the average command running time multiplied by the length of the queue. This time is also the maximum latency between sending a NOTIFY request and receiving a response from nsnotifyd. For example, if you rapidly update 100 zones, and your command takes about 1 second to run, nsnotifyd will take about 1 minute and 40 seconds to process the queue and respond to the last NOTIFY. You should aim to keep this maximum latency (your command running time times your NOTIFY batch size) less than your DNS server's NOTIFY timeout. If your command is too slow, you can alter it to fork and do the bulk of its work in the background, but then you are responsible for avoiding a forkbomb. You might limit how many NOTIFY messages your DNS server sends at once, or alter your command to limit its own concurrency. EXAMPLE - metazones Metazones allow you to use standard DNS mechanisms - AXFR, IXFR, NOTIFY, UPDATE - to control the configuration of multiple name servers, instead of using a separate out-of-band distribution system. For details, see the metazone(1) manual. EXAMPLE - zone revision history Say you have a zone, example.org, which is updated dynamically, and you want to automatically record its history in a git(1) repository. Setup git On a server that is authoritative for example.org, run the following com- mands: $ mkdir zone-history $ cd zone-history $ git init $ touch example.org $ git add example.org $ git commit -m 'add example.org (empty)' Monitor the zone The nsnotify2git script is designed to work with nsnotifyd to record the history of a set of zones. Continuing the transcript, $ nsnotifyd -P nsnotifyd.pid -p 5309 nsnotify2git example.org Send notifies To configure BIND to send notifies to nsnotifyd, so it detects changes more efficiently, look in your named.conf(5) file for zone example.org { ... }; Inside the zone clause, add or modify the `also-notify' setting so it in- cludes the address and port used by nsnotifyd, like also-notify { 127.0.0.1 port 5309; }; Update the zone Now, when the zone changes, nsnotifyd will quickly record the change in your git repository. $ nsupdate -l > add example.com 3600 IN TXT "foo" > send > quit $ git log --format=%s example.org IN SOA 1234 add example.org (empty) EXAMPLE - stealth secondary synchronization A stealth secondary is a server which transfers authoritative copies of a zone, but which is not listed in the zone's NS records. It will not nor- mally get NOTIFY messages to tell it when to update the zone, so must rely on the zone's SOA timers instead. We would like stealth secondaries to get updates promptly, but without ex- tra manual configuration of `also-notify' lists. To do this, nsnotifyd includes nsnotify-liststealth which analyzes a BIND log file to extract lists of AXFR and IXFR clients for each zone (excluding clients that use TSIG), and nsnotify which takes zone and a list of clients that should be notified. The nsnotify2stealth script bridges between nsnotifyd and these two helpers. Create working directory The working directory contains the client lists, one per zone, and a sym- link to the log file used by BIND. You only need to run this command once when creating the directory. $ mkdir notify-stealth $ cd notify-stealth $ ln -s /var/log/messages .log This directory will also contain a .pid file for nsnotifyd, and occasion- ally a .once file to stop nsnotify2stealth from running more than one nsnotify-liststealth at a time. Pre-populate the directory This gets us a file per zone, each containing a list of clients for that zone. The nsnotify2stealth script will automatically update the client lists once per day. $ nsnotify-liststealth .log Monitor the zones Because we have a file per zone, we can invoke nsnotifyd with a glob in- stead of listing the zones explicitly. The special files (.log .once .pid) are dotted so that the glob works as expected. $ nsnotifyd -P .pid -p 5307 nsnotify2stealth * Send notifies You will also need to reconfigure BIND to send notifies to nsnotifyd, as described in the previous example. Tune BIND If you have a lot of stealth secondaries, nsnotify2stealth can cause a large flood of zone transfers. You may need to change BIND's capacity set- tings as described in the ISC Knowledge Base article cited in the "SEE ALSO" section below. EXAMPLE - bump-in-the-wire DNSSEC The nsdiff(1) utility creates an nsupdate(1) script from the differences between two versions of a zone. It can be used as an alternative to BIND's inline-signing option, amongst other things. You can use nsnotifyd together with nsdiff to implement a zone signer that operates as a "bump in the wire" between a DNSSEC-unaware hidden master server and the zone's public name servers. Configure your hidden master server to send notifies and allow zone trans- fers to your signing server: also-notify { signer port 5305; }; allow-transfer { signer; }; Configure the signer with dynamic signed master zones, and generate keys for them: zone example.org { type master; update-policy local; auto-dnssec maintain; }; $ dnssec-keygen -fk example.org $ dnssec-keygen example.org Run nsnotifyd on the signer to trigger an update of the signed zone as soon as an update occurs on the hidden master: $ nsnotifyd -P nsnotifyd.pid -p 5305 nsnotify2update example.org Configure your public name servers to transfer your zones from the signer instead of from the hidden master. BUGS The nsnotifyd daemon is not very secure. It accepts any well-formed NOTIFY message, regardless of the source. It does not support TSIG authentication (RFC 2845) for access control. You should configure nsnotifyd to listen on a loopback address (which is the default) or use a packet filter to block unwanted traffic. The nsnotifyd daemon is not aware of the authoritative servers for a zone, so it cannot filter spurious NOTIFY messages. It has a very simplistic mechanism for choosing which servers to query when refreshing a zone. The nsnotifyd daemon only handles one query at a time, which prevents it from becoming a fork bomb, and in TCP mode it only handles one connection at a time. However, you can easily overwhelm it with more notifications than it can handle, or exclude other clients with a long-lived TCP connec- tion. See the "Performance considerations" section for further discussion. A spoofed NOTIFY will make nsnotifyd send a SOA query to the spoofed source address and wait for a reply (which will probably not arrive), during which time it is unresponsive. It does not support EDNS (RFC 6891). However, NOTIFY messages and re- sponses are very small, so following these specifications should not be necessary in practice. SEE ALSO git(1), metazone(1), named(8), named.conf(5), nsdiff(1), nsnotify(1), nspatch(1), nsupdate(1), syslog(3) Cathy Almond, "Tuning BIND for zone transfers", Internet Systems Consor- tium, ISC Knowledge Base, AA-00726, https://kb.isc.org/article/AA-00726. STANDARDS Paul Mockapetris, Domain names - concepts and facilities, RFC 1034, Novem- ber 1987. Paul Mockapetris, Domain names - implementation and specification, RFC 1035, November 1987. Robert Elz and Randy Bush, Serial number arithmetic, RFC 1982, August 1996. Paul Vixie, A mechanism for prompt notification of zone changes (DNS NO- TIFY), RFC 1996, August 1996. AUTHOR Tony Finch <dot@dotat.at> DNS February 24, 2026 NSNOTIFYD(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | DETAILS | EXAMPLE - metazones | EXAMPLE - zone revision history | EXAMPLE - stealth secondary synchronization | EXAMPLE - bump-in-the-wire DNSSEC | BUGS | SEE ALSO | STANDARDS | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=nsnotifyd&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>