Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_15_...
[ipreg/bind9.git] / bin / dnssec / dnssec-signzone.docbook
CommitLineData
d4ef6505 1<!--
843d3896 2 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
d4ef6505 3 -
0c27b3fe
MA
4 - This Source Code Form is subject to the terms of the Mozilla Public
5 - License, v. 2.0. If a copy of the MPL was not distributed with this
6 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
843d3896
OS
7 -
8 - See the COPYRIGHT file distributed with this work for additional
9 - information regarding copyright ownership.
d4ef6505 10-->
2eeb74d1 11
14a656f9 12<!-- Converted by db4-upgrade version 1.0 -->
1b8ce3b3 13<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="man.dnssec-signzone">
14a656f9
EH
14 <info>
15 <date>2014-02-18</date>
16 </info>
0b062f49 17 <refentryinfo>
14a656f9
EH
18 <corpname>ISC</corpname>
19 <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
0b062f49
BW
20 </refentryinfo>
21
22 <refmeta>
23 <refentrytitle><application>dnssec-signzone</application></refentrytitle>
6ed53e59 24 <manvolnum>8</manvolnum>
0b062f49
BW
25 <refmiscinfo>BIND9</refmiscinfo>
26 </refmeta>
27
28 <refnamediv>
29 <refname><application>dnssec-signzone</application></refname>
30 <refpurpose>DNSSEC zone signing tool</refpurpose>
31 </refnamediv>
32
268a4475
RA
33 <docinfo>
34 <copyright>
30e4fbdf
MA
35 <year>2000</year>
36 <year>2001</year>
37 <year>2002</year>
38 <year>2003</year>
268a4475
RA
39 <year>2004</year>
40 <year>2005</year>
4b3f3cc6 41 <year>2006</year>
c1a883f2 42 <year>2007</year>
3398334b 43 <year>2008</year>
39844d47 44 <year>2009</year>
0e27506c 45 <year>2011</year>
3b398443 46 <year>2012</year>
43b94483 47 <year>2013</year>
6ea23853 48 <year>2014</year>
19c7b1a0 49 <year>2015</year>
0c27b3fe 50 <year>2016</year>
b4099ed0 51 <year>2017</year>
843d3896 52 <year>2018</year>
dc64b706 53 <year>2019</year>
268a4475
RA
54 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
55 </copyright>
268a4475
RA
56 </docinfo>
57
0b062f49 58 <refsynopsisdiv>
14a656f9 59 <cmdsynopsis sepchar=" ">
0b062f49 60 <command>dnssec-signzone</command>
14a656f9
EH
61 <arg choice="opt" rep="norepeat"><option>-a</option></arg>
62 <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">class</replaceable></option></arg>
63 <arg choice="opt" rep="norepeat"><option>-d <replaceable class="parameter">directory</replaceable></option></arg>
64 <arg choice="opt" rep="norepeat"><option>-D</option></arg>
65 <arg choice="opt" rep="norepeat"><option>-E <replaceable class="parameter">engine</replaceable></option></arg>
66 <arg choice="opt" rep="norepeat"><option>-e <replaceable class="parameter">end-time</replaceable></option></arg>
67 <arg choice="opt" rep="norepeat"><option>-f <replaceable class="parameter">output-file</replaceable></option></arg>
68 <arg choice="opt" rep="norepeat"><option>-g</option></arg>
69 <arg choice="opt" rep="norepeat"><option>-h</option></arg>
a477a025
EH
70 <arg choice="opt" rep="norepeat"><option>-i <replaceable class="parameter">interval</replaceable></option></arg>
71 <arg choice="opt" rep="norepeat"><option>-I <replaceable class="parameter">input-format</replaceable></option></arg>
49c13b06 72 <arg choice="opt" rep="norepeat"><option>-J <replaceable class="parameter">jump</replaceable></option></arg>
a477a025 73 <arg choice="opt" rep="norepeat"><option>-j <replaceable class="parameter">jitter</replaceable></option></arg>
14a656f9
EH
74 <arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
75 <arg choice="opt" rep="norepeat"><option>-k <replaceable class="parameter">key</replaceable></option></arg>
76 <arg choice="opt" rep="norepeat"><option>-L <replaceable class="parameter">serial</replaceable></option></arg>
77 <arg choice="opt" rep="norepeat"><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
a477a025 78 <arg choice="opt" rep="norepeat"><option>-M <replaceable class="parameter">maxttl</replaceable></option></arg>
14a656f9
EH
79 <arg choice="opt" rep="norepeat"><option>-N <replaceable class="parameter">soa-serial-format</replaceable></option></arg>
80 <arg choice="opt" rep="norepeat"><option>-o <replaceable class="parameter">origin</replaceable></option></arg>
81 <arg choice="opt" rep="norepeat"><option>-O <replaceable class="parameter">output-format</replaceable></option></arg>
82 <arg choice="opt" rep="norepeat"><option>-P</option></arg>
14a656f9
EH
83 <arg choice="opt" rep="norepeat"><option>-Q</option></arg>
84 <arg choice="opt" rep="norepeat"><option>-R</option></arg>
14a656f9
EH
85 <arg choice="opt" rep="norepeat"><option>-S</option></arg>
86 <arg choice="opt" rep="norepeat"><option>-s <replaceable class="parameter">start-time</replaceable></option></arg>
87 <arg choice="opt" rep="norepeat"><option>-T <replaceable class="parameter">ttl</replaceable></option></arg>
88 <arg choice="opt" rep="norepeat"><option>-t</option></arg>
89 <arg choice="opt" rep="norepeat"><option>-u</option></arg>
90 <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
91 <arg choice="opt" rep="norepeat"><option>-V</option></arg>
92 <arg choice="opt" rep="norepeat"><option>-X <replaceable class="parameter">extended end-time</replaceable></option></arg>
93 <arg choice="opt" rep="norepeat"><option>-x</option></arg>
94 <arg choice="opt" rep="norepeat"><option>-z</option></arg>
95 <arg choice="opt" rep="norepeat"><option>-3 <replaceable class="parameter">salt</replaceable></option></arg>
96 <arg choice="opt" rep="norepeat"><option>-H <replaceable class="parameter">iterations</replaceable></option></arg>
97 <arg choice="opt" rep="norepeat"><option>-A</option></arg>
98 <arg choice="req" rep="norepeat">zonefile</arg>
99 <arg rep="repeat" choice="opt">key</arg>
0b062f49
BW
100 </cmdsynopsis>
101 </refsynopsisdiv>
102
14a656f9 103 <refsection><info><title>DESCRIPTION</title></info>
30eec077 104
268a4475
RA
105 <para><command>dnssec-signzone</command>
106 signs a zone. It generates
107 NSEC and RRSIG records and produces a signed version of the
108 zone. The security status of delegations from the signed zone
109 (that is, whether the child zones are secure or not) is
110 determined by the presence or absence of a
111 <filename>keyset</filename> file for each child zone.
0b062f49 112 </para>
14a656f9 113 </refsection>
0b062f49 114
14a656f9 115 <refsection><info><title>OPTIONS</title></info>
30eec077 116
0b062f49
BW
117
118 <variablelist>
119 <varlistentry>
120 <term>-a</term>
268a4475
RA
121 <listitem>
122 <para>
123 Verify all generated signatures.
124 </para>
125 </listitem>
0b062f49
BW
126 </varlistentry>
127
128 <varlistentry>
129 <term>-c <replaceable class="parameter">class</replaceable></term>
268a4475
RA
130 <listitem>
131 <para>
132 Specifies the DNS class of the zone.
133 </para>
134 </listitem>
0b062f49
BW
135 </varlistentry>
136
eab9975b
EH
137 <varlistentry>
138 <term>-C</term>
139 <listitem>
140 <para>
141 Compatibility mode: Generate a
142 <filename>keyset-<replaceable>zonename</replaceable></filename>
143 file in addition to
144 <filename>dsset-<replaceable>zonename</replaceable></filename>
145 when signing a zone, for use by older versions of
146 <command>dnssec-signzone</command>.
147 </para>
148 </listitem>
149 </varlistentry>
150
b0c15bd9 151 <varlistentry>
553ead32 152 <term>-d <replaceable class="parameter">directory</replaceable></term>
268a4475
RA
153 <listitem>
154 <para>
553ead32
EH
155 Look for <filename>dsset-</filename> or
156 <filename>keyset-</filename> files in <option>directory</option>.
268a4475
RA
157 </para>
158 </listitem>
b0c15bd9
MA
159 </varlistentry>
160
eff7f78b
MA
161 <varlistentry>
162 <term>-D</term>
163 <listitem>
164 <para>
165 Output only those record types automatically managed by
166 <command>dnssec-signzone</command>, i.e. RRSIG, NSEC,
167 NSEC3 and NSEC3PARAM records. If smart signing
168 (<option>-S</option>) is used, DNSKEY records are also
169 included. The resulting file can be included in the original
170 zone file with <command>$INCLUDE</command>. This option
30eec077 171 cannot be combined with <option>-O raw</option>,
c9611b45 172 <option>-O map</option>, or serial number updating.
eff7f78b
MA
173 </para>
174 </listitem>
175 </varlistentry>
176
8b78c993
FD
177 <varlistentry>
178 <term>-E <replaceable class="parameter">engine</replaceable></term>
179 <listitem>
180 <para>
ba751492
EH
181 When applicable, specifies the hardware to use for
182 cryptographic operations, such as a secure key store used
183 for signing.
184 </para>
185 <para>
186 When BIND is built with OpenSSL PKCS#11 support, this defaults
187 to the string "pkcs11", which identifies an OpenSSL engine
188 that can drive a cryptographic accelerator or hardware service
189 module. When BIND is built with native PKCS#11 cryptography
190 (--enable-native-pkcs11), it defaults to the path of the PKCS#11
191 provider library specified via "--with-pkcs11".
8b78c993
FD
192 </para>
193 </listitem>
194 </varlistentry>
195
50105afc 196 <varlistentry>
553ead32 197 <term>-g</term>
268a4475
RA
198 <listitem>
199 <para>
553ead32
EH
200 Generate DS records for child zones from
201 <filename>dsset-</filename> or <filename>keyset-</filename>
202 file. Existing DS records will be removed.
268a4475
RA
203 </para>
204 </listitem>
50105afc
MA
205 </varlistentry>
206
0b062f49 207 <varlistentry>
553ead32 208 <term>-K <replaceable class="parameter">directory</replaceable></term>
268a4475
RA
209 <listitem>
210 <para>
553ead32
EH
211 Key repository: Specify a directory to search for DNSSEC keys.
212 If not specified, defaults to the current directory.
268a4475
RA
213 </para>
214 </listitem>
0b062f49
BW
215 </varlistentry>
216
bf7f253e 217 <varlistentry>
553ead32 218 <term>-k <replaceable class="parameter">key</replaceable></term>
268a4475
RA
219 <listitem>
220 <para>
553ead32
EH
221 Treat specified key as a key signing key ignoring any
222 key flags. This option may be specified multiple times.
223 </para>
224 </listitem>
225 </varlistentry>
226
227 <varlistentry>
228 <term>-l <replaceable class="parameter">domain</replaceable></term>
229 <listitem>
230 <para>
231 Generate a DLV set in addition to the key (DNSKEY) and DS sets.
232 The domain is appended to the name of the records.
268a4475
RA
233 </para>
234 </listitem>
bf7f253e
MA
235 </varlistentry>
236
35f6a21f
EH
237 <varlistentry>
238 <term>-M <replaceable class="parameter">maxttl</replaceable></term>
239 <listitem>
240 <para>
241 Sets the maximum TTL for the signed zone.
242 Any TTL higher than <replaceable>maxttl</replaceable> in the
243 input zone will be reduced to <replaceable>maxttl</replaceable>
244 in the output. This provides certainty as to the largest
245 possible TTL in the signed zone, which is useful to know when
246 rolling keys because it is the longest possible time before
247 signatures that have been retrieved by resolvers will expire
248 from resolver caches. Zones that are signed with this
249 option should be configured to use a matching
250 <option>max-zone-ttl</option> in <filename>named.conf</filename>.
251 (Note: This option is incompatible with <option>-D</option>,
252 because it modifies non-DNSSEC data in the output zone.)
253 </para>
254 </listitem>
255 </varlistentry>
256
0b062f49
BW
257 <varlistentry>
258 <term>-s <replaceable class="parameter">start-time</replaceable></term>
268a4475
RA
259 <listitem>
260 <para>
261 Specify the date and time when the generated RRSIG records
262 become valid. This can be either an absolute or relative
263 time. An absolute start time is indicated by a number
264 in YYYYMMDDHHMMSS notation; 20000530144500 denotes
265 14:45:00 UTC on May 30th, 2000. A relative start time is
266 indicated by +N, which is N seconds from the current time.
267 If no <option>start-time</option> is specified, the current
268 time minus 1 hour (to allow for clock skew) is used.
269 </para>
270 </listitem>
0b062f49
BW
271 </varlistentry>
272
273 <varlistentry>
274 <term>-e <replaceable class="parameter">end-time</replaceable></term>
268a4475
RA
275 <listitem>
276 <para>
277 Specify the date and time when the generated RRSIG records
278 expire. As with <option>start-time</option>, an absolute
279 time is indicated in YYYYMMDDHHMMSS notation. A time relative
280 to the start time is indicated with +N, which is N seconds from
281 the start time. A time relative to the current time is
282 indicated with now+N. If no <option>end-time</option> is
283 specified, 30 days from the start time is used as a default.
eab9975b
EH
284 <option>end-time</option> must be later than
285 <option>start-time</option>.
268a4475
RA
286 </para>
287 </listitem>
0b062f49
BW
288 </varlistentry>
289
61271cde
EH
290 <varlistentry>
291 <term>-X <replaceable class="parameter">extended end-time</replaceable></term>
292 <listitem>
293 <para>
294 Specify the date and time when the generated RRSIG records
295 for the DNSKEY RRset will expire. This is to be used in cases
296 when the DNSKEY signatures need to persist longer than
297 signatures on other records; e.g., when the private component
298 of the KSK is kept offline and the KSK signature is to be
299 refreshed manually.
300 </para>
301 <para>
302 As with <option>start-time</option>, an absolute
303 time is indicated in YYYYMMDDHHMMSS notation. A time relative
304 to the start time is indicated with +N, which is N seconds from
305 the start time. A time relative to the current time is
306 indicated with now+N. If no <option>extended end-time</option> is
307 specified, the value of <option>end-time</option> is used as
308 the default. (<option>end-time</option>, in turn, defaults to
309 30 days from the start time.) <option>extended end-time</option>
310 must be later than <option>start-time</option>.
311 </para>
312 </listitem>
313 </varlistentry>
314
0b062f49
BW
315 <varlistentry>
316 <term>-f <replaceable class="parameter">output-file</replaceable></term>
268a4475
RA
317 <listitem>
318 <para>
319 The name of the output file containing the signed zone. The
320 default is to append <filename>.signed</filename> to
d9eebc08
EH
321 the input filename. If <option>output-file</option> is
322 set to <literal>"-"</literal>, then the signed zone is
323 written to the standard output, with a default output
324 format of "full".
268a4475
RA
325 </para>
326 </listitem>
0b062f49
BW
327 </varlistentry>
328
329 <varlistentry>
330 <term>-h</term>
268a4475
RA
331 <listitem>
332 <para>
333 Prints a short summary of the options and arguments to
334 <command>dnssec-signzone</command>.
335 </para>
336 </listitem>
0b062f49
BW
337 </varlistentry>
338
42782931
MS
339 <varlistentry>
340 <term>-V</term>
341 <listitem>
342 <para>
343 Prints version information.
344 </para>
345 </listitem>
346 </varlistentry>
347
0b062f49
BW
348 <varlistentry>
349 <term>-i <replaceable class="parameter">interval</replaceable></term>
268a4475
RA
350 <listitem>
351 <para>
561a29af 352 When a previously-signed zone is passed as input, records
268a4475
RA
353 may be resigned. The <option>interval</option> option
354 specifies the cycle interval as an offset from the current
355 time (in seconds). If a RRSIG record expires after the
356 cycle interval, it is retained. Otherwise, it is considered
357 to be expiring soon, and it will be replaced.
358 </para>
359 <para>
360 The default cycle interval is one quarter of the difference
361 between the signature end and start times. So if neither
362 <option>end-time</option> or <option>start-time</option>
363 are specified, <command>dnssec-signzone</command>
364 generates
365 signatures that are valid for 30 days, with a cycle
366 interval of 7.5 days. Therefore, if any existing RRSIG records
367 are due to expire in less than 7.5 days, they would be
368 replaced.
369 </para>
370 </listitem>
0b062f49
BW
371 </varlistentry>
372
e1740442
MA
373 <varlistentry>
374 <term>-I <replaceable class="parameter">input-format</replaceable></term>
375 <listitem>
376 <para>
377 The format of the input zone file.
6844e3f0 378 Possible formats are <command>"text"</command> (default),
c9611b45 379 <command>"raw"</command>, and <command>"map"</command>.
e1740442
MA
380 This option is primarily intended to be used for dynamic
381 signed zones so that the dumped zone file in a non-text
382 format containing updates can be signed directly.
383 The use of this option does not make much sense for
384 non-dynamic zones.
385 </para>
386 </listitem>
387 </varlistentry>
388
49c13b06
TF
389 <varlistentry>
390 <term>-J <replaceable class="parameter">jump</replaceable></term>
391 <listitem>
392 <para>
393 When signing a zone with <option>jitter</option> (see
394 the <option>-j</option> option below) signature expire
395 times are spread out with a resolution of one second. You
396 can change this with the <option>-J jump</option> option,
397 so that signatures expire in lumps <option>jump</option>
398 seconds apart.
399 </para>
400 </listitem>
401 </varlistentry>
402
6e8a8077 403 <varlistentry>
268a4475
RA
404 <term>-j <replaceable class="parameter">jitter</replaceable></term>
405 <listitem>
406 <para>
407 When signing a zone with a fixed signature lifetime, all
408 RRSIG records issued at the time of signing expires
409 simultaneously. If the zone is incrementally signed, i.e.
561a29af
MA
410 a previously-signed zone is passed as input to the signer,
411 all expired signatures have to be regenerated at about the
268a4475
RA
412 same time. The <option>jitter</option> option specifies a
413 jitter window that will be used to randomize the signature
414 expire time, thus spreading incremental signature
415 regeneration over time.
416 </para>
417 <para>
418 Signature lifetime jitter also to some extent benefits
419 validators and servers by spreading out cache expiration,
420 i.e. if large numbers of RRSIGs don't expire at the same time
421 from all caches there will be less congestion than if all
422 validators need to refetch at mostly the same time.
423 </para>
424 </listitem>
6e8a8077
MA
425 </varlistentry>
426
f30785f5
EH
427 <varlistentry>
428 <term>-L <replaceable class="parameter">serial</replaceable></term>
429 <listitem>
430 <para>
c9611b45 431 When writing a signed zone to "raw" or "map" format, set the
6844e3f0
EH
432 "source serial" value in the header to the specified serial
433 number. (This is expected to be used primarily for testing
434 purposes.)
f30785f5
EH
435 </para>
436 </listitem>
437 </varlistentry>
438
0b062f49
BW
439 <varlistentry>
440 <term>-n <replaceable class="parameter">ncpus</replaceable></term>
268a4475
RA
441 <listitem>
442 <para>
443 Specifies the number of threads to use. By default, one
444 thread is started for each detected CPU.
445 </para>
446 </listitem>
0b062f49
BW
447 </varlistentry>
448
6ed53e59
DH
449 <varlistentry>
450 <term>-N <replaceable class="parameter">soa-serial-format</replaceable></term>
451 <listitem>
452 <para>
453 The SOA serial number format of the signed zone.
454 Possible formats are <command>"keep"</command> (default),
b4ba66ba
EH
455 <command>"increment"</command>, <command>"unixtime"</command>,
456 and <command>"date"</command>.
6ed53e59
DH
457 </para>
458
459 <variablelist>
460 <varlistentry>
461 <term><command>"keep"</command></term>
462 <listitem>
463 <para>Do not modify the SOA serial number.</para>
464 </listitem>
465 </varlistentry>
466
467 <varlistentry>
468 <term><command>"increment"</command></term>
469 <listitem>
470 <para>Increment the SOA serial number using RFC 1982
471 arithmetics.</para>
472 </listitem>
473 </varlistentry>
474
475 <varlistentry>
476 <term><command>"unixtime"</command></term>
477 <listitem>
478 <para>Set the SOA serial number to the number of seconds
479 since epoch.</para>
480 </listitem>
481 </varlistentry>
b4ba66ba
EH
482
483 <varlistentry>
484 <term><command>"date"</command></term>
485 <listitem>
486 <para>Set the SOA serial number to today's date in
487 YYYYMMDDNN format.</para>
488 </listitem>
489 </varlistentry>
6ed53e59
DH
490 </variablelist>
491
492 </listitem>
493 </varlistentry>
494
0b062f49
BW
495 <varlistentry>
496 <term>-o <replaceable class="parameter">origin</replaceable></term>
268a4475
RA
497 <listitem>
498 <para>
499 The zone origin. If not specified, the name of the zone file
500 is assumed to be the origin.
501 </para>
502 </listitem>
0b062f49
BW
503 </varlistentry>
504
e1740442
MA
505 <varlistentry>
506 <term>-O <replaceable class="parameter">output-format</replaceable></term>
507 <listitem>
508 <para>
509 The format of the output file containing the signed zone.
6844e3f0
EH
510 Possible formats are <command>"text"</command> (default),
511 which is the standard textual representation of the zone;
b4d8192d 512 <command>"full"</command>, which is text output in a
6844e3f0 513 format suitable for processing by external scripts;
c9611b45 514 and <command>"map"</command>, <command>"raw"</command>,
6844e3f0
EH
515 and <command>"raw=N"</command>, which store the zone in
516 binary formats for rapid loading by <command>named</command>.
517 <command>"raw=N"</command> specifies the format version of
518 the raw zone file: if N is 0, the raw file can be read by
519 any version of <command>named</command>; if N is 1, the file
520 can be read by release 9.9.0 or higher; the default is 1.
e1740442
MA
521 </para>
522 </listitem>
523 </varlistentry>
524
2534a73a
MA
525 <varlistentry>
526 <term>-P</term>
527 <listitem>
528 <para>
529 Disable post sign verification tests.
530 </para>
531 <para>
532 The post sign verification test ensures that for each algorithm
6a550cb8
JR
533 in use there is at least one non revoked self signed KSK key,
534 that all revoked KSK keys are self signed, and that all records
2534a73a 535 in the zone are signed by the algorithm.
6a550cb8 536 This option skips these tests.
2534a73a
MA
537 </para>
538 </listitem>
539 </varlistentry>
540
35f1a4fc 541 <varlistentry>
0bbe3273 542 <term>-Q</term>
35f1a4fc
EH
543 <listitem>
544 <para>
0bbe3273 545 Remove signatures from keys that are no longer active.
35f1a4fc
EH
546 </para>
547 <para>
548 Normally, when a previously-signed zone is passed as input
549 to the signer, and a DNSKEY record has been removed and
30eec077 550 replaced with a new one, signatures from the old key
35f1a4fc
EH
551 that are still within their validity period are retained.
552 This allows the zone to continue to validate with cached
0bbe3273
EH
553 copies of the old DNSKEY RRset. The <option>-Q</option>
554 forces <command>dnssec-signzone</command> to remove
555 signatures from keys that are no longer active. This
556 enables ZSK rollover using the procedure described in
557 RFC 4641, section 4.2.1.1 ("Pre-Publish Key Rollover").
558 </para>
559 </listitem>
560 </varlistentry>
561 <varlistentry>
562 <term>-R</term>
563 <listitem>
564 <para>
565 Remove signatures from keys that are no longer published.
566 </para>
567 <para>
568 This option is similar to <option>-Q</option>, except it
569 forces <command>dnssec-signzone</command> to signatures from
570 keys that are no longer published. This enables ZSK rollover
571 using the procedure described in RFC 4641, section 4.2.1.2
572 ("Double Signature Zone Signing Key Rollover").
35f1a4fc
EH
573 </para>
574 </listitem>
575 </varlistentry>
553ead32
EH
576 <varlistentry>
577 <term>-S</term>
578 <listitem>
579 <para>
580 Smart signing: Instructs <command>dnssec-signzone</command> to
581 search the key repository for keys that match the zone being
582 signed, and to include them in the zone if appropriate.
583 </para>
584 <para>
585 When a key is found, its timing metadata is examined to
586 determine how it should be used, according to the following
587 rules. Each successive rule takes priority over the prior
588 ones:
589 </para>
590 <variablelist>
591 <varlistentry>
592 <listitem>
593 <para>
594 If no timing metadata has been set for the key, the key is
595 published in the zone and used to sign the zone.
596 </para>
597 </listitem>
598 </varlistentry>
599
600 <varlistentry>
601 <listitem>
602 <para>
603 If the key's publication date is set and is in the past, the
604 key is published in the zone.
605 </para>
606 </listitem>
607 </varlistentry>
608
609 <varlistentry>
610 <listitem>
611 <para>
612 If the key's activation date is set and in the past, the
613 key is published (regardless of publication date) and
30eec077 614 used to sign the zone.
553ead32
EH
615 </para>
616 </listitem>
617 </varlistentry>
618
619 <varlistentry>
620 <listitem>
621 <para>
622 If the key's revocation date is set and in the past, and the
623 key is published, then the key is revoked, and the revoked key
624 is used to sign the zone.
625 </para>
626 </listitem>
627 </varlistentry>
628
629 <varlistentry>
630 <listitem>
631 <para>
632 If either of the key's unpublication or deletion dates are set
633 and in the past, the key is NOT published or used to sign the
634 zone, regardless of any other metadata.
635 </para>
636 </listitem>
637 </varlistentry>
30419509
EH
638
639 <varlistentry>
640 <listitem>
641 <para>
642 If key's sync publication date is set and in the past,
643 synchronization records (type CDS and/or CDNSKEY) are
644 created.
645 </para>
646 </listitem>
647 </varlistentry>
648
649 <varlistentry>
650 <listitem>
651 <para>
652 If key's sync deletion date is set and in the past,
653 synchronization records (type CDS and/or CDNSKEY) are
654 removed.
655 </para>
656 </listitem>
657 </varlistentry>
553ead32
EH
658 </variablelist>
659 </listitem>
660 </varlistentry>
661
662 <varlistentry>
663 <term>-T <replaceable class="parameter">ttl</replaceable></term>
664 <listitem>
665 <para>
61bcc232
EH
666 Specifies a TTL to be used for new DNSKEY records imported
667 into the zone from the key repository. If not
668 specified, the default is the TTL value from the zone's SOA
eab9975b
EH
669 record. This option is ignored when signing without
670 <option>-S</option>, since DNSKEY records are not imported
671 from the key repository in that case. It is also ignored if
672 there are any pre-existing DNSKEY records at the zone apex,
673 in which case new records' TTL values will be set to match
61bcc232
EH
674 them, or if any of the imported DNSKEY records had a default
675 TTL value. In the event of a a conflict between TTL values in
676 imported keys, the shortest one is used.
553ead32
EH
677 </para>
678 </listitem>
679 </varlistentry>
680
0b062f49
BW
681 <varlistentry>
682 <term>-t</term>
268a4475
RA
683 <listitem>
684 <para>
685 Print statistics at completion.
686 </para>
687 </listitem>
0b062f49
BW
688 </varlistentry>
689
fb596cc9
EH
690 <varlistentry>
691 <term>-u</term>
692 <listitem>
693 <para>
694 Update NSEC/NSEC3 chain when re-signing a previously signed
695 zone. With this option, a zone signed with NSEC can be
696 switched to NSEC3, or a zone signed with NSEC3 can
697 be switch to NSEC or to NSEC3 with different parameters.
698 Without this option, <command>dnssec-signzone</command> will
699 retain the existing chain when re-signing.
700 </para>
701 </listitem>
702 </varlistentry>
703
0b062f49
BW
704 <varlistentry>
705 <term>-v <replaceable class="parameter">level</replaceable></term>
268a4475
RA
706 <listitem>
707 <para>
708 Sets the debugging level.
709 </para>
710 </listitem>
0b062f49
BW
711 </varlistentry>
712
3727725b
EH
713 <varlistentry>
714 <term>-x</term>
715 <listitem>
716 <para>
20502f35
EH
717 Only sign the DNSKEY, CDNSKEY, and CDS RRsets with
718 key-signing keys, and omit signatures from zone-signing
719 keys. (This is similar to the
8e4f3f1c 720 <command>dnssec-dnskey-kskonly yes;</command> zone option in
c00929ed 721 <command>named</command>.)
3727725b
EH
722 </para>
723 </listitem>
724 </varlistentry>
725
b0c15bd9
MA
726 <varlistentry>
727 <term>-z</term>
268a4475
RA
728 <listitem>
729 <para>
3727725b
EH
730 Ignore KSK flag on key when determining what to sign. This
731 causes KSK-flagged keys to sign all records, not just the
c00929ed
EH
732 DNSKEY RRset. (This is similar to the
733 <command>update-check-ksk no;</command> zone option in
734 <command>named</command>.)
268a4475
RA
735 </para>
736 </listitem>
b0c15bd9
MA
737 </varlistentry>
738
6098d364
MA
739 <varlistentry>
740 <term>-3 <replaceable class="parameter">salt</replaceable></term>
741 <listitem>
742 <para>
a93a66f6 743 Generate an NSEC3 chain with the given hex encoded salt.
6098d364
MA
744 A dash (<replaceable class="parameter">salt</replaceable>) can
745 be used to indicate that no salt is to be used when generating the NSEC3 chain.
746 </para>
747 </listitem>
748 </varlistentry>
749
750 <varlistentry>
751 <term>-H <replaceable class="parameter">iterations</replaceable></term>
752 <listitem>
753 <para>
cbadc440 754 When generating an NSEC3 chain, use this many iterations. The
a93a66f6 755 default is 10.
6098d364
MA
756 </para>
757 </listitem>
758 </varlistentry>
759
760 <varlistentry>
761 <term>-A</term>
762 <listitem>
763 <para>
a93a66f6 764 When generating an NSEC3 chain set the OPTOUT flag on all
6098d364
MA
765 NSEC3 records and do not generate NSEC3 records for insecure
766 delegations.
767 </para>
fb596cc9
EH
768 <para>
769 Using this option twice (i.e., <option>-AA</option>)
770 turns the OPTOUT flag off for all records. This is useful
771 when using the <option>-u</option> option to modify an NSEC3
772 chain which previously had OPTOUT set.
773 </para>
6098d364
MA
774 </listitem>
775 </varlistentry>
776
0b062f49
BW
777 <varlistentry>
778 <term>zonefile</term>
268a4475
RA
779 <listitem>
780 <para>
781 The file containing the zone to be signed.
268a4475
RA
782 </para>
783 </listitem>
0b062f49
BW
784 </varlistentry>
785
786 <varlistentry>
787 <term>key</term>
268a4475
RA
788 <listitem>
789 <para>
561a29af
MA
790 Specify which keys should be used to sign the zone. If
791 no keys are specified, then the zone will be examined
792 for DNSKEY records at the zone apex. If these are found and
793 there are matching private keys, in the current directory,
794 then these will be used for signing.
268a4475
RA
795 </para>
796 </listitem>
0b062f49
BW
797 </varlistentry>
798
799 </variablelist>
14a656f9 800 </refsection>
0b062f49 801
14a656f9 802 <refsection><info><title>EXAMPLE</title></info>
30eec077 803
0b062f49 804 <para>
268a4475 805 The following command signs the <userinput>example.com</userinput>
07370798
MM
806 zone with the ECDSAP256SHA256 key generated by key generated by
807 <command>dnssec-keygen</command> (Kexample.com.+013+17247).
808 Because the <command>-S</command> option is not being used,
809 the zone's keys must be in the master file
77b8f88f
EH
810 (<filename>db.example.com</filename>). This invocation looks
811 for <filename>dsset</filename> files, in the current directory,
812 so that DS records can be imported from them (<command>-g</command>).
0b062f49 813 </para>
561a29af 814<programlisting>% dnssec-signzone -g -o example.com db.example.com \
07370798 815Kexample.com.+013+17247
561a29af
MA
816db.example.com.signed
817%</programlisting>
0b062f49 818 <para>
561a29af 819 In the above example, <command>dnssec-signzone</command> creates
268a4475 820 the file <filename>db.example.com.signed</filename>. This
561a29af 821 file should be referenced in a zone statement in a
268a4475 822 <filename>named.conf</filename> file.
0b062f49 823 </para>
561a29af
MA
824 <para>
825 This example re-signs a previously signed zone with default parameters.
826 The private keys are assumed to be in the current directory.
827 </para>
828<programlisting>% cp db.example.com.signed db.example.com
829% dnssec-signzone -o example.com db.example.com
830db.example.com.signed
831%</programlisting>
14a656f9 832 </refsection>
0b062f49 833
14a656f9 834 <refsection><info><title>SEE ALSO</title></info>
30eec077 835
268a4475
RA
836 <para><citerefentry>
837 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
0b062f49 838 </citerefentry>,
0b062f49 839 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
0bbe3273 840 <citetitle>RFC 4033</citetitle>, <citetitle>RFC 4641</citetitle>.
0b062f49 841 </para>
14a656f9 842 </refsection>
0b062f49 843
14a656f9 844</refentry>