1NSDIFF(1) User Contributed Perl Documentation NSDIFF(1)
2
6 nsdiff - create "nsupdate" script from DNS zone file differences
7
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
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 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 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 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
38 -h Display this documentation.
39 -V Display version information.
41 -0 Allow very large updates affecting one domain name to be split
43 across multiple requests.
44 -1 Abort if update does not fit in one request packet.
46 -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 -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 -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 -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 -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 -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 -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 -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 -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 -u Tell nsupdate to send the update message to the server specified in
102 the -s option.
103 -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 The following options are passed to dig to modify its SOA and AXFR
110 queries:
111 -b address
113 Source address for dig queries
114 -k keyfile
116 TSIG key file for dig queries.
117 -y [hmac:]name:key
119 Literal TSIG key for dig queries.
120
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
126 "usage: ..."
127 "not a domain name: <zone>"
128 Errors in the command line.
129 "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 "missing SOA record"
135 The output of named-compilezone is incomplete, usually because the
136 input file is erroneous.
137 "<zone> has changes"
139 Printed instead of an nsupdate script when the -q option is used.
140 "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 "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 "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 "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
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 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 Configure your zone as follows, to support DNSSEC and local dynamic
173 updates:
174 zone $zone {
176 type primary;
177 file "$workingfile";
178 auto-dnssec maintain;
179 update-policy local;
180 };
181 To create DNSSEC keys for your zone, change to named's working
183 directory and run these commands:
184 dnssec-keygen -f KSK $zone
186 dnssec-keygen $zone
187
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 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 nsdiff -m $primary -s $signer $zone | nsupdate -l
202
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 nsdiff -i '^(?!25\d\.)' 2.0.192.in-addr.arpa 2.0.192.static |
213 nsupdate -l
214
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 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
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
242 This is nsdiff-1.82 <https://dotat.at/prog/nsdiff/>
243 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
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
257 nspatch(1), nsupdate(1), nsvi(1), dig(1), named(8),
258 named-compilezone(8), perlre(1)
259perl v5.38.0 2023-07-20 NSDIFF(1)