1NSDIFF(1)             User Contributed Perl Documentation            NSDIFF(1)
2
3
4

NAME

6       nsdiff - create "nsupdate" script from DNS zone file differences
7

SYNOPSIS

9       nsdiff [-hV] [-b address] [-k keyfile] [-y [hmac:]name:key]
10              [-0|-1] [-q|-v [q][r]] [-cCdD] [-i regex] [-S mode|num]
11              [-u] [-s server] [-m server] <zone> [old] [new]
12

DESCRIPTION

14       The nsdiff program examines the old and new versions of a DNS zone, and
15       outputs the differences as a script for use by BIND's nsupdate program.
16       It ignores DNSSEC-related differences, assuming that the name server
17       has sole control over zone keys and signatures.
18
19       The input files are typically in standard DNS zone file format. They
20       are passed through BIND's named-compilezone program to convert them to
21       canonical form, so they may also be in BIND's "raw" format and may have
22       .jnl update journals.
23
24       If the old file is not specified, nsdiff will use dig to transfer the
25       zone from the server given by the -s option, or if the -s option is
26       missing it will get the server from the zone's SOA MNAME field. If both
27       old and new files are not specified, nsdiff will transfer the new
28       version of the zone from the server given by the -m option.
29
30       The SOA serial number has special handling: any difference between the
31       old and new serial numbers is ignored, because background DNSSEC
32       signing activity can increment the serial number unpredictably. When
33       the zones differ, nsdiff sets the serial number according to the -S
34       option, and it uses the old serial number to protect against
35       conflicting updates.
36

OPTIONS

