1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3 [<!ENTITY mdash "—">]>
5 - Copyright (C) 2004-2009 Internet Systems Consortium, Inc. ("ISC")
6 - Copyright (C) 2000-2003 Internet Software Consortium.
8 - Permission to use, copy, modify, and/or distribute this software for any
9 - purpose with or without fee is hereby granted, provided that the above
10 - copyright notice and this permission notice appear in all copies.
12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
14 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
18 - PERFORMANCE OF THIS SOFTWARE.
21 <!-- $Id: dnssec-signzone.docbook,v 1.31.44.6 2009/06/09 01:47:19 each Exp $ -->
22 <refentry id="man.dnssec-signzone">
24 <date>June 08, 2009</date>
28 <refentrytitle><application>dnssec-signzone</application></refentrytitle>
29 <manvolnum>8</manvolnum>
30 <refmiscinfo>BIND9</refmiscinfo>
34 <refname><application>dnssec-signzone</application></refname>
35 <refpurpose>DNSSEC zone signing tool</refpurpose>
46 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
53 <holder>Internet Software Consortium.</holder>
59 <command>dnssec-signzone</command>
60 <arg><option>-a</option></arg>
61 <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
62 <arg><option>-d <replaceable class="parameter">directory</replaceable></option></arg>
63 <arg><option>-e <replaceable class="parameter">end-time</replaceable></option></arg>
64 <arg><option>-f <replaceable class="parameter">output-file</replaceable></option></arg>
65 <arg><option>-g</option></arg>
66 <arg><option>-h</option></arg>
67 <arg><option>-k <replaceable class="parameter">key</replaceable></option></arg>
68 <arg><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
69 <arg><option>-i <replaceable class="parameter">interval</replaceable></option></arg>
70 <arg><option>-I <replaceable class="parameter">input-format</replaceable></option></arg>
71 <arg><option>-j <replaceable class="parameter">jitter</replaceable></option></arg>
72 <arg><option>-N <replaceable class="parameter">soa-serial-format</replaceable></option></arg>
73 <arg><option>-o <replaceable class="parameter">origin</replaceable></option></arg>
74 <arg><option>-O <replaceable class="parameter">output-format</replaceable></option></arg>
75 <arg><option>-p</option></arg>
76 <arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
77 <arg><option>-s <replaceable class="parameter">start-time</replaceable></option></arg>
78 <arg><option>-t</option></arg>
79 <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
80 <arg><option>-z</option></arg>
81 <arg><option>-3 <replaceable class="parameter">salt</replaceable></option></arg>
82 <arg><option>-H <replaceable class="parameter">iterations</replaceable></option></arg>
83 <arg><option>-A</option></arg>
84 <arg choice="req">zonefile</arg>
85 <arg rep="repeat">key</arg>
90 <title>DESCRIPTION</title>
91 <para><command>dnssec-signzone</command>
92 signs a zone. It generates
93 NSEC and RRSIG records and produces a signed version of the
94 zone. The security status of delegations from the signed zone
95 (that is, whether the child zones are secure or not) is
96 determined by the presence or absence of a
97 <filename>keyset</filename> file for each child zone.
102 <title>OPTIONS</title>
109 Verify all generated signatures.
115 <term>-c <replaceable class="parameter">class</replaceable></term>
118 Specifies the DNS class of the zone.
124 <term>-k <replaceable class="parameter">key</replaceable></term>
127 Treat specified key as a key signing key ignoring any
128 key flags. This option may be specified multiple times.
134 <term>-l <replaceable class="parameter">domain</replaceable></term>
137 Generate a DLV set in addition to the key (DNSKEY) and DS sets.
138 The domain is appended to the name of the records.
144 <term>-d <replaceable class="parameter">directory</replaceable></term>
147 Look for <filename>keyset</filename> files in
148 <option>directory</option> as the directory
157 Generate DS records for child zones from keyset files.
158 Existing DS records will be removed.
164 <term>-s <replaceable class="parameter">start-time</replaceable></term>
167 Specify the date and time when the generated RRSIG records
168 become valid. This can be either an absolute or relative
169 time. An absolute start time is indicated by a number
170 in YYYYMMDDHHMMSS notation; 20000530144500 denotes
171 14:45:00 UTC on May 30th, 2000. A relative start time is
172 indicated by +N, which is N seconds from the current time.
173 If no <option>start-time</option> is specified, the current
174 time minus 1 hour (to allow for clock skew) is used.
180 <term>-e <replaceable class="parameter">end-time</replaceable></term>
183 Specify the date and time when the generated RRSIG records
184 expire. As with <option>start-time</option>, an absolute
185 time is indicated in YYYYMMDDHHMMSS notation. A time relative
186 to the start time is indicated with +N, which is N seconds from
187 the start time. A time relative to the current time is
188 indicated with now+N. If no <option>end-time</option> is
189 specified, 30 days from the start time is used as a default.
195 <term>-f <replaceable class="parameter">output-file</replaceable></term>
198 The name of the output file containing the signed zone. The
199 default is to append <filename>.signed</filename> to
210 Prints a short summary of the options and arguments to
211 <command>dnssec-signzone</command>.
217 <term>-i <replaceable class="parameter">interval</replaceable></term>
220 When a previously-signed zone is passed as input, records
221 may be resigned. The <option>interval</option> option
222 specifies the cycle interval as an offset from the current
223 time (in seconds). If a RRSIG record expires after the
224 cycle interval, it is retained. Otherwise, it is considered
225 to be expiring soon, and it will be replaced.
228 The default cycle interval is one quarter of the difference
229 between the signature end and start times. So if neither
230 <option>end-time</option> or <option>start-time</option>
231 are specified, <command>dnssec-signzone</command>
233 signatures that are valid for 30 days, with a cycle
234 interval of 7.5 days. Therefore, if any existing RRSIG records
235 are due to expire in less than 7.5 days, they would be
242 <term>-I <replaceable class="parameter">input-format</replaceable></term>
245 The format of the input zone file.
246 Possible formats are <command>"text"</command> (default)
247 and <command>"raw"</command>.
248 This option is primarily intended to be used for dynamic
249 signed zones so that the dumped zone file in a non-text
250 format containing updates can be signed directly.
251 The use of this option does not make much sense for
258 <term>-j <replaceable class="parameter">jitter</replaceable></term>
261 When signing a zone with a fixed signature lifetime, all
262 RRSIG records issued at the time of signing expires
263 simultaneously. If the zone is incrementally signed, i.e.
264 a previously-signed zone is passed as input to the signer,
265 all expired signatures have to be regenerated at about the
266 same time. The <option>jitter</option> option specifies a
267 jitter window that will be used to randomize the signature
268 expire time, thus spreading incremental signature
269 regeneration over time.
272 Signature lifetime jitter also to some extent benefits
273 validators and servers by spreading out cache expiration,
274 i.e. if large numbers of RRSIGs don't expire at the same time
275 from all caches there will be less congestion than if all
276 validators need to refetch at mostly the same time.
282 <term>-n <replaceable class="parameter">ncpus</replaceable></term>
285 Specifies the number of threads to use. By default, one
286 thread is started for each detected CPU.
292 <term>-N <replaceable class="parameter">soa-serial-format</replaceable></term>
295 The SOA serial number format of the signed zone.
296 Possible formats are <command>"keep"</command> (default),
297 <command>"increment"</command> and
298 <command>"unixtime"</command>.
303 <term><command>"keep"</command></term>
305 <para>Do not modify the SOA serial number.</para>
310 <term><command>"increment"</command></term>
312 <para>Increment the SOA serial number using RFC 1982
318 <term><command>"unixtime"</command></term>
320 <para>Set the SOA serial number to the number of seconds
330 <term>-o <replaceable class="parameter">origin</replaceable></term>
333 The zone origin. If not specified, the name of the zone file
334 is assumed to be the origin.
340 <term>-O <replaceable class="parameter">output-format</replaceable></term>
343 The format of the output file containing the signed zone.
344 Possible formats are <command>"text"</command> (default)
345 and <command>"raw"</command>.
354 Use pseudo-random data when signing the zone. This is faster,
355 but less secure, than using real random data. This option
356 may be useful when signing large zones or when the entropy
363 <term>-r <replaceable class="parameter">randomdev</replaceable></term>
366 Specifies the source of randomness. If the operating
367 system does not provide a <filename>/dev/random</filename>
368 or equivalent device, the default source of randomness
369 is keyboard input. <filename>randomdev</filename>
371 the name of a character device or file containing random
372 data to be used instead of the default. The special value
373 <filename>keyboard</filename> indicates that keyboard
374 input should be used.
383 Print statistics at completion.
389 <term>-v <replaceable class="parameter">level</replaceable></term>
392 Sets the debugging level.
401 Ignore KSK flag on key when determining what to sign.
407 <term>-3 <replaceable class="parameter">salt</replaceable></term>
410 Generate a NSEC3 chain with the given hex encoded salt.
411 A dash (<replaceable class="parameter">salt</replaceable>) can
412 be used to indicate that no salt is to be used when generating the NSEC3 chain.
418 <term>-H <replaceable class="parameter">iterations</replaceable></term>
421 When generating a NSEC3 chain use this many interations. The
431 When generating a NSEC3 chain set the OPTOUT flag on all
432 NSEC3 records and do not generate NSEC3 records for insecure
439 <term>zonefile</term>
442 The file containing the zone to be signed.
451 Specify which keys should be used to sign the zone. If
452 no keys are specified, then the zone will be examined
453 for DNSKEY records at the zone apex. If these are found and
454 there are matching private keys, in the current directory,
455 then these will be used for signing.
464 <title>EXAMPLE</title>
466 The following command signs the <userinput>example.com</userinput>
467 zone with the DSA key generated by <command>dnssec-keygen</command>
468 (Kexample.com.+003+17247). The zone's keys must be in the master
469 file (<filename>db.example.com</filename>). This invocation looks
470 for <filename>keyset</filename> files, in the current directory,
471 so that DS records can be generated from them (<command>-g</command>).
473 <programlisting>% dnssec-signzone -g -o example.com db.example.com \
474 Kexample.com.+003+17247
475 db.example.com.signed
478 In the above example, <command>dnssec-signzone</command> creates
479 the file <filename>db.example.com.signed</filename>. This
480 file should be referenced in a zone statement in a
481 <filename>named.conf</filename> file.
484 This example re-signs a previously signed zone with default parameters.
485 The private keys are assumed to be in the current directory.
487 <programlisting>% cp db.example.com.signed db.example.com
488 % dnssec-signzone -o example.com db.example.com
489 db.example.com.signed
494 <title>KNOWN BUGS</title>
496 <command>dnssec-signzone</command> was designed so that it could
497 sign a zone partially, using only a subset of the DNSSEC keys
498 needed to produce a fully-signed zone. This permits a zone
499 administrator, for example, to sign a zone with one key on one
500 machine, move the resulting partially-signed zone to a second
501 machine, and sign it again with a second key.
504 An unfortunate side-effect of this flexibility is that
505 <command>dnssec-signzone</command> does not check to make sure
506 it's signing a zone with any valid keys at all. An attempt to
507 sign a zone without any keys will appear to succeed, producing
508 a "signed" zone with no signatures. There is no warning issued
509 when a zone is not fully signed.
513 This will be corrected in a future release. In the meantime, ISC
514 recommends examining the output of <command>dnssec-signzone</command>
515 to confirm that the zone is properly signed by all keys before
521 <title>SEE ALSO</title>
523 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
525 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
526 <citetitle>RFC 4033</citetitle>.
531 <title>AUTHOR</title>
532 <para><corpauthor>Internet Systems Consortium</corpauthor>