contrib/bind9/bin/dnssec/dnssec-signzone.docbook

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