38       -h  Display this documentation.
39
40       -V  Display version information.
41
42       -0  Allow very large updates affecting one domain name to be split
43           across multiple requests.
44
45       -1  Abort if update does not fit in one request packet.
46
47       -C  Do not ignore CDS or CDNSKEY records. They are normally managed by
48           dnssec-settime with the "-P sync" and "-D sync" options, but you
49           can use this option if you are managing them some other way. In
50           that case, your un-signed zone file should include the complete CDS
51           and/or CDNSKEY RRset(s); if not, nsdiff will delete the records.
52
53       -c  Compare records case-insensitively. Can be helpful if the nsupdate
54           target server does not preserve the case of domain names. However
55           with this option, nsdiff does not correctly handle records that
56           only differ in case.
57
58       -D  Do not ignore DNSKEY records. It is sometimes necessary to take
59           manual control over a zone's DNSKEY RRset, for instance to include
60           a foreign DNSKEY records during migration to or from another
61           hosting provider.  If you use this option your un-signed zone file
62           should include the complete DNSKEY RRset; if not, nsdiff will try
63           to delete the DNSKEY records. Normally named will reject the
64           update, unless the zone is configured with the dnssec-secure-to-
65           insecure option.
66
67       -d  Ignore DS records. This option is useful if you are managing secure
68           delegations on the signing server (via nsupdate) rather than in the
69           source zone.
70
71       -i regex
72           Ignore more DNS records. By default, nsdiff strips out DNSSEC RRs
73           (except for DS) before comparing zones. You can exclude irrelevant
74           changes from the diff by supplying a regex that matches the
75           unwanted RRs.
76
77       -m server[#port]
78           Transfer the new version of the zone from the server given in this
79           option, for example, a back-end hidden primary server. You can
80           specify the server host name or IP address, optionally followed by
81           a "#" and the port number.
82
83       -s server[#port]
84           Transfer the old version of the zone from the server given in this
85           option, using the same syntax as the -m option.
86
87       -S date|file|serial|unix|num
88           Choose the SOA serial number update mode: the default file takes
89           the serial number from the new input zone; date uses a number of
90           the form YYYYMMDDnn and allows for up to 100 updates per day;
91           serial just increments the serial number in the old input zone;
92           unix uses the UNIX "seconds since the epoch" value. You can also
93           specify an explicit serial number value. In all cases, if the old
94           input zone serial number is larger than the target value it is just
95           incremented. Serial number wrap-around is not supported.
96
97       -q  Quiet / quick check. Output is suppressed unless the zones differ,
98           in which case a short note is printed instead of an nsupdate
99           script.
100
101       -u  Tell nsupdate to send the update message to the server specified in
102           the -s option.
103
104       -v [q][r]
105           Control verbosity.  The q flag causes queries to be printed.  The r
106           flag causes responses to be printed.  To make nsdiff quiet, use
107           -v ''.
108
109       The following options are passed to dig to modify its SOA and AXFR
110       queries:
111
112       -b address
113           Source address for dig queries
114
115       -k keyfile
116           TSIG key file for dig queries.
117
118       -y [hmac:]name:key
119           Literal TSIG key for dig queries.
120

EXIT STATUS

122       The nsdiff utility returns 0 if the zones are the same, 1 if they
123       differ, and 2 if there was an error.
124

DIAGNOSTICS

126       "usage: ..."
127       "not a domain name: <zone>"
128           Errors in the command line.
129
130       "could not get SOA record for <zone>"
131           Failed to retreive the zone's SOA using dig when trying to obtain
132           the server MNAME from which to AXFR the zone.
133
134       "missing SOA record"
135           The output of named-compilezone is incomplete, usually because the
136           input file is erroneous.
137
138       "<zone> has changes"
139           Printed instead of an nsupdate script when the -q option is used.
140
141       "update does not fit in packet"
142           The changes for one domain name did not fit in 64 KiB, or the -1
143           option was specified and all the changes did not fit in 64 KiB.
144
145       "ignoring dig options when loading zones from files"
146           Warning emitted when the command line includes options for dig as
147           well as zone source files.
148
149       "ignoring -m option when loading new zone from file"
150       "need -m option when there are no input files"
151           The -m server option is required when there are no file arguments,
152           and ignored otherwise.
153
154       "loading zone <zone> via AXFR from server"
155       "loading zone <zone> from file file"
156           Normal progress messages emitted before nsdiff invokes named-
157           compilezone, to explain the latter's diagnostics.
158

EXAMPLE - DNSSEC

160       It is easiest to deploy DNSSEC if you allow named to manage zone keys
161       and signatures automatically, and feed in changes to zones using DNS
162       update requests. However this is very different from the traditional
163       way of manually maintaining zones in standard DNS zone file format. The
164       nsdiff program bridges the gap between the two operational styles.
165
166       To support this workflow you need BIND-9.7 or newer. You will continue
167       maintaining your zone file $sourcefile as before, but it is no longer
168       the same as the $workingfile used by named. After you make a change,
169       instead of using "rndc reload $zone", run "nsdiff $zone $sourcefile |
170       nsupdate -l".
171
172       Configure your zone as follows, to support DNSSEC and local dynamic
173       updates:
174
175         zone $zone {
176           type primary;
177           file "$workingfile";
178           auto-dnssec maintain;
179           update-policy local;
180         };
181
182       To create DNSSEC keys for your zone, change to named's working
183       directory and run these commands:
184
185         dnssec-keygen -f KSK $zone
186         dnssec-keygen $zone
187

EXAMPLE - bump-in-the-wire signing

189       A common arrangement for DNSSEC is to have a primary server that is
190       oblivious to DNSSEC, a signing server which transfers the zone from the
191       primary and adds the DNSSEC records, and a number of secondary servers
192       which transfer the zone from the signer and which are the public
193       authoritative servers.
194
195       You can implement this with nsdiff, which handles the transfer of the
196       zone from the primary to the signer. No modifications to the primary
197       are necessary. You set up the signer as in the previous section. To
198       transfer changes from the primary to the signer, run the following on
199       the signer:
200
201         nsdiff -m $primary -s $signer $zone | nsupdate -l
202

EXAMPLE - dynamic reverse DNS

204       You have a reverse zone such as "2.0.192.in-addr.arpa" which is mostly
205       managed dynamically by a DHCP server, but which also has some static
206       records (for network equipment, say). You can maintain the static part
207       in a DNS zone file and feed any changes into the live dynamic zone by
208       telling nsdiff to ignore the dynamic entries. Say all the static
209       equipment has IP addresses between 192.0.2.250 and 192.0.2.255, then
210       you can run the command pipeline:
211
212         nsdiff -i '^(?!25\d\.)' 2.0.192.in-addr.arpa 2.0.192.static |
213           nsupdate -l
214

CAVEATS

216       By default nsdiff does not maintain the transactional semantics of
217       native DNS update requests when the diff is big: it applies large
218       changes in multiple update requests. To minimise the problems this may
219       cause, nsdiff ensures each domain name's changes are all in the same
220       update request. There is still a small risk of clients not seeing a
221       change applied atomically when that matters (e.g. altering an MX and
222       creating the new target in the same transaction). You can avoid the
223       risk by using the -1 option to prevent multi-packet updates, or by
224       being careful about changes that depend on multiple domain names.
225
226       The update requests emitted by nsdiff include SOA serial number
227       prerequisite checks to ensure that the zone has not changed while it is
228       running. This can happen even in simple setups if named happens to be
229       re-signing the zone at the time you make an update. Unfortunately the
230       DNS update protocol does not allow for good error reporting when a
231       prerequisite check fails. You can use nspatch to cope with this
232       problem.
233

BUGS

235       When updating a name's DNS records, nsdiff first deletes the old ones
236       then adds the new ones. This ensures that CNAME replacements and TTL
237       changes work correctly. However, this update strategy prevents you from
238       replacing every record in a zone's apex NS RRset in one update, because
239       it isn't possible to delete all a zone's name servers.
240

VERSION

242         This is nsdiff-1.82 <https://dotat.at/prog/nsdiff/>
243
244         Written by Tony Finch <fanf2@cam.ac.uk> <dot@dotat.at>
245         at Cambridge University Information Services.
246         You may do anything with this. It has no warranty.
247         <https://creativecommons.org/publicdomain/zero/1.0/>
248

ACKNOWLEDGMENTS

250       Thanks to Mike Bristow, Piete Brooks (University of Cambridge Computer
251       Laboratory), Terry Burton (University of Leicester), Owen Dunn
252       (University of Cambridge Faculty of Mathematics), JP Mens, Mohamad
253       Shidiq Purnama (PANDI), and Jordan Rieger (webnames.ca) for providing
254       useful feedback.
255

SEE ALSO

257       nspatch(1), nsupdate(1), nsvi(1), dig(1), named(8),
258       named-compilezone(8), perlre(1)
259
260
261
262perl v5.36.0                      2022-07-22                         NSDIFF(1)
Impressum