Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_15_...
[ipreg/bind9.git] / bin / dnssec / dnssec-settime.docbook
CommitLineData
553ead32 1<!--
843d3896 2 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
553ead32 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.
553ead32 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-settime">
14a656f9 14 <info>
e939674d 15 <date>2015-08-21</date>
14a656f9 16 </info>
553ead32 17 <refentryinfo>
14a656f9
EH
18 <corpname>ISC</corpname>
19 <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
553ead32
EH
20 </refentryinfo>
21
22 <refmeta>
23 <refentrytitle><application>dnssec-settime</application></refentrytitle>
24 <manvolnum>8</manvolnum>
25 <refmiscinfo>BIND9</refmiscinfo>
26 </refmeta>
27
28 <refnamediv>
29 <refname><application>dnssec-settime</application></refname>
f02194c0 30 <refpurpose>set the key timing metadata for a DNSSEC key</refpurpose>
553ead32
EH
31 </refnamediv>
32
33 <docinfo>
34 <copyright>
35 <year>2009</year>
f1c89cb4 36 <year>2010</year>
207cee01 37 <year>2011</year>
6ea23853 38 <year>2014</year>
a6ca1009 39 <year>2015</year>
0c27b3fe 40 <year>2016</year>
a08f49ae 41 <year>2017</year>
843d3896 42 <year>2018</year>
dc64b706 43 <year>2019</year>
553ead32
EH
44 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
45 </copyright>
46 </docinfo>
47
48 <refsynopsisdiv>
14a656f9 49 <cmdsynopsis sepchar=" ">
553ead32 50 <command>dnssec-settime</command>
14a656f9
EH
51 <arg choice="opt" rep="norepeat"><option>-f</option></arg>
52 <arg choice="opt" rep="norepeat"><option>-K <replaceable class="parameter">directory</replaceable></option></arg>
53 <arg choice="opt" rep="norepeat"><option>-L <replaceable class="parameter">ttl</replaceable></option></arg>
54 <arg choice="opt" rep="norepeat"><option>-P <replaceable class="parameter">date/offset</replaceable></option></arg>
e939674d 55 <arg choice="opt" rep="norepeat"><option>-P sync <replaceable class="parameter">date/offset</replaceable></option></arg>
14a656f9
EH
56 <arg choice="opt" rep="norepeat"><option>-A <replaceable class="parameter">date/offset</replaceable></option></arg>
57 <arg choice="opt" rep="norepeat"><option>-R <replaceable class="parameter">date/offset</replaceable></option></arg>
58 <arg choice="opt" rep="norepeat"><option>-I <replaceable class="parameter">date/offset</replaceable></option></arg>
27505a93 59 <arg choice="opt" rep="norepeat"><option>-D <replaceable class="parameter">date/offset</replaceable></option></arg>
e939674d 60 <arg choice="opt" rep="norepeat"><option>-D sync <replaceable class="parameter">date/offset</replaceable></option></arg>
5201b96d
MK
61 <arg choice="opt" rep="norepeat"><option>-S <replaceable class="parameter">key</replaceable></option></arg>
62 <arg choice="opt" rep="norepeat"><option>-i <replaceable class="parameter">interval</replaceable></option></arg>
14a656f9
EH
63 <arg choice="opt" rep="norepeat"><option>-h</option></arg>
64 <arg choice="opt" rep="norepeat"><option>-V</option></arg>
65 <arg choice="opt" rep="norepeat"><option>-v <replaceable class="parameter">level</replaceable></option></arg>
66 <arg choice="opt" rep="norepeat"><option>-E <replaceable class="parameter">engine</replaceable></option></arg>
67 <arg choice="req" rep="norepeat">keyfile</arg>
553ead32
EH
68 </cmdsynopsis>
69 </refsynopsisdiv>
70
14a656f9 71 <refsection><info><title>DESCRIPTION</title></info>
30eec077 72
553ead32
EH
73 <para><command>dnssec-settime</command>
74 reads a DNSSEC private key file and sets the key timing metadata
75 as specified by the <option>-P</option>, <option>-A</option>,
b843f577 76 <option>-R</option>, <option>-I</option>, and <option>-D</option>
553ead32
EH
77 options. The metadata can then be used by
78 <command>dnssec-signzone</command> or other signing software to
79 determine when a key is to be published, whether it should be
80 used for signing a zone, etc.
81 </para>
82 <para>
83 If none of these options is set on the command line,
84 then <command>dnssec-settime</command> simply prints the key timing
85 metadata already stored in the key.
86 </para>
87 <para>
88 When key metadata fields are changed, both files of a key
89 pair (<filename>Knnnn.+aaa+iiiii.key</filename> and
90 <filename>Knnnn.+aaa+iiiii.private</filename>) are regenerated.
91 Metadata fields are stored in the private file. A human-readable
92 description of the metadata is also placed in comments in the key
d7be2b79
EH
93 file. The private file's permissions are always set to be
94 inaccessible to anyone other than the owner (mode 0600).
553ead32 95 </para>
14a656f9 96 </refsection>
553ead32 97
14a656f9 98 <refsection><info><title>OPTIONS</title></info>
30eec077 99
553ead32
EH
100
101 <variablelist>
102 <varlistentry>
e939674d 103 <term>-f</term>
553ead32 104 <listitem>
e939674d
MA
105 <para>
106 Force an update of an old-format key with no metadata fields.
553ead32
EH
107 Without this option, <command>dnssec-settime</command> will
108 fail when attempting to update a legacy key. With this option,
109 the key will be recreated in the new format, but with the
110 original key data retained. The key's creation date will be
30eec077
MA
111 set to the present time. If no other values are specified,
112 then the key's publication and activation dates will also
10a759ce 113 be set to the present time.
e939674d 114 </para>
553ead32
EH
115 </listitem>
116 </varlistentry>
30eec077 117
553ead32
EH
118 <varlistentry>
119 <term>-K <replaceable class="parameter">directory</replaceable></term>
120 <listitem>
121 <para>
122 Sets the directory in which the key files are to reside.
123 </para>
124 </listitem>
125 </varlistentry>
126
61bcc232
EH
127 <varlistentry>
128 <term>-L <replaceable class="parameter">ttl</replaceable></term>
129 <listitem>
130 <para>
131 Sets the default TTL to use for this key when it is converted
132 into a DNSKEY RR. If the key is imported into a zone,
133 this is the TTL that will be used for it, unless there was
134 already a DNSKEY RRset in place, in which case the existing TTL
03f97949
EH
135 would take precedence. If this value is not set and there
136 is no existing DNSKEY RRset, the TTL will default to the
137 SOA TTL. Setting the default TTL to <literal>0</literal>
138 or <literal>none</literal> removes it from the key.
61bcc232
EH
139 </para>
140 </listitem>
141 </varlistentry>
142
553ead32 143 <varlistentry>
e939674d 144 <term>-h</term>
553ead32 145 <listitem>
e939674d
MA
146 <para>
147 Emit usage message and exit.
148 </para>
553ead32
EH
149 </listitem>
150 </varlistentry>
30eec077 151
42782931 152 <varlistentry>
e939674d 153 <term>-V</term>
42782931 154 <listitem>
e939674d
MA
155 <para>
156 Prints version information.
157 </para>
42782931
MS
158 </listitem>
159 </varlistentry>
160
553ead32
EH
161 <varlistentry>
162 <term>-v <replaceable class="parameter">level</replaceable></term>
163 <listitem>
164 <para>
165 Sets the debugging level.
166 </para>
167 </listitem>
168 </varlistentry>
8b78c993
FD
169
170 <varlistentry>
171 <term>-E <replaceable class="parameter">engine</replaceable></term>
172 <listitem>
173 <para>
ba751492
EH
174 Specifies the cryptographic hardware to use, when applicable.
175 </para>
176 <para>
177 When BIND is built with OpenSSL PKCS#11 support, this defaults
178 to the string "pkcs11", which identifies an OpenSSL engine
179 that can drive a cryptographic accelerator or hardware service
180 module. When BIND is built with native PKCS#11 cryptography
181 (--enable-native-pkcs11), it defaults to the path of the PKCS#11
182 provider library specified via "--with-pkcs11".
8b78c993
FD
183 </para>
184 </listitem>
185 </varlistentry>
553ead32 186 </variablelist>
14a656f9 187 </refsection>
553ead32 188
14a656f9 189 <refsection><info><title>TIMING OPTIONS</title></info>
30eec077 190
553ead32
EH
191 <para>
192 Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
193 If the argument begins with a '+' or '-', it is interpreted as
eab9975b
EH
194 an offset from the present time. For convenience, if such an offset
195 is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
196 then the offset is computed in years (defined as 365 24-hour days,
197 ignoring leap years), months (defined as 30 24-hour days), weeks,
198 days, hours, or minutes, respectively. Without a suffix, the offset
a165a17a 199 is computed in seconds. To unset a date, use 'none' or 'never'.
553ead32
EH
200 </para>
201
202 <variablelist>
203 <varlistentry>
204 <term>-P <replaceable class="parameter">date/offset</replaceable></term>
205 <listitem>
206 <para>
207 Sets the date on which a key is to be published to the zone.
208 After that date, the key will be included in the zone but will
209 not be used to sign it.
210 </para>
211 </listitem>
212 </varlistentry>
213
e939674d
MA
214 <varlistentry>
215 <term>-P sync <replaceable class="parameter">date/offset</replaceable></term>
216 <listitem>
217 <para>
218 Sets the date on which CDS and CDNSKEY records that match this
219 key are to be published to the zone.
220 </para>
221 </listitem>
222 </varlistentry>
223
553ead32
EH
224 <varlistentry>
225 <term>-A <replaceable class="parameter">date/offset</replaceable></term>
226 <listitem>
227 <para>
228 Sets the date on which the key is to be activated. After that
eec29cfd 229 date, the key will be included in the zone and used to sign
553ead32
EH
230 it.
231 </para>
232 </listitem>
233 </varlistentry>
234
235 <varlistentry>
236 <term>-R <replaceable class="parameter">date/offset</replaceable></term>
237 <listitem>
238 <para>
239 Sets the date on which the key is to be revoked. After that
240 date, the key will be flagged as revoked. It will be included
241 in the zone and will be used to sign it.
242 </para>
243 </listitem>
244 </varlistentry>
245
246 <varlistentry>
b843f577 247 <term>-I <replaceable class="parameter">date/offset</replaceable></term>
553ead32
EH
248 <listitem>
249 <para>
b843f577
EH
250 Sets the date on which the key is to be retired. After that
251 date, the key will still be included in the zone, but it
252 will not be used to sign it.
553ead32
EH
253 </para>
254 </listitem>
255 </varlistentry>
256
257 <varlistentry>
258 <term>-D <replaceable class="parameter">date/offset</replaceable></term>
259 <listitem>
260 <para>
261 Sets the date on which the key is to be deleted. After that
b843f577
EH
262 date, the key will no longer be included in the zone. (It
263 may remain in the key repository, however.)
553ead32
EH
264 </para>
265 </listitem>
266 </varlistentry>
267
e939674d
MA
268 <varlistentry>
269 <term>-D sync <replaceable class="parameter">date/offset</replaceable></term>
270 <listitem>
271 <para>
272 Sets the date on which the CDS and CDNSKEY records that match this
273 key are to be deleted.
274 </para>
275 </listitem>
276 </varlistentry>
277
c6f4972c
MA
278 <varlistentry>
279 <term>-S <replaceable class="parameter">predecessor key</replaceable></term>
280 <listitem>
281 <para>
282 Select a key for which the key being modified will be an
283 explicit successor. The name, algorithm, size, and type of the
284 predecessor key must exactly match those of the key being
285 modified. The activation date of the successor key will be set
286 to the inactivation date of the predecessor. The publication
287 date will be set to the activation date minus the prepublication
288 interval, which defaults to 30 days.
289 </para>
290 </listitem>
291 </varlistentry>
292
293 <varlistentry>
294 <term>-i <replaceable class="parameter">interval</replaceable></term>
295 <listitem>
296 <para>
297 Sets the prepublication interval for a key. If set, then
298 the publication and activation dates must be separated by at least
299 this much time. If the activation date is specified but the
300 publication date isn't, then the publication date will default
301 to this much time before the activation date; conversely, if
302 the publication date is specified but activation date isn't,
303 then activation will be set to this much time after publication.
304 </para>
305 <para>
306 If the key is being set to be an explicit successor to another
30eec077 307 key, then the default prepublication interval is 30 days;
c6f4972c
MA
308 otherwise it is zero.
309 </para>
310 <para>
311 As with date offsets, if the argument is followed by one of
312 the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the
313 interval is measured in years, months, weeks, days, hours,
314 or minutes, respectively. Without a suffix, the interval is
315 measured in seconds.
316 </para>
317 </listitem>
318 </varlistentry>
553ead32 319 </variablelist>
14a656f9 320 </refsection>
553ead32 321
14a656f9 322 <refsection><info><title>PRINTING OPTIONS</title></info>
30eec077 323
eab9975b
EH
324 <para>
325 <command>dnssec-settime</command> can also be used to print the
326 timing metadata associated with a key.
327 </para>
328
329 <variablelist>
330 <varlistentry>
e939674d 331 <term>-u</term>
eab9975b 332 <listitem>
e939674d
MA
333 <para>
334 Print times in UNIX epoch format.
335 </para>
eab9975b
EH
336 </listitem>
337 </varlistentry>
338
339 <varlistentry>
e939674d 340 <term>-p <replaceable class="parameter">C/P/Psync/A/R/I/D/Dsync/all</replaceable></term>
eab9975b 341 <listitem>
e939674d
MA
342 <para>
343 Print a specific metadata value or set of metadata values.
eab9975b 344 The <option>-p</option> option may be followed by one or more
e939674d
MA
345 of the following letters or strings to indicate which value
346 or values to print:
eab9975b
EH
347 <option>C</option> for the creation date,
348 <option>P</option> for the publication date,
e939674d 349 <option>Psync</option> for the CDS and CDNSKEY publication date,
eab9975b 350 <option>A</option> for the activation date,
dcfca6f1 351 <option>R</option> for the revocation date,
e939674d
MA
352 <option>I</option> for the inactivation date,
353 <option>D</option> for the deletion date, and
354 <option>Dsync</option> for the CDS and CDNSKEY deletion date
eab9975b 355 To print all of the metadata, use <option>-p all</option>.
e939674d 356 </para>
eab9975b
EH
357 </listitem>
358 </varlistentry>
359
360 </variablelist>
14a656f9 361 </refsection>
eab9975b 362
14a656f9 363 <refsection><info><title>SEE ALSO</title></info>
30eec077 364
553ead32
EH
365 <para><citerefentry>
366 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
367 </citerefentry>,
368 <citerefentry>
369 <refentrytitle>dnssec-signzone</refentrytitle><manvolnum>8</manvolnum>
370 </citerefentry>,
371 <citetitle>BIND 9 Administrator Reference Manual</citetitle>,
372 <citetitle>RFC 5011</citetitle>.
373 </para>
14a656f9 374 </refsection>
553ead32 375
14a656f9 376</refentry>