etc/services - sync with NetBSD-8
[minix.git] / external / bsd / bind / dist / bin / dnssec / dnssec-settime.docbook
blob6314677acc9cfcb92f4b99c63c0d568c9094a970
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) 2009-2011, 2014, 2015  Internet Systems Consortium, Inc. ("ISC")
6  -
7  - Permission to use, copy, modify, and/or distribute this software for any
8  - purpose with or without fee is hereby granted, provided that the above
9  - copyright notice and this permission notice appear in all copies.
10  -
11  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
12  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
13  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
14  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
15  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
16  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17  - PERFORMANCE OF THIS SOFTWARE.
18 -->
20 <refentry id="man.dnssec-settime">
21   <refentryinfo>
22     <date>February 06, 2014</date>
23   </refentryinfo>
25   <refmeta>
26     <refentrytitle><application>dnssec-settime</application></refentrytitle>
27     <manvolnum>8</manvolnum>
28     <refmiscinfo>BIND9</refmiscinfo>
29   </refmeta>
31   <refnamediv>
32     <refname><application>dnssec-settime</application></refname>
33     <refpurpose>Set the key timing metadata for a DNSSEC key</refpurpose>
34   </refnamediv>
36   <docinfo>
37     <copyright>
38       <year>2009</year>
39       <year>2010</year>
40       <year>2011</year>
41       <year>2014</year>
42       <year>2015</year>
43       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
44     </copyright>
45   </docinfo>
47   <refsynopsisdiv>
48     <cmdsynopsis>
49       <command>dnssec-settime</command>
50       <arg><option>-f</option></arg>
51       <arg><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
52       <arg><option>-L <replaceable class="parameter">ttl</replaceable></option></arg>
53       <arg><option>-P <replaceable class="parameter">date/offset</replaceable></option></arg>
54       <arg><option>-A <replaceable class="parameter">date/offset</replaceable></option></arg>
55       <arg><option>-R <replaceable class="parameter">date/offset</replaceable></option></arg>
56       <arg><option>-I <replaceable class="parameter">date/offset</replaceable></option></arg>
57       <arg><option>-D <replaceable class="parameter">date/offset</replaceable></option></arg>
58       <arg><option>-h</option></arg>
59       <arg><option>-V</option></arg>
60       <arg><option>-v <replaceable class="parameter">level</replaceable></option></arg>
61       <arg><option>-E <replaceable class="parameter">engine</replaceable></option></arg>
62       <arg choice="req">keyfile</arg>
63     </cmdsynopsis>
64   </refsynopsisdiv>
66   <refsect1>
67     <title>DESCRIPTION</title>
68     <para><command>dnssec-settime</command>
69       reads a DNSSEC private key file and sets the key timing metadata
70       as specified by the <option>-P</option>, <option>-A</option>,
71       <option>-R</option>, <option>-I</option>, and <option>-D</option>
72       options.  The metadata can then be used by
73       <command>dnssec-signzone</command> or other signing software to
74       determine when a key is to be published, whether it should be
75       used for signing a zone, etc.
76     </para>
77     <para>
78       If none of these options is set on the command line,
79       then <command>dnssec-settime</command> simply prints the key timing
80       metadata already stored in the key.
81     </para>
82     <para>
83       When key metadata fields are changed, both files of a key
84       pair (<filename>Knnnn.+aaa+iiiii.key</filename> and
85       <filename>Knnnn.+aaa+iiiii.private</filename>) are regenerated.
86       Metadata fields are stored in the private file.  A human-readable
87       description of the metadata is also placed in comments in the key
88       file.  The private file's permissions are always set to be
89       inaccessible to anyone other than the owner (mode 0600).
90     </para>
91   </refsect1>
93   <refsect1>
94     <title>OPTIONS</title>
96     <variablelist>
97       <varlistentry>
98         <term>-f</term>
99         <listitem>
100           <para>
101             Force an update of an old-format key with no metadata fields.
102             Without this option, <command>dnssec-settime</command> will
103             fail when attempting to update a legacy key.  With this option,
104             the key will be recreated in the new format, but with the
105             original key data retained.  The key's creation date will be
106             set to the present time.  If no other values are specified, 
107             then the key's publication and activation dates will also 
108             be set to the present time.
109           </para>
110         </listitem>
111       </varlistentry>
112   
113       <varlistentry>
114         <term>-K <replaceable class="parameter">directory</replaceable></term>
115         <listitem>
116           <para>
117             Sets the directory in which the key files are to reside.
118           </para>
119         </listitem>
120       </varlistentry>
122       <varlistentry>
123         <term>-L <replaceable class="parameter">ttl</replaceable></term>
124         <listitem>
125           <para>
126             Sets the default TTL to use for this key when it is converted
127             into a DNSKEY RR.  If the key is imported into a zone,
128             this is the TTL that will be used for it, unless there was
129             already a DNSKEY RRset in place, in which case the existing TTL
130             would take precedence.  If this value is not set and there
131             is no existing DNSKEY RRset, the TTL will default to the
132             SOA TTL. Setting the default TTL to <literal>0</literal>
133             or <literal>none</literal> removes it from the key.
134           </para>
135         </listitem>
136       </varlistentry>
138       <varlistentry>
139         <term>-h</term>
140         <listitem>
141           <para>
142             Emit usage message and exit.
143           </para>
144         </listitem>
145       </varlistentry>
146   
147       <varlistentry>
148         <term>-V</term>
149         <listitem>
150           <para>
151             Prints version information.
152           </para>
153         </listitem>
154       </varlistentry>
156       <varlistentry>
157         <term>-v <replaceable class="parameter">level</replaceable></term>
158         <listitem>
159           <para>
160             Sets the debugging level.
161           </para>
162         </listitem>
163       </varlistentry>
165       <varlistentry>
166         <term>-E <replaceable class="parameter">engine</replaceable></term>
167         <listitem>
168           <para>
169             Specifies the cryptographic hardware to use, when applicable.
170           </para>
171           <para>
172             When BIND is built with OpenSSL PKCS#11 support, this defaults
173             to the string "pkcs11", which identifies an OpenSSL engine
174             that can drive a cryptographic accelerator or hardware service
175             module.  When BIND is built with native PKCS#11 cryptography
176             (--enable-native-pkcs11), it defaults to the path of the PKCS#11
177             provider library specified via "--with-pkcs11".
178           </para>
179         </listitem>
180       </varlistentry>
181     </variablelist>
182   </refsect1>
184   <refsect1>
185     <title>TIMING OPTIONS</title>
186     <para>
187       Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
188       If the argument begins with a '+' or '-', it is interpreted as
189       an offset from the present time.  For convenience, if such an offset
190       is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
191       then the offset is computed in years (defined as 365 24-hour days,
192       ignoring leap years), months (defined as 30 24-hour days), weeks,
193       days, hours, or minutes, respectively.  Without a suffix, the offset
194       is computed in seconds.  To unset a date, use 'none' or 'never'.
195     </para>
197     <variablelist>
198       <varlistentry>
199         <term>-P <replaceable class="parameter">date/offset</replaceable></term>
200         <listitem>
201           <para>
202             Sets the date on which a key is to be published to the zone.
203             After that date, the key will be included in the zone but will
204             not be used to sign it.
205           </para>
206         </listitem>
207       </varlistentry>
209       <varlistentry>
210         <term>-A <replaceable class="parameter">date/offset</replaceable></term>
211         <listitem>
212           <para>
213             Sets the date on which the key is to be activated.  After that
214             date, the key will be included in the zone and used to sign
215             it.
216           </para>
217         </listitem>
218       </varlistentry>
220       <varlistentry>
221         <term>-R <replaceable class="parameter">date/offset</replaceable></term>
222         <listitem>
223           <para>
224             Sets the date on which the key is to be revoked.  After that
225             date, the key will be flagged as revoked.  It will be included
226             in the zone and will be used to sign it.
227           </para>
228         </listitem>
229       </varlistentry>
231       <varlistentry>
232         <term>-I <replaceable class="parameter">date/offset</replaceable></term>
233         <listitem>
234           <para>
235             Sets the date on which the key is to be retired.  After that
236             date, the key will still be included in the zone, but it
237             will not be used to sign it.
238           </para>
239         </listitem>
240       </varlistentry>
242       <varlistentry>
243         <term>-D <replaceable class="parameter">date/offset</replaceable></term>
244         <listitem>
245           <para>
246             Sets the date on which the key is to be deleted.  After that
247             date, the key will no longer be included in the zone.  (It
248             may remain in the key repository, however.)
249           </para>
250         </listitem>
251       </varlistentry>
253       <varlistentry>
254         <term>-S <replaceable class="parameter">predecessor key</replaceable></term>
255         <listitem>
256           <para>
257             Select a key for which the key being modified will be an
258             explicit successor.  The name, algorithm, size, and type of the
259             predecessor key must exactly match those of the key being
260             modified.  The activation date of the successor key will be set
261             to the inactivation date of the predecessor.  The publication
262             date will be set to the activation date minus the prepublication
263             interval, which defaults to 30 days.
264           </para>
265         </listitem>
266       </varlistentry>
268       <varlistentry>
269         <term>-i <replaceable class="parameter">interval</replaceable></term>
270         <listitem>
271           <para>
272             Sets the prepublication interval for a key.  If set, then
273             the publication and activation dates must be separated by at least
274             this much time.  If the activation date is specified but the
275             publication date isn't, then the publication date will default
276             to this much time before the activation date; conversely, if
277             the publication date is specified but activation date isn't,
278             then activation will be set to this much time after publication.
279           </para>
280           <para>
281             If the key is being set to be an explicit successor to another
282             key, then the default prepublication interval is 30 days; 
283             otherwise it is zero.
284           </para>
285           <para>
286             As with date offsets, if the argument is followed by one of
287             the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the
288             interval is measured in years, months, weeks, days, hours,
289             or minutes, respectively.  Without a suffix, the interval is
290             measured in seconds.
291           </para>
292         </listitem>
293       </varlistentry>
294     </variablelist>
295   </refsect1>
297   <refsect1>
298     <title>PRINTING OPTIONS</title>
299     <para>
300       <command>dnssec-settime</command> can also be used to print the
301       timing metadata associated with a key.
302     </para>
304     <variablelist>
305       <varlistentry>
306         <term>-u</term>
307         <listitem>
308           <para>
309             Print times in UNIX epoch format.
310           </para>
311         </listitem>
312       </varlistentry>
314       <varlistentry>
315         <term>-p <replaceable class="parameter">C/P/A/R/I/D/all</replaceable></term>
316         <listitem>
317           <para>
318             Print a specific metadata value or set of metadata values.
319             The <option>-p</option> option may be followed by one or more
320             of the following letters to indicate which value or values to print:
321             <option>C</option> for the creation date,
322             <option>P</option> for the publication date,
323             <option>A</option> for the activation date,
324             <option>R</option> for the revocation date,
325             <option>I</option> for the inactivation date, or
326             <option>D</option> for the deletion date.
327             To print all of the metadata, use <option>-p all</option>.
328           </para>
329         </listitem>
330       </varlistentry>
332     </variablelist>
333   </refsect1>
335   <refsect1>
336     <title>SEE ALSO</title>
337     <para><citerefentry>
338         <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
339       </citerefentry>,
340       <citerefentry>
341         <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
342       </citerefentry>,
343       <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
344       <citetitle>RFC 5011</citetitle>.
345     </para>
346   </refsect1>
348   <refsect1>
349     <title>AUTHOR</title>
350     <para><corpauthor>Internet Systems Consortium</corpauthor>
351     </para>
352   </refsect1>
354 </refentry><!--
355  - Local variables:
356  - mode: sgml
357  - End: