| blob | 8d928318ac27493725e6211cc6786ad847b15979 |
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 "—">]>
4 <!--
5 - Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC")
6 - Copyright (C) 2000-2003 Internet Software Consortium.
7 -
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.
11 -
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.
19 -->
21 <!-- $Id: dnssec-signzone.docbook,v 1.10.18.17 2007/08/28 07:20:00 tbox Exp $ -->
22 <refentry id="man.dnssec-signzone">
23 <refentryinfo>
24 <date>June 30, 2000</date>
25 </refentryinfo>
27 <refmeta>
28 <refentrytitle><application>dnssec-signzone</application></refentrytitle>
29 <manvolnum>8</manvolnum>
30 <refmiscinfo>BIND9</refmiscinfo>
31 </refmeta>
33 <refnamediv>
34 <refname><application>dnssec-signzone</application></refname>
35 <refpurpose>DNSSEC zone signing tool</refpurpose>
36 </refnamediv>
38 <docinfo>
39 <copyright>
40 <year>2004</year>
41 <year>2005</year>
42 <year>2006</year>
43 <year>2007</year>
44 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
45 </copyright>
46 <copyright>
47 <year>2000</year>
48 <year>2001</year>
49 <year>2002</year>
50 <year>2003</year>
51 <holder>Internet Software Consortium.</holder>
52 </copyright>
53 </docinfo>
55 <refsynopsisdiv>
56 <cmdsynopsis>
57 <command>dnssec-signzone</command>
58 <arg><option>-a</option></arg>
59 <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
60 <arg><option>-d <replaceable class="parameter">directory</replaceable></option></arg>
61 <arg><option>-e <replaceable class="parameter">end-time</replaceable></option></arg>
62 <arg><option>-f <replaceable class="parameter">output-file</replaceable></option></arg>
63 <arg><option>-g</option></arg>
64 <arg><option>-h</option></arg>
65 <arg><option>-k <replaceable class="parameter">key</replaceable></option></arg>
66 <arg><option>-l <replaceable class="parameter">domain</replaceable></option></arg>
67 <arg><option>-i <replaceable class="parameter">interval</replaceable></option></arg>
68 <arg><option>-I <replaceable class="parameter">input-format</replaceable></option></arg>
69 <arg><option>-j <replaceable class="parameter">jitter</replaceable></option></arg>
70 <arg><option>-N <replaceable class="parameter">soa-serial-format</replaceable></option></arg>
71 <arg><option>-o <replaceable class="parameter">origin</replaceable></option></arg>
72 <arg><option>-O <replaceable class="parameter">output-format</replaceable></option></arg>
73 <arg><option>-p</option></arg>
74 <arg><option>-r <replaceable class="parameter">randomdev</replaceable></option></arg>
75 <arg><option>-s <replaceable class="parameter">start-time</replaceable></option></arg>
76 <arg><option>-t</option></arg>
77 <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
78 <arg><option>-z</option></arg>
79 <arg choice="req">zonefile</arg>
80 <arg rep="repeat">key</arg>
81 </cmdsynopsis>
82 </refsynopsisdiv>
84 <refsect1>
85 <title>DESCRIPTION</title>
86 <para><command>dnssec-signzone</command>
87 signs a zone. It generates
88 NSEC and RRSIG records and produces a signed version of the
89 zone. The security status of delegations from the signed zone
90 (that is, whether the child zones are secure or not) is
91 determined by the presence or absence of a
92 <filename>keyset</filename> file for each child zone.
93 </para>
94 </refsect1>
96 <refsect1>
97 <title>OPTIONS</title>
99 <variablelist>
100 <varlistentry>
101 <term>-a</term>
102 <listitem>
103 <para>
104 Verify all generated signatures.
105 </para>
106 </listitem>
107 </varlistentry>
109 <varlistentry>
110 <term>-c <replaceable class="parameter">class</replaceable></term>
111 <listitem>
112 <para>
113 Specifies the DNS class of the zone.
114 </para>
115 </listitem>
116 </varlistentry>
118 <varlistentry>
119 <term>-k <replaceable class="parameter">key</replaceable></term>
120 <listitem>
121 <para>
122 Treat specified key as a key signing key ignoring any
123 key flags. This option may be specified multiple times.
124 </para>
125 </listitem>
126 </varlistentry>
128 <varlistentry>
129 <term>-l <replaceable class="parameter">domain</replaceable></term>
130 <listitem>
131 <para>
132 Generate a DLV set in addition to the key (DNSKEY) and DS sets.
133 The domain is appended to the name of the records.
134 </para>
135 </listitem>
136 </varlistentry>
138 <varlistentry>
139 <term>-d <replaceable class="parameter">directory</replaceable></term>
140 <listitem>
141 <para>
142 Look for <filename>keyset</filename> files in
143 <option>directory</option> as the directory
144 </para>
145 </listitem>
146 </varlistentry>
148 <varlistentry>
149 <term>-g</term>
150 <listitem>
151 <para>
152 Generate DS records for child zones from keyset files.
153 Existing DS records will be removed.
154 </para>
155 </listitem>
156 </varlistentry>
158 <varlistentry>
159 <term>-s <replaceable class="parameter">start-time</replaceable></term>
160 <listitem>
161 <para>
162 Specify the date and time when the generated RRSIG records
163 become valid. This can be either an absolute or relative
164 time. An absolute start time is indicated by a number
165 in YYYYMMDDHHMMSS notation; 20000530144500 denotes
166 14:45:00 UTC on May 30th, 2000. A relative start time is
167 indicated by +N, which is N seconds from the current time.
168 If no <option>start-time</option> is specified, the current
169 time minus 1 hour (to allow for clock skew) is used.
170 </para>
171 </listitem>
172 </varlistentry>
174 <varlistentry>
175 <term>-e <replaceable class="parameter">end-time</replaceable></term>
176 <listitem>
177 <para>
178 Specify the date and time when the generated RRSIG records
179 expire. As with <option>start-time</option>, an absolute
180 time is indicated in YYYYMMDDHHMMSS notation. A time relative
181 to the start time is indicated with +N, which is N seconds from
182 the start time. A time relative to the current time is
183 indicated with now+N. If no <option>end-time</option> is
184 specified, 30 days from the start time is used as a default.
185 </para>
186 </listitem>
187 </varlistentry>
189 <varlistentry>
190 <term>-f <replaceable class="parameter">output-file</replaceable></term>
191 <listitem>
192 <para>
193 The name of the output file containing the signed zone. The
194 default is to append <filename>.signed</filename> to
195 the
196 input filename.
197 </para>
198 </listitem>
199 </varlistentry>
201 <varlistentry>
202 <term>-h</term>
203 <listitem>
204 <para>
205 Prints a short summary of the options and arguments to
206 <command>dnssec-signzone</command>.
207 </para>
208 </listitem>
209 </varlistentry>
211 <varlistentry>
212 <term>-i <replaceable class="parameter">interval</replaceable></term>
213 <listitem>
214 <para>
215 When a previously-signed zone is passed as input, records
216 may be resigned. The <option>interval</option> option
217 specifies the cycle interval as an offset from the current
218 time (in seconds). If a RRSIG record expires after the
219 cycle interval, it is retained. Otherwise, it is considered
220 to be expiring soon, and it will be replaced.
221 </para>
222 <para>
223 The default cycle interval is one quarter of the difference
224 between the signature end and start times. So if neither
225 <option>end-time</option> or <option>start-time</option>
226 are specified, <command>dnssec-signzone</command>
227 generates
228 signatures that are valid for 30 days, with a cycle
229 interval of 7.5 days. Therefore, if any existing RRSIG records
230 are due to expire in less than 7.5 days, they would be
231 replaced.
232 </para>
233 </listitem>
234 </varlistentry>
236 <varlistentry>
237 <term>-I <replaceable class="parameter">input-format</replaceable></term>
238 <listitem>
239 <para>
240 The format of the input zone file.
241 Possible formats are <command>"text"</command> (default)
242 and <command>"raw"</command>.
243 This option is primarily intended to be used for dynamic
244 signed zones so that the dumped zone file in a non-text
245 format containing updates can be signed directly.
246 The use of this option does not make much sense for
247 non-dynamic zones.
248 </para>
249 </listitem>
250 </varlistentry>
252 <varlistentry>
253 <term>-j <replaceable class="parameter">jitter</replaceable></term>
254 <listitem>
255 <para>
256 When signing a zone with a fixed signature lifetime, all
257 RRSIG records issued at the time of signing expires
258 simultaneously. If the zone is incrementally signed, i.e.
259 a previously-signed zone is passed as input to the signer,
260 all expired signatures have to be regenerated at about the
261 same time. The <option>jitter</option> option specifies a
262 jitter window that will be used to randomize the signature
263 expire time, thus spreading incremental signature
264 regeneration over time.
265 </para>
266 <para>
267 Signature lifetime jitter also to some extent benefits
268 validators and servers by spreading out cache expiration,
269 i.e. if large numbers of RRSIGs don't expire at the same time
270 from all caches there will be less congestion than if all
271 validators need to refetch at mostly the same time.
272 </para>
273 </listitem>
274 </varlistentry>
276 <varlistentry>
277 <term>-n <replaceable class="parameter">ncpus</replaceable></term>
278 <listitem>
279 <para>
280 Specifies the number of threads to use. By default, one
281 thread is started for each detected CPU.
282 </para>
283 </listitem>
284 </varlistentry>
286 <varlistentry>
287 <term>-N <replaceable class="parameter">soa-serial-format</replaceable></term>
288 <listitem>
289 <para>
290 The SOA serial number format of the signed zone.
291 Possible formats are <command>"keep"</command> (default),
292 <command>"increment"</command> and
293 <command>"unixtime"</command>.
294 </para>
296 <variablelist>
297 <varlistentry>
298 <term><command>"keep"</command></term>
299 <listitem>
300 <para>Do not modify the SOA serial number.</para>
301 </listitem>
302 </varlistentry>
304 <varlistentry>
305 <term><command>"increment"</command></term>
306 <listitem>
307 <para>Increment the SOA serial number using RFC 1982
308 arithmetics.</para>
309 </listitem>
310 </varlistentry>
312 <varlistentry>
313 <term><command>"unixtime"</command></term>
314 <listitem>
315 <para>Set the SOA serial number to the number of seconds
316 since epoch.</para>
317 </listitem>
318 </varlistentry>
319 </variablelist>
321 </listitem>
322 </varlistentry>
324 <varlistentry>
325 <term>-o <replaceable class="parameter">origin</replaceable></term>
326 <listitem>
327 <para>
328 The zone origin. If not specified, the name of the zone file
329 is assumed to be the origin.
330 </para>
331 </listitem>
332 </varlistentry>
334 <varlistentry>
335 <term>-O <replaceable class="parameter">output-format</replaceable></term>
336 <listitem>
337 <para>
338 The format of the output file containing the signed zone.
339 Possible formats are <command>"text"</command> (default)
340 and <command>"raw"</command>.
341 </para>
342 </listitem>
343 </varlistentry>
345 <varlistentry>
346 <term>-p</term>
347 <listitem>
348 <para>
349 Use pseudo-random data when signing the zone. This is faster,
350 but less secure, than using real random data. This option
351 may be useful when signing large zones or when the entropy
352 source is limited.
353 </para>
354 </listitem>
355 </varlistentry>
357 <varlistentry>
358 <term>-r <replaceable class="parameter">randomdev</replaceable></term>
359 <listitem>
360 <para>
361 Specifies the source of randomness. If the operating
362 system does not provide a <filename>/dev/random</filename>
363 or equivalent device, the default source of randomness
364 is keyboard input. <filename>randomdev</filename>
365 specifies
366 the name of a character device or file containing random
367 data to be used instead of the default. The special value
368 <filename>keyboard</filename> indicates that keyboard
369 input should be used.
370 </para>
371 </listitem>
372 </varlistentry>
374 <varlistentry>
375 <term>-t</term>
376 <listitem>
377 <para>
378 Print statistics at completion.
379 </para>
380 </listitem>
381 </varlistentry>
383 <varlistentry>
384 <term>-v <replaceable class="parameter">level</replaceable></term>
385 <listitem>
386 <para>
387 Sets the debugging level.
388 </para>
389 </listitem>
390 </varlistentry>
392 <varlistentry>
393 <term>-z</term>
394 <listitem>
395 <para>
396 Ignore KSK flag on key when determining what to sign.
397 </para>
398 </listitem>
399 </varlistentry>
401 <varlistentry>
402 <term>zonefile</term>
403 <listitem>
404 <para>
405 The file containing the zone to be signed.
406 </para>
407 </listitem>
408 </varlistentry>
410 <varlistentry>
411 <term>key</term>
412 <listitem>
413 <para>
414 Specify which keys should be used to sign the zone. If
415 no keys are specified, then the zone will be examined
416 for DNSKEY records at the zone apex. If these are found and
417 there are matching private keys, in the current directory,
418 then these will be used for signing.
419 </para>
420 </listitem>
421 </varlistentry>
423 </variablelist>
424 </refsect1>
426 <refsect1>
427 <title>EXAMPLE</title>
428 <para>
429 The following command signs the <userinput>example.com</userinput>
430 zone with the DSA key generated by <command>dnssec-keygen</command>
431 (Kexample.com.+003+17247). The zone's keys must be in the master
432 file (<filename>db.example.com</filename>). This invocation looks
433 for <filename>keyset</filename> files, in the current directory,
434 so that DS records can be generated from them (<command>-g</command>).
435 </para>
436 <programlisting>% dnssec-signzone -g -o example.com db.example.com \
437 Kexample.com.+003+17247
438 db.example.com.signed
439 %</programlisting>
440 <para>
441 In the above example, <command>dnssec-signzone</command> creates
442 the file <filename>db.example.com.signed</filename>. This
443 file should be referenced in a zone statement in a
444 <filename>named.conf</filename> file.
445 </para>
446 <para>
447 This example re-signs a previously signed zone with default parameters.
448 The private keys are assumed to be in the current directory.
449 </para>
450 <programlisting>% cp db.example.com.signed db.example.com
451 % dnssec-signzone -o example.com db.example.com
452 db.example.com.signed
453 %</programlisting>
454 </refsect1>
456 <refsect1>
457 <title>SEE ALSO</title>
458 <para><citerefentry>
459 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
460 </citerefentry>,
461 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
462 <citetitle>RFC 2535</citetitle>.
463 </para>
464 </refsect1>
466 <refsect1>
467 <title>AUTHOR</title>
468 <para><corpauthor>Internet Systems Consortium</corpauthor>
469 </para>
470 </refsect1>
472 </refentry><!--
473 - Local variables:
474 - mode: sgml
475 - End:
476 -->