Update repub branch u/fanf2/patch to rebasing branch u/fanf2/rebasing revision v9_15_...
[ipreg/bind9.git] / bin / dnssec / dnssec-settime.html
CommitLineData
63fe88e8 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
553ead32 2<!--
b4d3f782 3 - Copyright (C) 2009-2011, 2014-2019 Internet Systems Consortium, Inc. ("ISC")
bef75d63 4 -
6807a2dc
TU
5 - This Source Code Form is subject to the terms of the Mozilla Public
6 - License, v. 2.0. If a copy of the MPL was not distributed with this
7 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
553ead32 8-->
63fe88e8 9<html lang="en">
553ead32
EH
10<head>
11<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
0a7ed886 12<title>dnssec-settime</title>
fd2597f7 13<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
553ead32 14</head>
fd2597f7 15<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
553ead32 16<a name="man.dnssec-settime"></a><div class="titlepage"></div>
16fde7f0
TU
17
18
19
20
21
22 <div class="refnamediv">
553ead32 23<h2>Name</h2>
16fde7f0
TU
24<p>
25 <span class="application">dnssec-settime</span>
26 &#8212; set the key timing metadata for a DNSSEC key
27 </p>
553ead32 28</div>
16fde7f0
TU
29
30
31
32 <div class="refsynopsisdiv">
553ead32 33<h2>Synopsis</h2>
16fde7f0
TU
34 <div class="cmdsynopsis"><p>
35 <code class="command">dnssec-settime</code>
36 [<code class="option">-f</code>]
37 [<code class="option">-K <em class="replaceable"><code>directory</code></em></code>]
38 [<code class="option">-L <em class="replaceable"><code>ttl</code></em></code>]
39 [<code class="option">-P <em class="replaceable"><code>date/offset</code></em></code>]
40 [<code class="option">-P sync <em class="replaceable"><code>date/offset</code></em></code>]
41 [<code class="option">-A <em class="replaceable"><code>date/offset</code></em></code>]
42 [<code class="option">-R <em class="replaceable"><code>date/offset</code></em></code>]
43 [<code class="option">-I <em class="replaceable"><code>date/offset</code></em></code>]
44 [<code class="option">-D <em class="replaceable"><code>date/offset</code></em></code>]
45 [<code class="option">-D sync <em class="replaceable"><code>date/offset</code></em></code>]
2a08a599
TU
46 [<code class="option">-S <em class="replaceable"><code>key</code></em></code>]
47 [<code class="option">-i <em class="replaceable"><code>interval</code></em></code>]
16fde7f0
TU
48 [<code class="option">-h</code>]
49 [<code class="option">-V</code>]
50 [<code class="option">-v <em class="replaceable"><code>level</code></em></code>]
51 [<code class="option">-E <em class="replaceable"><code>engine</code></em></code>]
52 {keyfile}
53 </p></div>
54 </div>
55
56 <div class="refsection">
fd2597f7 57<a name="id-1.7"></a><h2>DESCRIPTION</h2>
16fde7f0
TU
58
59 <p><span class="command"><strong>dnssec-settime</strong></span>
0a7ed886 60 reads a DNSSEC private key file and sets the key timing metadata
553ead32 61 as specified by the <code class="option">-P</code>, <code class="option">-A</code>,
f8e3e03c 62 <code class="option">-R</code>, <code class="option">-I</code>, and <code class="option">-D</code>
0a7ed886 63 options. The metadata can then be used by
2eeb74d1 64 <span class="command"><strong>dnssec-signzone</strong></span> or other signing software to
0a7ed886
AU
65 determine when a key is to be published, whether it should be
66 used for signing a zone, etc.
553ead32 67 </p>
16fde7f0 68 <p>
553ead32 69 If none of these options is set on the command line,
2eeb74d1 70 then <span class="command"><strong>dnssec-settime</strong></span> simply prints the key timing
553ead32
EH
71 metadata already stored in the key.
72 </p>
16fde7f0 73 <p>
0a7ed886
AU
74 When key metadata fields are changed, both files of a key
75 pair (<code class="filename">Knnnn.+aaa+iiiii.key</code> and
76 <code class="filename">Knnnn.+aaa+iiiii.private</code>) are regenerated.
77 Metadata fields are stored in the private file. A human-readable
78 description of the metadata is also placed in comments in the key
77dccf2a
AU
79 file. The private file's permissions are always set to be
80 inaccessible to anyone other than the owner (mode 0600).
0a7ed886 81 </p>
16fde7f0
TU
82 </div>
83
84 <div class="refsection">
fd2597f7 85<a name="id-1.8"></a><h2>OPTIONS</h2>
16fde7f0
TU
86
87
88 <div class="variablelist"><dl class="variablelist">
0a7ed886 89<dt><span class="term">-f</span></dt>
16fde7f0
TU
90<dd>
91 <p>
e62b9c9c 92 Force an update of an old-format key with no metadata fields.
2eeb74d1 93 Without this option, <span class="command"><strong>dnssec-settime</strong></span> will
0a7ed886
AU
94 fail when attempting to update a legacy key. With this option,
95 the key will be recreated in the new format, but with the
96 original key data retained. The key's creation date will be
9d557856
TU
97 set to the present time. If no other values are specified,
98 then the key's publication and activation dates will also
7717ec7a 99 be set to the present time.
16fde7f0
TU
100 </p>
101 </dd>
553ead32 102<dt><span class="term">-K <em class="replaceable"><code>directory</code></em></span></dt>
16fde7f0
TU
103<dd>
104 <p>
553ead32 105 Sets the directory in which the key files are to reside.
16fde7f0
TU
106 </p>
107 </dd>
a3f8c8e2 108<dt><span class="term">-L <em class="replaceable"><code>ttl</code></em></span></dt>
16fde7f0
TU
109<dd>
110 <p>
a3f8c8e2
AU
111 Sets the default TTL to use for this key when it is converted
112 into a DNSKEY RR. If the key is imported into a zone,
113 this is the TTL that will be used for it, unless there was
114 already a DNSKEY RRset in place, in which case the existing TTL
ef8014e5
TU
115 would take precedence. If this value is not set and there
116 is no existing DNSKEY RRset, the TTL will default to the
117 SOA TTL. Setting the default TTL to <code class="literal">0</code>
118 or <code class="literal">none</code> removes it from the key.
16fde7f0
TU
119 </p>
120 </dd>
0a7ed886 121<dt><span class="term">-h</span></dt>
16fde7f0
TU
122<dd>
123 <p>
e62b9c9c 124 Emit usage message and exit.
16fde7f0
TU
125 </p>
126 </dd>
6f120589 127<dt><span class="term">-V</span></dt>
16fde7f0
TU
128<dd>
129 <p>
e62b9c9c 130 Prints version information.
16fde7f0
TU
131 </p>
132 </dd>
0a7ed886 133<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
16fde7f0
TU
134<dd>
135 <p>
0a7ed886 136 Sets the debugging level.
16fde7f0
TU
137 </p>
138 </dd>
8ec3c085 139<dt><span class="term">-E <em class="replaceable"><code>engine</code></em></span></dt>
6ea23853 140<dd>
16fde7f0 141 <p>
6ea23853
TU
142 Specifies the cryptographic hardware to use, when applicable.
143 </p>
16fde7f0 144 <p>
6ea23853
TU
145 When BIND is built with OpenSSL PKCS#11 support, this defaults
146 to the string "pkcs11", which identifies an OpenSSL engine
147 that can drive a cryptographic accelerator or hardware service
148 module. When BIND is built with native PKCS#11 cryptography
149 (--enable-native-pkcs11), it defaults to the path of the PKCS#11
150 provider library specified via "--with-pkcs11".
151 </p>
16fde7f0 152 </dd>
0a7ed886 153</dl></div>
16fde7f0
TU
154 </div>
155
156 <div class="refsection">
fd2597f7 157<a name="id-1.9"></a><h2>TIMING OPTIONS</h2>
16fde7f0
TU
158
159 <p>
0a7ed886
AU
160 Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS.
161 If the argument begins with a '+' or '-', it is interpreted as
2895f101
AU
162 an offset from the present time. For convenience, if such an offset
163 is followed by one of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi',
164 then the offset is computed in years (defined as 365 24-hour days,
165 ignoring leap years), months (defined as 30 24-hour days), weeks,
166 days, hours, or minutes, respectively. Without a suffix, the offset
bbbf2e27 167 is computed in seconds. To unset a date, use 'none' or 'never'.
0a7ed886 168 </p>
16fde7f0
TU
169
170 <div class="variablelist"><dl class="variablelist">
0a7ed886 171<dt><span class="term">-P <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
172<dd>
173 <p>
553ead32
EH
174 Sets the date on which a key is to be published to the zone.
175 After that date, the key will be included in the zone but will
176 not be used to sign it.
16fde7f0
TU
177 </p>
178 </dd>
e62b9c9c 179<dt><span class="term">-P sync <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
180<dd>
181 <p>
e62b9c9c
TU
182 Sets the date on which CDS and CDNSKEY records that match this
183 key are to be published to the zone.
16fde7f0
TU
184 </p>
185 </dd>
553ead32 186<dt><span class="term">-A <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
187<dd>
188 <p>
553ead32 189 Sets the date on which the key is to be activated. After that
5a24d24c 190 date, the key will be included in the zone and used to sign
553ead32 191 it.
16fde7f0
TU
192 </p>
193 </dd>
553ead32 194<dt><span class="term">-R <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
195<dd>
196 <p>
553ead32
EH
197 Sets the date on which the key is to be revoked. After that
198 date, the key will be flagged as revoked. It will be included
199 in the zone and will be used to sign it.
16fde7f0
TU
200 </p>
201 </dd>
f8e3e03c 202<dt><span class="term">-I <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
203<dd>
204 <p>
f8e3e03c
AU
205 Sets the date on which the key is to be retired. After that
206 date, the key will still be included in the zone, but it
207 will not be used to sign it.
16fde7f0
TU
208 </p>
209 </dd>
553ead32 210<dt><span class="term">-D <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
211<dd>
212 <p>
553ead32 213 Sets the date on which the key is to be deleted. After that
f8e3e03c
AU
214 date, the key will no longer be included in the zone. (It
215 may remain in the key repository, however.)
16fde7f0
TU
216 </p>
217 </dd>
e62b9c9c 218<dt><span class="term">-D sync <em class="replaceable"><code>date/offset</code></em></span></dt>
16fde7f0
TU
219<dd>
220 <p>
e62b9c9c
TU
221 Sets the date on which the CDS and CDNSKEY records that match this
222 key are to be deleted.
16fde7f0
TU
223 </p>
224 </dd>
3acf5eb9 225<dt><span class="term">-S <em class="replaceable"><code>predecessor key</code></em></span></dt>
16fde7f0
TU
226<dd>
227 <p>
3acf5eb9
AU
228 Select a key for which the key being modified will be an
229 explicit successor. The name, algorithm, size, and type of the
230 predecessor key must exactly match those of the key being
231 modified. The activation date of the successor key will be set
232 to the inactivation date of the predecessor. The publication
233 date will be set to the activation date minus the prepublication
234 interval, which defaults to 30 days.
16fde7f0
TU
235 </p>
236 </dd>
3acf5eb9
AU
237<dt><span class="term">-i <em class="replaceable"><code>interval</code></em></span></dt>
238<dd>
16fde7f0 239 <p>
3acf5eb9
AU
240 Sets the prepublication interval for a key. If set, then
241 the publication and activation dates must be separated by at least
242 this much time. If the activation date is specified but the
243 publication date isn't, then the publication date will default
244 to this much time before the activation date; conversely, if
245 the publication date is specified but activation date isn't,
246 then activation will be set to this much time after publication.
247 </p>
16fde7f0 248 <p>
3acf5eb9 249 If the key is being set to be an explicit successor to another
9d557856 250 key, then the default prepublication interval is 30 days;
3acf5eb9
AU
251 otherwise it is zero.
252 </p>
16fde7f0 253 <p>
3acf5eb9
AU
254 As with date offsets, if the argument is followed by one of
255 the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the
256 interval is measured in years, months, weeks, days, hours,
257 or minutes, respectively. Without a suffix, the interval is
258 measured in seconds.
259 </p>
16fde7f0 260 </dd>
553ead32 261</dl></div>
16fde7f0
TU
262 </div>
263
264 <div class="refsection">
fd2597f7 265<a name="id-1.10"></a><h2>PRINTING OPTIONS</h2>
16fde7f0
TU
266
267 <p>
2eeb74d1 268 <span class="command"><strong>dnssec-settime</strong></span> can also be used to print the
2895f101
AU
269 timing metadata associated with a key.
270 </p>
16fde7f0
TU
271
272 <div class="variablelist"><dl class="variablelist">
2895f101 273<dt><span class="term">-u</span></dt>
16fde7f0
TU
274<dd>
275 <p>
e62b9c9c 276 Print times in UNIX epoch format.
16fde7f0
TU
277 </p>
278 </dd>
e62b9c9c 279<dt><span class="term">-p <em class="replaceable"><code>C/P/Psync/A/R/I/D/Dsync/all</code></em></span></dt>
16fde7f0
TU
280<dd>
281 <p>
e62b9c9c 282 Print a specific metadata value or set of metadata values.
2895f101 283 The <code class="option">-p</code> option may be followed by one or more
e62b9c9c
TU
284 of the following letters or strings to indicate which value
285 or values to print:
2895f101
AU
286 <code class="option">C</code> for the creation date,
287 <code class="option">P</code> for the publication date,
e62b9c9c 288 <code class="option">Psync</code> for the CDS and CDNSKEY publication date,
2895f101 289 <code class="option">A</code> for the activation date,
44d0f025 290 <code class="option">R</code> for the revocation date,
e62b9c9c
TU
291 <code class="option">I</code> for the inactivation date,
292 <code class="option">D</code> for the deletion date, and
293 <code class="option">Dsync</code> for the CDS and CDNSKEY deletion date
2895f101 294 To print all of the metadata, use <code class="option">-p all</code>.
16fde7f0
TU
295 </p>
296 </dd>
2895f101 297</dl></div>
16fde7f0
TU
298 </div>
299
300 <div class="refsection">
fd2597f7 301<a name="id-1.11"></a><h2>SEE ALSO</h2>
16fde7f0
TU
302
303 <p><span class="citerefentry">
304 <span class="refentrytitle">dnssec-keygen</span>(8)
305 </span>,
306 <span class="citerefentry">
307 <span class="refentrytitle">dnssec-signzone</span>(8)
308 </span>,
553ead32
EH
309 <em class="citetitle">BIND 9 Administrator Reference Manual</em>,
310 <em class="citetitle">RFC 5011</em>.
311 </p>
16fde7f0
TU
312 </div>
313
553ead32
EH
314</div></body>
315</html>