Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NSNOTIFYD(1)		FreeBSD	General	Commands Manual		  NSNOTIFYD(1)

NAME
     nsnotifyd -- handle DNS NOTIFY messages by	running	a command

SYNOPSIS
     nsnotifyd [-46dVw]	[-l facility] [-P pidfile] [-u user] [-R min:max]
	       [-r min:max] [-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 pa-
     rameters to poll for updates if nsnotifyd does not	receive	NOTIFY mes-
     sages more	frequently.

     You should	specify	zone names without the trailing	dot.  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 mes-
     sages.

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 ad-
	     dresses 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
	     before dropping privilege.

     -p	port
	     Listen on port, which may be a service name or a UDP port number.
	     The default is the	domain service,	UDP 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
	     Specify an	authoritative server to	use for	zone SOA refresh
	     queries.  By default nsnotifyd does periodic refreshes using the
	     system recursive resolver,	so its refresh queries may get stale
	     cached answers.

	     You can specify an	IP address or hostname.	 A hostname is looked
	     up	using the system resolver, constrained by the -4 or -6 op-
	     tions.

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

	   w	   weeks
	   d	   days
	   h	   hours
	   m	   minutes
	   s	   seconds

DETAILS
   Startup
     Before daemonizing, nsnotifyd makes SOA queries for each zone to initial-
     ize its refresh and retry timers.

     Daemonizing is configured using the -P pidfile and	-u user	options, or
     disabled 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 DNS server.  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 man-
     gled.

     Normally nsnotifyd	only accepts NOTIFY messages for zones given on	the
     command 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, or when a refresh or retry timer	ex-
     pires, 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 -s option.

     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
     occur 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 inter-
     val.

     If	the SOA	query or command fails,	nsnotifyd does not update its SOA pa-
     rameters, and and will next poll the zone on its retry interval.

     Unknown zones that	were not mentioned on the command line are not polled.

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
     extra 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 (exclud-
     ing clients that use TSIG), and nsnotify which takes zone and a list of
     clients that should be notified.  The nsnotify2stealth script bridges be-
     tween 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
     settings 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
     transfers 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.

     The nsnotifyd daemon only handles one query at a time, which prevents it
     from becoming a fork bomb.	 However, you can easily overwhelm it with
     more notifications	than it	can handle.  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 unrespon-
     sive.

     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	sim-
     plistic mechanism for choosing which servers to query when	refreshing a
     zone.

     The nsnotifyd daemon cannot accept	NOTIFY messages	over TCP (RFC 5966).
     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
     Consortium, ISC Knowledge Base, AA-00726,
     https://kb.isc.org/article/AA-00726.

STANDARDS
     Paul Mockapetris, Domain names - concepts and facilities, RFC 1034,
     November 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
     NOTIFY), RFC 1996,	August 1996.

AUTHOR
     Tony Finch	<dot@dotat.at> <fanf2@cam.ac.uk>
     at	Cambridge University Information Services

DNS				 July 10, 2015				   DNS

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://www.freebsd.org/cgi/man.cgi?query=nsnotifyd&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help