nsnotifyd.1

.Dd December 5, 2024
.Dt NSNOTIFYD 1 "DNS Commands Manual"
.Os DNS
.Sh NAME
.Nm nsnotifyd
.Nd handle DNS NOTIFY messages by running a command
.Sh SYNOPSIS
.Nm
.Op Fl 46dtVw
.Op Fl l Ar facility
.Op Fl P Ar pidfile
.Op Fl u Ar user
.Op Fl R Ar min Ns Li : Ns Ar max
.Op Fl r Ar min Ns Li : Ns Ar max
.Op Fl T Ar max
.Op Fl s Ar authority
.Op Fl a Ar addr
.Op Fl p Ar port
.Aq Ar command
.Ao Ar zone Ac Ns ...
.Sh DESCRIPTION
The
.Nm
daemon
monitors a set of DNS
.Ar zone Ns s
and runs a
.Ar 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 parameters
to poll for updates if
.Nm
does not receive NOTIFY messages more frequently.
.Pp
The root zone can be specified as
.Ql \&.
or
.Ql root .
.Pp
Note:
.Nm nsnotify
(without
.Ql d )
is a client for sending DNS NOTIFY messages
whereas
.Nm nsnotifyd
(with
.Ql d )
is a daemon for handling DNS NOTIFY messages.
.Sh OPTIONS
.Bl -tag -width indent
.It Fl 4
Use IPv4 only
(apart from the system resolver).
.It Fl 6
Use IPv6 only
(apart from the system resolver).
.It Fl a Ar address
Listen on
.Ar address
for NOTIFY messages.
The default is
.Li 127.0.0.1 .
.Pp
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
.Fl 4
or
.Fl 6
options.
.It Fl d
Debugging mode.
.Pp
Use once to prevent
.Nm
from daemonizing
and to make it print log messages to stderr.
.Pp
Use twice to get dumps of DNS packets.
.It Fl l Ar facility
Set the
.Xr syslog 3
facility.
The default is
.Sy daemon .
.It Fl P Ar path
Write the
.Nm
PID to the given
.Ar path
after daemonizing
and before dropping privilege.
.It Fl p Ar port
Listen on
.Ar port ,
which may be a service name or a port number.
The default is the
.Sy domain
service, port 53.
.It Fl R Ar interval
Override SOA
.Sy refresh
interval.
.It Fl R Ar min Ns Li : Ns Ar max
Restrict SOA
.Sy refresh
intervals
to be between
.Ar min
and
.Ar max .
.It Fl r Ar interval
Override SOA
.Sy retry
interval.
.It Fl r Ar min Ns Li : Ns Ar max
Restrict SOA
.Sy retry
intervals
to be between
.Ar min
and
.Ar max .
.It Fl s Ar authority
Specify an authoritative server to
use for zone SOA refresh queries.
By default
.Nm
does periodic refreshes
using the system recursive resolver,
so its refresh queries may get stale cached answers.
.Pp
You can specify an IP address or hostname.
A hostname is looked up using the system resolver,
constrained by the
.Fl 4
or
.Fl 6
options.
.It Fl T Ar interval
Set the read timeout for TCP connections.
.It Fl t
Listen for TCP connections instead of UDP.
.It Fl u Ar user
Drop privilege to
.Ar user
after daemonizing.
.It Fl V
Print details about this version of
.Nm .
.It Fl w
Accept NOTIFY messages for unknown zones
that are not given on the command line.
(Wildcard mode.)
.El
.Ss Interval syntax
Time parameters for the
.Fl T ,
.Fl R
and
.Fl r
options are in seconds,
or you can use a combination of the following time units,
as in DNS master files.
For example,
.Li 1h1m1s
is 3661 seconds.
.Pp
The usage message printed by
.Ic nsnotifyd -?
includes the default intervals.
.Pp
.Bl -tag -compact -width indent -offset indent
.It w
weeks
.It d
days
.It h
hours
.It m
minutes
.It s
seconds
.El
.Sh DETAILS
.Ss Startup
Before daemonizing,
.Nm
makes SOA queries for each
.Ar zone
to initialize its refresh and retry timers.
.Pp
Daemonizing is configured using the
.Fl P
.Ar pidfile
and
.Fl u
.Ar user
options,
or disabled with the
.Fl d
debugging option.
.Pp
When daemonizing,
.Nm
does
.Em not
change its working directory.
This allows the
.Ar command
to be context-sensitive.
.Ss Server
The
.Nm
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
.Nm
with and without the
.Fl t
option.
.Pp
The only DNS queries handled by
.Nm
are NOTIFY messages.
It rejects other queries with a
.Sy REFUSED
response code, or
.Sy FORMERR
if the query is too mangled.
.Pp
In UDP-only mode (the default),
.Nm
handles one query at a time,
which includes waiting for the script to finish.
In TCP-only mode
(the
.Fl t
option),
.Nm
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
.Fl T
read timeout interval.
.Pp
Normally
.Nm
only accepts NOTIFY messages for
.Ar zones
given on the command line.
NOTIFY messages are accepted for unknown zones if you use the
.Fl w
wildcard option.
.Pp
Messages are logged via
.Xr syslog 3 .
.Ss Zone refresh
When
.Nm
receives a NOTIFY,
or when a refresh or retry timer expires,
it makes a SOA query to see if the zone has changed.
The SOA query is sent to the source of the NOTIFY
or, if a timer expired, to the server given in the
.Fl s
option.
.Pp
If the NOTIFY message was accepted for an unknown zone
because you used the
.Fl w
wildcard option,
.Nm
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.)
.Pp
Some jitter is applied to SOA refresh and retry timers,
so polling can occur up to 10% earlier than specified.
.Ss Command invocation
When the SOA reply indicates the zone's serial number has increased,
.Nm
runs the
.Ar command
with two or three arguments:
.Bl -enum
.It
the
.Ar zone
name without the trailing dot,
except for the root zone
.Ql \&. ;
.It
its new serial number;
.It
the source address of the NOTIFY,
or no third argument if the update was found via a periodic refresh or retry.
.El
.Pp
When the command exits successfully,
.Nm
updates its copy of the zone's SOA parameters.
It will next poll the zone on its refresh interval.
.Pp
If the SOA query or command fails,
.Nm
does not update its SOA parameters,
and and will next poll the zone on its retry interval.
.Pp
Unknown zones that were not mentioned on the command line
are not polled.
.Ss Performance considerations
The speed of your
.Ar command
determines how fast
.Nm
can process NOTIFY messages.
.Pp
When NOTIFYs arrive faster than they can be processed,
.Nm
relies on network buffers to hold the queue of pending requests.
The time to clear the queue is the average
.Ar 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
.Nm .
.Pp
For example,
if you rapidly update 100 zones,
and your
.Ar command
takes about 1 second to run,
.Nm
will take about 1 minute and 40 seconds to process the queue
and respond to the last NOTIFY.
.Pp
You should aim to keep this maximum latency
(your
.Ar command
running time times your NOTIFY batch size)
less than your DNS server's NOTIFY timeout.
If your
.Ar 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
.Ar command
to limit its own concurrency.
.Sh 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.
.Pp
For details,
see the
.Xr metazone 1
manual.
.Sh EXAMPLE - zone revision history
Say you have a zone,
.Sy example.org ,
which is updated dynamically,
and you want to automatically record its history in a
.Xr git 1
repository.
.Ss Setup git
On a server that is authoritative for
.Sy example.org ,
run the following commands:
.Bd -literal -offset indent
$ mkdir zone-history
$ cd zone-history
$ git init
$ touch example.org
$ git add example.org
$ git commit -m 'add example.org (empty)'
.Ed
.Ss Monitor the zone
The
.Nm nsnotify2git
script is designed to work with
.Nm
to record the history of a set of zones.
Continuing the transcript,
.Bd -literal -offset indent
$ nsnotifyd -P nsnotifyd.pid -p 5309 nsnotify2git example.org
.Ed
.Ss Send notifies
To configure BIND to send notifies to
.Nm ,
so it detects changes more efficiently,
look in your
.Xr named.conf 5
file for
.Bd -literal -offset indent
zone example.org {
    ...
};
.Ed
.Pp
Inside the zone clause,
add or modify the
.Ql also-notify
setting so it includes the address and port used by
.Nm ,
like
.Bd -literal -offset indent
also-notify { 127.0.0.1 port 5309; };
.Ed
.Ss Update the zone
Now, when the zone changes,
.Nm
will quickly record the change in your
.Ic git
repository.
.Bd -literal -offset indent
$ nsupdate -l
> add example.com 3600 IN TXT "foo"
> send
> quit
$ git log --format=%s
example.org IN SOA 1234
add example.org (empty)
.Ed
.Sh 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 normally get NOTIFY messages to tell it when to update the
zone, so must rely on the zone's SOA timers instead.
.Pp
We would like stealth secondaries to get updates promptly,
but without extra manual configuration of
.Ql also-notify
lists.
.Pp
To do this,
.Nm
includes
.Nm 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
.Nm nsnotify
which takes zone and a list of clients that should be notified.
The
.Nm nsnotify2stealth
script bridges between
.Nm
and these two helpers.
.Ss Create working directory
The working directory contains the client lists,
one per zone,
and a symlink to the log file used by BIND.
You only need to run this command once
when creating the directory.
.Bd -literal -offset indent
$ mkdir notify-stealth
$ cd notify-stealth
$ ln -s /var/log/messages .log
.Ed
.Pp
This directory will also contain a
.Pa .pid
file for
.Nm ,
and occasionally a
.Pa .once
file to stop
.Nm nsnotify2stealth
from running more than one
.Nm nsnotify-liststealth
at a time.
.Ss Pre-populate the directory
This gets us a file per zone,
each containing a list of clients for that zone.
The
.Nm nsnotify2stealth
script will automatically update the client lists
once per day.
.Bd -literal -offset indent
$ nsnotify-liststealth .log
.Ed
.Ss Monitor the zones
Because we have a file per zone,
we can invoke
.Nm
with a glob instead of listing the zones explicitly.
The special files
.Pa ( .log .once .pid )
are dotted so that the glob works as expected.
.Bd -literal -offset indent
$ nsnotifyd -P .pid -p 5307 nsnotify2stealth *
.Ed
.Ss Send notifies
You will also need to reconfigure BIND to send notifies to
.Nm ,
as described in the previous example.
.Ss Tune BIND
If you have a lot of stealth secondaries,
.Nm nsnotify2stealth
can cause a large flood of zone transfers.
You may need to change BIND's capacity settings
as described in the ISC Knowledge Base article
cited in the
.Sx SEE ALSO
section below.
.Sh EXAMPLE - bump-in-the-wire DNSSEC
The
.Xr nsdiff 1
utility creates an
.Xr nsupdate 1
script from the differences between two versions of a zone.
It can be used as an alternative to BIND's
.Cd inline-signing
option, amongst other things.
.Pp
You can use
.Nm
together with
.Nm 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.
.Pp
Configure your hidden master server to send notifies and allow zone
transfers to your signing server:
.Bd -literal -offset indent
also-notify { signer port 5305; };
allow-transfer { signer; };
.Ed
.Pp
Configure the signer with dynamic signed master zones,
and generate keys for them:
.Bd -literal -offset indent
zone example.org {
    type master;
    update-policy local;
    auto-dnssec maintain;
};
.Ed
.Bd -literal -offset indent
$ dnssec-keygen -fk example.org
$ dnssec-keygen example.org
.Ed
.Pp
Run
.Nm
on the signer to trigger an update of the signed zone
as soon as an update occurs on the hidden master:
.Bd -literal -offset indent
$ nsnotifyd -P nsnotifyd.pid -p 5305 nsnotify2update example.org
.Ed
.Pp
Configure your public name servers to transfer your zones from the
signer instead of from the hidden master.
.Sh BUGS
The
.Nm
daemon is not very secure.
.Pp
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
.Nm
to listen on a loopback address
(which is the default)
or use a packet filter to block unwanted traffic.
.Pp
The
.Nm
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.
.Pp
The
.Nm
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 connection.
See the
.Sx Performance considerations
section for further discussion.
.Pp
A spoofed NOTIFY will make
.Nm
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.
.Pp
It does not support EDNS (RFC 6891).
However,
NOTIFY messages and responses are very small,
so following these specifications should not be necessary in practice.
.Sh SEE ALSO
.Xr git 1 ,
.Xr metazone 1 ,
.Xr named 8 ,
.Xr named.conf 5 ,
.Xr nsdiff 1 ,
.Xr nsnotify 1 ,
.Xr nspatch 1 ,
.Xr nsupdate 1 ,
.Xr syslog 3
.Rs
.%T Tuning BIND for zone transfers
.%A Cathy Almond
.%I Internet Systems Consortium
.%J ISC Knowledge Base
.%N AA-00726
.%U https://kb.isc.org/article/AA-00726
.Re
.Sh STANDARDS
.Rs
.%A Paul Mockapetris
.%T Domain names - concepts and facilities
.%R RFC 1034
.%D November 1987
.Re
.Pp
.Rs
.%A Paul Mockapetris
.%T Domain names - implementation and specification
.%R RFC 1035
.%D November 1987
.Re
.Pp
.Rs
.%A Robert Elz
.%A Randy Bush
.%T Serial number arithmetic
.%R RFC 1982
.%D August 1996
.Re
.Pp
.Rs
.%A Paul Vixie
.%T A mechanism for prompt notification of zone changes (DNS NOTIFY)
.%R RFC 1996
.%D August 1996
.Re
.Sh AUTHOR
.An Tony Finch
.Aq Li dot@dotat.at
.\" SPDX-License-Identifier: 0BSD OR MIT-0