Provided by: nsdiff_1.85-2_all 
NAME
nsdiff - create "nsupdate" script from DNS zone file differences
SYNOPSIS
nsdiff [-hV] [-b address] [-k keyfile] [-y [hmac:]name:key]
[-0|-1] [-q|-v [q][r]] [-cCdD] [-i regex] [-S mode|num]
[-u] [-s server] [-m server] <zone> [old] [new]
DESCRIPTION
The nsdiff program examines the old and new versions of a DNS zone, and outputs the differences as a
script for use by BIND's nsupdate program. It ignores DNSSEC-related differences, assuming that the name
server has sole control over zone keys and signatures.
The input files are typically in standard DNS zone file format. They are passed through BIND's named-
compilezone program to convert them to canonical form, so they may also be in BIND's "raw" format and may
have .jnl update journals.
If the old file is not specified, nsdiff will use dig to transfer the zone from the server given by the
-s option, or if the -s option is missing it will get the server from the zone's SOA MNAME field. If both
old and new files are not specified, nsdiff will transfer the new version of the zone from the server
given by the -m option.
The SOA serial number has special handling: any difference between the old and new serial numbers is
ignored (except in -S file mode), because background DNSSEC signing activity can increment the serial
number unpredictably. When the zones differ, nsdiff sets the serial number according to the -S option,
and it uses the old serial number to protect against conflicting updates.
OPTIONS
-h Display this documentation.
-V Display version information.
-0 Allow very large updates affecting one domain name to be split across multiple requests.
-1 Abort if update does not fit in one request packet.
-C Do not ignore CDS or CDNSKEY records. They are normally managed by dnssec-settime with the "-P sync"
and "-D sync" options, but you can use this option if you are managing them some other way. In that
case, your un-signed zone file should include the complete CDS and/or CDNSKEY RRset(s); if not,
nsdiff will delete the records.
-c Compare records case-insensitively. Can be helpful if the nsupdate target server does not preserve
the case of domain names. However with this option, nsdiff does not correctly handle records that
only differ in case.
-D Do not ignore DNSKEY records. It is sometimes necessary to take manual control over a zone's DNSKEY
RRset, for instance to include a foreign DNSKEY records during migration to or from another hosting
provider. If you use this option your un-signed zone file should include the complete DNSKEY RRset;
if not, nsdiff will try to delete the DNSKEY records. Normally named will reject the update, unless
the zone is configured with the dnssec-secure-to-insecure option.
-d Ignore DS records. This option is useful if you are managing secure delegations on the signing server
(via nsupdate) rather than in the source zone.
-i regex
Ignore more DNS records. By default, nsdiff strips out DNSSEC RRs (except for DS) before comparing
zones. You can exclude irrelevant changes from the diff by supplying a regex that matches the
unwanted RRs.
-m server[#port]
Transfer the new version of the zone from the server given in this option, for example, a back-end
hidden primary server. You can specify the server host name or IP address, optionally followed by a
"#" and the port number.
-s server[#port]
Transfer the old version of the zone from the server given in this option, using the same syntax as
the -m option.
-S date|file|serial|unix|num
Choose the SOA serial number update mode: the default file takes the serial number from the new input
zone; date uses a number of the form YYYYMMDDnn and allows for up to 100 updates per day; serial just
increments the serial number in the old input zone; unix uses the UNIX "seconds since the epoch"
value. You can also specify an explicit serial number value. In all cases, if the old input zone
serial number is larger than the target value it is just incremented. Serial number wrap-around is
not supported.
-q Quiet / quick check. Output is suppressed unless the zones differ, in which case a short note is
printed instead of an nsupdate script.
-u Tell nsupdate to send the update message to the server specified in the -s option.
-v [q][r]
Control verbosity. The q flag causes queries to be printed. The r flag causes responses to be
printed. To make nsdiff quiet, use -v ''.
The following options are passed to dig to modify its SOA and AXFR queries:
-b address
Source address for dig queries
-k keyfile
TSIG key file for dig queries.
-y [hmac:]name:key
Literal TSIG key for dig queries.
EXIT STATUS
The nsdiff utility returns 0 if the zones are the same, 1 if they differ, and 2 if there was an error.
DIAGNOSTICS
"usage: ..."
"not a domain name: <zone>"
Errors in the command line.
"could not get SOA record for <zone>"
Failed to retreive the zone's SOA using dig when trying to obtain the server MNAME from which to AXFR
the zone.
"missing SOA record"
The output of named-compilezone is incomplete, usually because the input file is erroneous.
"<zone> has changes"
Printed instead of an nsupdate script when the -q option is used.
"update does not fit in packet"
The changes for one domain name did not fit in 64 KiB, or the -1 option was specified and all the
changes did not fit in 64 KiB.
"ignoring dig options when loading zones from files"
Warning emitted when the command line includes options for dig as well as zone source files.
"ignoring -m option when loading new zone from file"
"need -m option when there are no input files"
The -m server option is required when there are no file arguments, and ignored otherwise.
"loading zone <zone> via AXFR from server"
"loading zone <zone> from file file"
Normal progress messages emitted before nsdiff invokes named-compilezone, to explain the latter's
diagnostics.
EXAMPLE - DNSSEC
It is easiest to deploy DNSSEC if you allow named to manage zone keys and signatures automatically, and
feed in changes to zones using DNS update requests. However this is very different from the traditional
way of manually maintaining zones in standard DNS zone file format. The nsdiff program bridges the gap
between the two operational styles.
To support this workflow you need BIND-9.7 or newer. You will continue maintaining your zone file
$sourcefile as before, but it is no longer the same as the $workingfile used by named. After you make a
change, instead of using "rndc reload $zone", run "nsdiff $zone $sourcefile | nsupdate -l".
Configure your zone as follows, to support DNSSEC and local dynamic updates:
zone $zone {
type primary;
file "$workingfile";
auto-dnssec maintain;
update-policy local;
};
To create DNSSEC keys for your zone, change to named's working directory and run these commands:
dnssec-keygen -f KSK $zone
dnssec-keygen $zone
EXAMPLE - bump-in-the-wire signing
A common arrangement for DNSSEC is to have a primary server that is oblivious to DNSSEC, a signing server
which transfers the zone from the primary and adds the DNSSEC records, and a number of secondary servers
which transfer the zone from the signer and which are the public authoritative servers.
You can implement this with nsdiff, which handles the transfer of the zone from the primary to the
signer. No modifications to the primary are necessary. You set up the signer as in the previous section.
To transfer changes from the primary to the signer, run the following on the signer:
nsdiff -m $primary -s $signer $zone | nsupdate -l
EXAMPLE - dynamic reverse DNS
You have a reverse zone such as "2.0.192.in-addr.arpa" which is mostly managed dynamically by a DHCP
server, but which also has some static records (for network equipment, say). You can maintain the static
part in a DNS zone file and feed any changes into the live dynamic zone by telling nsdiff to ignore the
dynamic entries. Say all the static equipment has IP addresses between 192.0.2.250 and 192.0.2.255, then
you can run the command pipeline:
nsdiff -i '^(?!25\d\.)' 2.0.192.in-addr.arpa 2.0.192.static |
nsupdate -l
CAVEATS
By default nsdiff does not maintain the transactional semantics of native DNS update requests when the
diff is big: it applies large changes in multiple update requests. To minimise the problems this may
cause, nsdiff ensures each domain name's changes are all in the same update request. There is still a
small risk of clients not seeing a change applied atomically when that matters (e.g. altering an MX and
creating the new target in the same transaction). You can avoid the risk by using the -1 option to
prevent multi-packet updates, or by being careful about changes that depend on multiple domain names.
The update requests emitted by nsdiff include SOA serial number prerequisite checks to ensure that the
zone has not changed while it is running. This can happen even in simple setups if named happens to be
re-signing the zone at the time you make an update. Unfortunately the DNS update protocol does not allow
for good error reporting when a prerequisite check fails. You can use nspatch to cope with this problem.
BUGS
When updating a name's DNS records, nsdiff first deletes the old ones then adds the new ones. This
ensures that CNAME replacements and TTL changes work correctly. However, this update strategy prevents
you from replacing every record in a zone's apex NS RRset in one update, because it isn't possible to
delete all a zone's name servers.
VERSION
This is nsdiff-1.85 <https://dotat.at/prog/nsdiff/>
Written by Tony Finch <fanf2@cam.ac.uk> <dot@dotat.at>
at Cambridge University Information Services.
You may do anything with this. It has no warranty.
ACKNOWLEDGMENTS
Thanks to Athanasius, Mike Bristow, Piete Brooks (University of Cambridge Computer Laboratory), Terry
Burton (University of Leicester), Owen Dunn (University of Cambridge Faculty of Mathematics), Martin
Hartl (Barracuda), JP Mens, Mohamad Shidiq Purnama (PANDI), and Jordan Rieger (webnames.ca) for providing
useful feedback.
SEE ALSO
nspatch(1), nsupdate(1), nsvi(1), dig(1), named(8), named-compilezone(8), perlre(1)
perl v5.38.2 2024-04-21 NSDIFF(1p)