-
Notifications
You must be signed in to change notification settings - Fork 5
/
nsnotifyd.1.html
557 lines (551 loc) · 26.9 KB
/
nsnotifyd.1.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
<!--
HTML for nsnotifyd web pages
Written by Tony Finch <[email protected]> in Cambridge.
Permission is hereby granted to use, copy, modify, and/or
distribute this software for any purpose with or without fee.
This software is provided 'as is', without warranty of any kind.
In no event shall the authors be liable for any damages arising
from the use of this software.
SPDX-License-Identifier: 0BSD OR MIT-0
-->
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
<link rel="stylesheet" href="nsnotifyd.css" type="text/css" media="all"/>
<title>nsnotifyd: scripted DNS NOTIFY handler</title>
</head>
<body>
<header>
<h1>
<a href="https://dotat.at/prog/nsnotifyd/">
<img src="https://dotat.at/graphics/dotat-32.png" alt="dotat">
<tt>nsnotifyd</tt>: scripted DNS NOTIFY handler
</a>
</h1>
</header>
<table class="head">
<tr>
<td class="head-ltitle">NSNOTIFYD(1)</td>
<td class="head-vol">General Commands Manual (dns commands manual)</td>
<td class="head-rtitle">NSNOTIFYD(1)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">nsnotifyd</code> — <span class="Nd">handle
DNS NOTIFY messages by running a command</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<table class="Nm">
<tr>
<td><code class="Nm">nsnotifyd</code></td>
<td>[<code class="Fl">-46dtVw</code>] [<code class="Fl">-l</code>
<var class="Ar">facility</var>] [<code class="Fl">-P</code>
<var class="Ar">pidfile</var>] [<code class="Fl">-u</code>
<var class="Ar">user</var>] [<code class="Fl">-R</code>
<var class="Ar">min</var>:<var class="Ar">max</var>]
[<code class="Fl">-r</code>
<var class="Ar">min</var>:<var class="Ar">max</var>]
[<code class="Fl">-T</code> <var class="Ar">max</var>]
[<code class="Fl">-s</code> <var class="Ar">authority</var>]
[<code class="Fl">-a</code> <var class="Ar">addr</var>]
[<code class="Fl">-p</code> <var class="Ar">port</var>]
⟨<var class="Ar">command</var>⟩
⟨<var class="Ar">zone</var>⟩...</td>
</tr>
</table>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">nsnotifyd</code> daemon monitors a set of DNS
<var class="Ar">zone</var>s and runs a <var class="Ar">command</var> 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 <code class="Nm">nsnotifyd</code> does not receive
NOTIFY messages more frequently.</p>
<p class="Pp">The root zone can be specified as
‘<code class="Li">.</code>’ or
‘<code class="Li">root</code>’.</p>
<p class="Pp">Note: <code class="Nm">nsnotify</code> (without
‘<code class="Li">d</code>’) is a client for sending DNS
NOTIFY messages whereas <code class="Nm">nsnotifyd</code> (with
‘<code class="Li">d</code>’) is a daemon for handling DNS
NOTIFY messages.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="OPTIONS"><a class="permalink" href="#OPTIONS">OPTIONS</a></h1>
<dl class="Bl-tag">
<dt id="4"><a class="permalink" href="#4"><code class="Fl">-4</code></a></dt>
<dd>Use IPv4 only (apart from the system resolver).</dd>
<dt id="6"><a class="permalink" href="#6"><code class="Fl">-6</code></a></dt>
<dd>Use IPv6 only (apart from the system resolver).</dd>
<dt id="a"><a class="permalink" href="#a"><code class="Fl">-a</code></a>
<var class="Ar">address</var></dt>
<dd>Listen on <var class="Ar">address</var> for NOTIFY messages. The default
is <code class="Li">127.0.0.1</code>.
<p class="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
<code class="Fl">-4</code> or <code class="Fl">-6</code> options.</p>
</dd>
<dt id="d"><a class="permalink" href="#d"><code class="Fl">-d</code></a></dt>
<dd>Debugging mode.
<p class="Pp">Use once to prevent <code class="Nm">nsnotifyd</code> from
daemonizing and to make it print log messages to stderr.</p>
<p class="Pp">Use twice to get dumps of DNS packets.</p>
</dd>
<dt id="l"><a class="permalink" href="#l"><code class="Fl">-l</code></a>
<var class="Ar">facility</var></dt>
<dd>Set the <a class="Xr">syslog(3)</a> facility. The default is
<a class="permalink" href="#daemon"><b class="Sy" id="daemon">daemon</b></a>.</dd>
<dt id="P"><a class="permalink" href="#P"><code class="Fl">-P</code></a>
<var class="Ar">path</var></dt>
<dd>Write the <code class="Nm">nsnotifyd</code> PID to the given
<var class="Ar">path</var> after daemonizing and before dropping
privilege.</dd>
<dt id="p"><a class="permalink" href="#p"><code class="Fl">-p</code></a>
<var class="Ar">port</var></dt>
<dd>Listen on <var class="Ar">port</var>, which may be a service name or a
port number. The default is the
<a class="permalink" href="#domain"><b class="Sy" id="domain">domain</b></a>
service, port 53.</dd>
<dt id="R"><a class="permalink" href="#R"><code class="Fl">-R</code></a>
<var class="Ar">interval</var></dt>
<dd>Override SOA <b class="Sy">refresh</b> interval.</dd>
<dt id="R~2"><a class="permalink" href="#R~2"><code class="Fl">-R</code></a>
<var class="Ar">min</var>:<var class="Ar">max</var></dt>
<dd>Restrict SOA <b class="Sy">refresh</b> intervals to be between
<var class="Ar">min</var> and <var class="Ar">max</var>.</dd>
<dt id="r"><a class="permalink" href="#r"><code class="Fl">-r</code></a>
<var class="Ar">interval</var></dt>
<dd>Override SOA <b class="Sy">retry</b> interval.</dd>
<dt id="r~2"><a class="permalink" href="#r~2"><code class="Fl">-r</code></a>
<var class="Ar">min</var>:<var class="Ar">max</var></dt>
<dd>Restrict SOA <b class="Sy">retry</b> intervals to be between
<var class="Ar">min</var> and <var class="Ar">max</var>.</dd>
<dt id="s"><a class="permalink" href="#s"><code class="Fl">-s</code></a>
<var class="Ar">authority</var></dt>
<dd>Specify an authoritative server to use for zone SOA refresh queries. By
default <code class="Nm">nsnotifyd</code> does periodic refreshes using
the system recursive resolver, so its refresh queries may get stale cached
answers.
<p class="Pp">You can specify an IP address or hostname. A hostname is
looked up using the system resolver, constrained by the
<code class="Fl">-4</code> or <code class="Fl">-6</code> options.</p>
</dd>
<dt id="T"><a class="permalink" href="#T"><code class="Fl">-T</code></a>
<var class="Ar">interval</var></dt>
<dd>Set the read timeout for TCP connections.</dd>
<dt id="t"><a class="permalink" href="#t"><code class="Fl">-t</code></a></dt>
<dd>Listen for TCP connections instead of UDP.</dd>
<dt id="u"><a class="permalink" href="#u"><code class="Fl">-u</code></a>
<var class="Ar">user</var></dt>
<dd>Drop privilege to <var class="Ar">user</var> after daemonizing.</dd>
<dt id="V"><a class="permalink" href="#V"><code class="Fl">-V</code></a></dt>
<dd>Print details about this version of
<code class="Nm">nsnotifyd</code>.</dd>
<dt id="w"><a class="permalink" href="#w"><code class="Fl">-w</code></a></dt>
<dd>Accept NOTIFY messages for unknown zones that are not given on the command
line. (Wildcard mode.)</dd>
</dl>
<section class="Ss">
<h2 class="Ss" id="Interval_syntax"><a class="permalink" href="#Interval_syntax">Interval
syntax</a></h2>
<p class="Pp">Time parameters for the <code class="Fl">-T</code>,
<code class="Fl">-R</code> and <code class="Fl">-r</code> options are in
seconds, or you can use a combination of the following time units, as in DNS
master files. For example, <code class="Li">1h1m1s</code> is 3661
seconds.</p>
<p class="Pp">The usage message printed by <code class="Ic">nsnotifyd -?</code>
includes the default intervals.</p>
<p class="Pp"></p>
<div class="Bd-indent">
<dl class="Bl-tag Bl-compact">
<dt>w</dt>
<dd>weeks</dd>
<dt>d</dt>
<dd>days</dd>
<dt>h</dt>
<dd>hours</dd>
<dt>m</dt>
<dd>minutes</dd>
<dt>s</dt>
<dd>seconds</dd>
</dl>
</div>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="DETAILS"><a class="permalink" href="#DETAILS">DETAILS</a></h1>
<section class="Ss">
<h2 class="Ss" id="Startup"><a class="permalink" href="#Startup">Startup</a></h2>
<p class="Pp">Before daemonizing, <code class="Nm">nsnotifyd</code> makes SOA
queries for each <var class="Ar">zone</var> to initialize its refresh and
retry timers.</p>
<p class="Pp">Daemonizing is configured using the <code class="Fl">-P</code>
<var class="Ar">pidfile</var> and <code class="Fl">-u</code>
<var class="Ar">user</var> options, or disabled with the
<code class="Fl">-d</code> debugging option.</p>
<p class="Pp" id="not">When daemonizing, <code class="Nm">nsnotifyd</code> does
<a class="permalink" href="#not"><i class="Em">not</i></a> change its
working directory. This allows the <var class="Ar">command</var> to be
context-sensitive.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Server"><a class="permalink" href="#Server">Server</a></h2>
<p class="Pp">The <code class="Nm">nsnotifyd</code> 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 <code class="Nm">nsnotifyd</code> with and without the
<code class="Fl">-t</code> option.</p>
<p class="Pp" id="REFUSED">The only DNS queries handled by
<code class="Nm">nsnotifyd</code> are NOTIFY messages. It rejects other
queries with a
<a class="permalink" href="#REFUSED"><b class="Sy">REFUSED</b></a> response
code, or
<a class="permalink" href="#FORMERR"><b class="Sy" id="FORMERR">FORMERR</b></a>
if the query is too mangled.</p>
<p class="Pp">In UDP-only mode (the default), <code class="Nm">nsnotifyd</code>
handles one query at a time, which includes waiting for the script to
finish. In TCP-only mode (the <code class="Fl">-t</code> option),
<code class="Nm">nsnotifyd</code> 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 <code class="Fl">-T</code> read timeout interval.</p>
<p class="Pp">Normally <code class="Nm">nsnotifyd</code> only accepts NOTIFY
messages for <var class="Ar">zones</var> given on the command line. NOTIFY
messages are accepted for unknown zones if you use the
<code class="Fl">-w</code> wildcard option.</p>
<p class="Pp">Messages are logged via <a class="Xr">syslog(3)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Zone_refresh"><a class="permalink" href="#Zone_refresh">Zone
refresh</a></h2>
<p class="Pp">When <code class="Nm">nsnotifyd</code> 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 <code class="Fl">-s</code>
option.</p>
<p class="Pp">If the NOTIFY message was accepted for an unknown zone because you
used the <code class="Fl">-w</code> wildcard option,
<code class="Nm">nsnotifyd</code> 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.)</p>
<p class="Pp">Some jitter is applied to SOA refresh and retry timers, so polling
can occur up to 10% earlier than specified.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Command_invocation"><a class="permalink" href="#Command_invocation">Command
invocation</a></h2>
<p class="Pp">When the SOA reply indicates the zone's serial number has
increased, <code class="Nm">nsnotifyd</code> runs the
<var class="Ar">command</var> with two or three arguments:</p>
<ol class="Bl-enum">
<li>the <var class="Ar">zone</var> name without the trailing dot, except for
the root zone ‘<code class="Li">.</code>’;</li>
<li>its new serial number;</li>
<li>the source address of the NOTIFY, or no third argument if the update was
found via a periodic refresh or retry.</li>
</ol>
<p class="Pp">When the command exits successfully,
<code class="Nm">nsnotifyd</code> updates its copy of the zone's SOA
parameters. It will next poll the zone on its refresh interval.</p>
<p class="Pp">If the SOA query or command fails,
<code class="Nm">nsnotifyd</code> does not update its SOA parameters, and
and will next poll the zone on its retry interval.</p>
<p class="Pp">Unknown zones that were not mentioned on the command line are not
polled.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Performance_considerations"><a class="permalink" href="#Performance_considerations">Performance
considerations</a></h2>
<p class="Pp">The speed of your <var class="Ar">command</var> determines how
fast <code class="Nm">nsnotifyd</code> can process NOTIFY messages.</p>
<p class="Pp">When NOTIFYs arrive faster than they can be processed,
<code class="Nm">nsnotifyd</code> relies on network buffers to hold the
queue of pending requests. The time to clear the queue is the average
<var class="Ar">command</var> 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 <code class="Nm">nsnotifyd</code>.</p>
<p class="Pp">For example, if you rapidly update 100 zones, and your
<var class="Ar">command</var> takes about 1 second to run,
<code class="Nm">nsnotifyd</code> will take about 1 minute and 40 seconds to
process the queue and respond to the last NOTIFY.</p>
<p class="Pp">You should aim to keep this maximum latency (your
<var class="Ar">command</var> running time times your NOTIFY batch size)
less than your DNS server's NOTIFY timeout. If your
<var class="Ar">command</var> 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 <var class="Ar">command</var> to limit
its own concurrency.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLE_-_metazones"><a class="permalink" href="#EXAMPLE_-_metazones">EXAMPLE
- metazones</a></h1>
<p class="Pp">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.</p>
<p class="Pp">For details, see the <a class="Xr">metazone(1)</a> manual.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLE_-_zone_revision_history"><a class="permalink" href="#EXAMPLE_-_zone_revision_history">EXAMPLE
- zone revision history</a></h1>
<p class="Pp">Say you have a zone, <b class="Sy">example.org</b>, which is
updated dynamically, and you want to automatically record its history in a
<a class="Xr">git(1)</a> repository.</p>
<section class="Ss">
<h2 class="Ss" id="Setup_git"><a class="permalink" href="#Setup_git">Setup
git</a></h2>
<p class="Pp">On a server that is authoritative for
<b class="Sy">example.org</b>, run the following commands:</p>
<div class="Bd Pp Bd-indent Li">
<pre>$ mkdir zone-history
$ cd zone-history
$ git init
$ touch example.org
$ git add example.org
$ git commit -m 'add example.org (empty)'</pre>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="Monitor_the_zone"><a class="permalink" href="#Monitor_the_zone">Monitor
the zone</a></h2>
<p class="Pp">The <code class="Nm">nsnotify2git</code> script is designed to
work with <code class="Nm">nsnotifyd</code> to record the history of a set
of zones. Continuing the transcript,</p>
<div class="Bd Pp Bd-indent Li">
<pre>$ nsnotifyd -P nsnotifyd.pid -p 5309 nsnotify2git example.org</pre>
</div>
</section>
<section class="Ss">
<h2 class="Ss">Send notifies</h2>
<p class="Pp">To configure BIND to send notifies to
<code class="Nm">nsnotifyd</code>, so it detects changes more efficiently,
look in your <a class="Xr">named.conf(5)</a> file for</p>
<div class="Bd Pp Bd-indent Li">
<pre>zone example.org {
...
};</pre>
</div>
<p class="Pp">Inside the zone clause, add or modify the
‘<code class="Li">also-notify</code>’ setting so it includes
the address and port used by <code class="Nm">nsnotifyd</code>, like</p>
<div class="Bd Pp Bd-indent Li">
<pre>also-notify { 127.0.0.1 port 5309; };</pre>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="Update_the_zone"><a class="permalink" href="#Update_the_zone">Update
the zone</a></h2>
<p class="Pp">Now, when the zone changes, <code class="Nm">nsnotifyd</code> will
quickly record the change in your <code class="Ic">git</code>
repository.</p>
<div class="Bd Pp Bd-indent Li">
<pre>$ nsupdate -l
> add example.com 3600 IN TXT "foo"
> send
> quit
$ git log --format=%s
example.org IN SOA 1234
add example.org (empty)</pre>
</div>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLE_-_stealth_secondary_synchronization"><a class="permalink" href="#EXAMPLE_-_stealth_secondary_synchronization">EXAMPLE
- stealth secondary synchronization</a></h1>
<p class="Pp">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.</p>
<p class="Pp">We would like stealth secondaries to get updates promptly, but
without extra manual configuration of
‘<code class="Li">also-notify</code>’ lists.</p>
<p class="Pp">To do this, <code class="Nm">nsnotifyd</code> includes
<code class="Nm">nsnotify-liststealth</code> which analyzes a BIND log file
to extract lists of AXFR and IXFR clients for each zone (excluding clients
that use TSIG), and <code class="Nm">nsnotify</code> which takes zone and a
list of clients that should be notified. The
<code class="Nm">nsnotify2stealth</code> script bridges between
<code class="Nm">nsnotifyd</code> and these two helpers.</p>
<section class="Ss">
<h2 class="Ss" id="Create_working_directory"><a class="permalink" href="#Create_working_directory">Create
working directory</a></h2>
<p class="Pp">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.</p>
<div class="Bd Pp Bd-indent Li">
<pre>$ mkdir notify-stealth
$ cd notify-stealth
$ ln -s /var/log/messages .log</pre>
</div>
<p class="Pp">This directory will also contain a <span class="Pa">.pid</span>
file for <code class="Nm">nsnotifyd</code>, and occasionally a
<span class="Pa">.once</span> file to stop
<code class="Nm">nsnotify2stealth</code> from running more than one
<code class="Nm">nsnotify-liststealth</code> at a time.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Pre-populate_the_directory"><a class="permalink" href="#Pre-populate_the_directory">Pre-populate
the directory</a></h2>
<p class="Pp">This gets us a file per zone, each containing a list of clients
for that zone. The <code class="Nm">nsnotify2stealth</code> script will
automatically update the client lists once per day.</p>
<div class="Bd Pp Bd-indent Li">
<pre>$ nsnotify-liststealth .log</pre>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="Monitor_the_zones"><a class="permalink" href="#Monitor_the_zones">Monitor
the zones</a></h2>
<p class="Pp">Because we have a file per zone, we can invoke
<code class="Nm">nsnotifyd</code> with a glob instead of listing the zones
explicitly. The special files (<span class="Pa">.log .once .pid</span>) are
dotted so that the glob works as expected.</p>
<div class="Bd Pp Bd-indent Li">
<pre>$ nsnotifyd -P .pid -p 5307 nsnotify2stealth *</pre>
</div>
</section>
<section class="Ss">
<h2 class="Ss">Send notifies</h2>
<p class="Pp">You will also need to reconfigure BIND to send notifies to
<code class="Nm">nsnotifyd</code>, as described in the previous example.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Tune_BIND"><a class="permalink" href="#Tune_BIND">Tune
BIND</a></h2>
<p class="Pp">If you have a lot of stealth secondaries,
<code class="Nm">nsnotify2stealth</code> 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
<a class="Sx" href="#SEE_ALSO">SEE ALSO</a> section below.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLE_-_bump-in-the-wire_DNSSEC"><a class="permalink" href="#EXAMPLE_-_bump-in-the-wire_DNSSEC">EXAMPLE
- bump-in-the-wire DNSSEC</a></h1>
<p class="Pp">The <a class="Xr">nsdiff(1)</a> utility creates an
<a class="Xr">nsupdate(1)</a> script from the differences between two
versions of a zone. It can be used as an alternative to BIND's
<code class="Cd">inline-signing</code> option, amongst other things.</p>
<p class="Pp">You can use <code class="Nm">nsnotifyd</code> together with
<code class="Nm">nsdiff</code> 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.</p>
<p class="Pp">Configure your hidden master server to send notifies and allow
zone transfers to your signing server:</p>
<div class="Bd Pp Bd-indent Li">
<pre>also-notify { signer port 5305; };
allow-transfer { signer; };</pre>
</div>
<p class="Pp">Configure the signer with dynamic signed master zones, and
generate keys for them:</p>
<div class="Bd Pp Bd-indent Li">
<pre>zone example.org {
type master;
update-policy local;
auto-dnssec maintain;
};</pre>
</div>
<div class="Bd Pp Bd-indent Li">
<pre>$ dnssec-keygen -fk example.org
$ dnssec-keygen example.org</pre>
</div>
<p class="Pp">Run <code class="Nm">nsnotifyd</code> on the signer to trigger an
update of the signed zone as soon as an update occurs on the hidden
master:</p>
<div class="Bd Pp Bd-indent Li">
<pre>$ nsnotifyd -P nsnotifyd.pid -p 5305 nsnotify2update example.org</pre>
</div>
<p class="Pp">Configure your public name servers to transfer your zones from the
signer instead of from the hidden master.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">The <code class="Nm">nsnotifyd</code> daemon is not very
secure.</p>
<p class="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 <code class="Nm">nsnotifyd</code> to listen on
a loopback address (which is the default) or use a packet filter to block
unwanted traffic.</p>
<p class="Pp">The <code class="Nm">nsnotifyd</code> 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.</p>
<p class="Pp">The <code class="Nm">nsnotifyd</code> 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
<a class="Sx" href="#Performance_considerations">Performance
considerations</a> section for further discussion.</p>
<p class="Pp">A spoofed NOTIFY will make <code class="Nm">nsnotifyd</code> 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.</p>
<p class="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.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">git(1)</a>, <a class="Xr">metazone(1)</a>,
<a class="Xr">named(8)</a>, <a class="Xr">named.conf(5)</a>,
<a class="Xr">nsdiff(1)</a>, <a class="Xr">nsnotify(1)</a>,
<a class="Xr">nspatch(1)</a>, <a class="Xr">nsupdate(1)</a>,
<a class="Xr">syslog(3)</a></p>
<p class="Pp"><cite class="Rs"><span class="RsA">Cathy Almond</span>,
<span class="RsT">Tuning BIND for zone transfers</span>,
<i class="RsI">Internet Systems Consortium</i>, <i class="RsJ">ISC Knowledge
Base</i>, <span class="RsN">AA-00726</span>,
<a class="RsU" href="https://kb.isc.org/article/AA-00726">https://kb.isc.org/article/AA-00726</a>.</cite></p>
</section>
<section class="Sh">
<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1>
<p class="Pp"><cite class="Rs"><span class="RsA">Paul Mockapetris</span>,
<span class="RsT">Domain names - concepts and facilities</span>,
<span class="RsR">RFC 1034</span>, <span class="RsD">November
1987</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">Paul Mockapetris</span>,
<span class="RsT">Domain names - implementation and specification</span>,
<span class="RsR">RFC 1035</span>, <span class="RsD">November
1987</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">Robert Elz</span> and
<span class="RsA">Randy Bush</span>, <span class="RsT">Serial number
arithmetic</span>, <span class="RsR">RFC 1982</span>,
<span class="RsD">August 1996</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">Paul Vixie</span>,
<span class="RsT">A mechanism for prompt notification of zone changes (DNS
NOTIFY)</span>, <span class="RsR">RFC 1996</span>, <span class="RsD">August
1996</span>.</cite></p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHOR"><a class="permalink" href="#AUTHOR">AUTHOR</a></h1>
<p class="Pp"><span class="An">Tony Finch</span>
⟨<code class="Li">[email protected]</code>⟩</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">December 5, 2024</td>
<td class="foot-os">DNS</td>
</tr>
</table>
<!-- SPDX-License-Identifier: 0BSD OR MIT-0 -->
<footer>
<address>
<a href="https://dotat.at/prog/nsnotifyd/"><tt>nsnotifyd</tt></a>
was written by
<a href="https://dotat.at/">Tony Finch</a>
<<a href="mailto:[email protected]">[email protected]</a>>
</address>
</footer>
</body>
</html>