| blob | 576d085dde17ac8b435e701e75c092ba804b645d |
1 .\" $NetBSD: zkt-signer.8,v 1.1.1.1 2015/07/08 15:37:53 christos Exp $
2 .\"
3 .TH zkt-signer 8 "Nov 27, 2010" "ZKT 1.1" ""
4 \" turn off hyphenation
5 .\" if n .nh
6 .nh
7 .SH NAME
8 zkt-signer \(em Secure DNS zone signing tool
10 .SH SYNOPSYS
11 .na
12 .B zkt-signer
13 .RB [ \-L
14 .IR "file" ]
15 .RB [ \-V
16 .IR "view" ]
17 .RB [ \-c
18 .IR "file" ]
19 .RB [ \-O
20 .IR "optstr" ]
21 .RB [ \-fhnr ]
22 .RB [ \-v
23 .RB [ \-v ]]
24 .B \-N
25 .I "named.conf"
26 .RI [ zone
27 .RI "" ... ]
28 .br
29 .B zkt-signer
30 .RB [ \-L
31 .IR "file" ]
32 .RB [ \-V
33 .IR "view" ]
34 .RB [ \-c
35 .IR "file" ]
36 .RB [ \-O
37 .IR "optstr" ]
38 .RB [ \-fhnr ]
39 .RB [ \-v
40 .RB [ \-v ]]
41 .RB [ \-D
42 .IR "directory" ]
43 .RI [ zone
44 .RI "" ... ]
45 .br
46 .B zkt-signer
47 .RB [ \-L
48 .IR "file" ]
49 .RB [ \-V
50 .IR "view" ]
51 .RB [ \-c
52 .IR "file" ]
53 .RB [ \-O
54 .IR "optstr" ]
55 .RB [ \-fhnr ]
56 .RB [ \-v
57 .RB [ \-v ]]
58 .B \-o
59 .IR "origin"
60 .RI [ zonefile ]
62 .SH DESCRIPTION
63 The
64 .I zkt-signer
65 command is a wrapper around
66 .I dnssec-signzone(8)
67 and
68 .I dnssec-keygen(8)
69 to sign a zone and manage the necessary zone keys.
70 It is able to increment the serial number before signing the zone
71 and can trigger
72 .I named(8)
73 to reload the signed zone file.
74 The command controls several secure zones and, if started in regular
75 intervals via
76 .IR cron(8) ,
77 can do all that stuff automatically.
78 .PP
79 In the most useful usage scenario the command will be called with option
80 .B \-N
81 to read the secure zones out of the given
82 .I named.conf
83 file.
84 If you have a configuration file with views, you have to use option
85 -V viewname or --view viewname to specify the name of the view.
86 Alternately you could link the executable file to a second name like
87 .I zkt-signer-viewname
88 and use that command to specify the name of the view.
89 .br
90 All master zone statements will be scanned for filenames
91 ending with ".signed".
92 These zones will be checked if the necessary zone- and key signing keys
93 are existent and fresh enough to be used in the signing process.
94 If one or more out-dated keys are found, new keying material will be generated via
95 the
96 .I dnssec-keygen(8)
97 command and the old keys will be marked as depreciated.
98 So the command do anything needed for a zone key rollover as defined by [2].
99 .PP
100 If the resigning interval is reached or any new key must be announced,
101 the serial number of the zone will be incremented and the
102 .I dnssec-signzone(8)
103 command will be evoked to sign the zone.
104 After that, if the option
105 .B \-r
106 is given, the
107 .I rndc(8)
108 command will be called to reload the zone on the
109 nameserver.
110 .PP
111 In the second form of the command it is possible to specify a directory
112 tree with the option
113 .B \-D
114 .IR dir .
115 Every secure zone found in a subdirectory below
116 .I dir
117 will be signed.
118 However, it is also possible to reduce the signing to those
119 zones given as arguments.
120 .br
121 If
122 .B \-D
123 is ommitted (and neither
124 .B \-N
125 nor
126 .BI \-o origin
127 is specified) the default directory specified in the
128 .I dnssec.conf
129 file by the parameter
130 .I zonedir
131 will be used as top level directory.
132 .ig
133 In directory mode the pre-requisite is, that the directory name is
134 exactly (including the trailing dot) the same as the zone name.
135 ..
137 .SH OPTIONS
138 .TP
139 .BI \-L " file|dir" ", \-\-logfile=" file|dir
140 Specify the name of a log file or a directory where
141 logfiles are created with a name like
142 .fam C
143 .\"# define LOG_FNAMETMPL "/zkt-%04d-%02d-%02dT%02d%02d%02dZ.log"
144 .RI zkt- YYYY-MM-DD T hhmmss Z.log .
145 .fam T
146 .\" \&.
147 If the argument is not an absolute path name and a zone directory
148 is specified in the config file, this will be prepended to the given name.
149 This option is also settable in the dnssec.conf file via the parameter
150 .BI LogFile .
151 .br
152 The default is no file logging, but error logging to syslog with facility
153 .BI USER
154 at level
155 .BI ERROR
156 is enabled by default.
157 These parameters are settable via the config file parameter
158 .BI "SyslogFacility" ,
159 .BI "SyslogLevel" ,
160 .BI "LogFile"
161 and
162 .BI "Loglevel" .
163 .br
164 The additional parameter
165 .BI VerboseLog
166 specifies the verbosity (0|1|2) of messages that will be logged
167 with level
168 .BI DEBUG
169 to file and syslog.
171 .TP
172 .BI \-V " view" ", \-\-view=" view
173 Try to read the default configuration out of a file named
174 .I dnssec-<view>.conf .
175 Instead of specifying the \-V or --view option every time,
176 it is also possible to create a hard- or softlink to the
177 executable file with an additional name like
178 .I zkt-signer-<view> .
179 .TP
180 .BI \-c " file" ", \-\-config=" file
181 Read configuration values out of the specified file.
182 Otherwise the default config file is read or build-in defaults
183 will be used.
184 .TP
185 .BI \-O " optstr" ", \-\-config-option=" optstr
186 Set any config file option via the commandline.
187 Several config file options can be specified via the argument string
188 but have to be delimited by semicolon (or newline).
189 .TP
190 .BR \-f ", " \-\-force
191 Force a resigning of the zone, regardless if the resigning interval
192 is reached or new keys must be announced.
193 .TP
194 .BR \-n ", " \-\-noexec
195 Don't execute the
196 .I dnssec-signzone(8)
197 command.
198 Currently this option is of very limited usage.
199 .TP
200 .BR \-r ", " \-\-reload
201 Reload the zone via
202 .I rndc(8)
203 after successful signing.
204 In a production environment it is recommended to use this option
205 to be sure that a freshly signed zone will be immediately propagated.
206 However, that's only feasable if named runs on the signing
207 machine, which is not recommended.
208 .ig
209 Otherwise the signed zonefile must be copied to the production
210 server before reloading the zone.
211 If this is the case, the parameter
212 .I propagation
213 in the
214 .I dnssec.conf
215 file must be set to a reasonable value.
216 ..
217 .TP
218 .BR \-v ", " \-\-verbose
219 Verbose mode (recommended).
220 A second
221 .B \-v
222 will be a little more verbose.
223 .TP
224 .BR \-h ", " \-\-help
225 Print out the online help.
227 .SH SAMPLE USAGE
228 .TP
229 .fam C
230 .B "zkt-signer \-N /var/named/named.conf \-r \-v \-v
231 .fam T
232 Sign all secure zones found in the named.conf file and, if necessary,
233 trigger a reload of the zone.
234 Print some explanatory remarks on stdout.
235 .TP
236 .fam C
237 .B "zkt-signer \-D zonedir/example.net. \-f \-v \-v
238 .fam T
239 Force the signing of the zone found in the directory
240 .I zonedir/example.net .
241 Do not reload the zone.
242 .TP
243 .fam C
244 .B "zkt-signer \-D zonedir \-f \-v \-v example.net.
245 .fam T
246 Same as above.
247 .TP
248 .fam C
249 .B "zkt-signer \-f \-v \-v example.net.
250 .fam T
251 Same as above if the
252 .I dnssec.conf
253 file contains the path of the parent directory of the
254 .I example.net
255 zone.
256 .TP
257 .fam C
258 .B "zkt-signer \-f \-v \-v \-o example.net. zone.db
259 .fam T
260 Same as above if we are in the directory containing the
261 .I example.net
262 files.
263 .TP
264 .fam C
265 .B "zkt-signer \-\-config-option='ResignInterval 1d; Sigvalidity 28h; \e
266 .B ZSKlifetime 2d;' \-v \-v \-o example.net. zone.db
267 .fam T
268 .br
269 Sign the example.net zone but override some config file values with parameters
270 given on the commandline.
272 .SH Zone setup and initial preparation
273 .TP
274 Create a separate directory for every secure zone.
275 .br
276 This is useful because there are many additional files needed to
277 secure a zone.
278 Besides the zone file
279 .RI ( zone.db ),
280 there is a signed zone file
281 .RI ( zone.db.signed),
282 a minimum of four files containing the key material,
283 a file called
284 .I dnskey.db
285 with the current used keys,
286 and the
287 .I dsset-
288 and
289 .IR keyset- files
290 created by the
291 .I dnssec-signzone(8)
292 command.
293 So in summary there is a minimum of nine files used per secure zone.
294 For every additional key there are two extra files and
295 every delegated subzone creates also two or three files.
296 .TP
297 Name the directory just like the zone.
298 .br
299 That's only needed if you want to use the zkt-signer command in
300 directory mode
301 .RB ( \-D ).
302 Then the name of the zone will be parsed out of the directory name.
303 .TP
304 Change the name of the zone file to \fIzone.db\fP
305 Otherwise you have to set the name via the
306 .I dnssec.conf
307 parameter
308 .IR zonefile ,
309 or you have to use the option
310 .B \-o
311 to name the zone and specify the zone file as argument.
312 .TP
313 Add the name of the signed zonefile to the \fInamed.conf\fP file
314 The filename is the name of the zone file with the
315 extension
316 .IR .signed .
317 Create an empty file with the name
318 .IB zone.db .signed
319 in the zone directory.
320 .TP
321 Include the keyfile in the zone.
322 The name of the keyfile is settable by the
323 .I dnssec.conf
324 parameter
325 .I keyfile .
326 The default is
327 .I dnskey.db .
328 .br
329 .if t \{\
330 .nf
331 .fam C
332 ...
333 IN NS ns1.example.net.
334 IN NS ns2.example.net.
335 $INCLUDE dnskey.db
336 ...
337 .fi
338 .fam T
339 You can also run
340 .I zkt-conf(8)
341 in the secure zone directory to do this.
342 Try
343 .br
344 .if t \{\
345 .nf
346 .fam C
347 $ zkt-conf -w zone.db
348 .fi
349 .fam T
350 .\}
351 .TP
352 Control the format of the SOA-Record
353 For automatic incrementation of the serial number, the SOA-Record
354 must be formated, so that the serial number is on a single line and
355 left justified in a field of at least 10 spaces!
356 .if t \{\
357 .fam C
358 .\"fi 0
359 .nf
360 @ IN SOA ns1.example.net. hostmaster.example.net. (
361 60 ; Serial
362 43200 ; Refresh
363 1800 ; Retry
364 2W ; Expire
365 7200 ); Minimum
366 .fi
367 .fam T
368 .\}
369 If you use BIND version 9.4 or later and
370 use the unixtime format for the serial number (which is the default since ZKT-1.0)
371 this is not necessary.
372 See also the parameter Serialformat in
373 .IR dnssec.conf .
374 .TP
375 Try to sign the zone
376 If the current working directory is the directory of the zone
377 .IR example.net ,
378 use the command
379 .fam C
380 .nf
381 .sp 0.5
382 $ zkt-signer \-D .. \-v \-v example.net
383 or
384 $ zkt-signer \-o example.net.
385 .sp 0.5
386 .fi
387 .fam T
388 to create the initial keying material and a signed zone file.
389 Then try to load the file on the name server.
391 .SH ENVIRONMENT VARIABLES
392 .TP
393 ZKT_CONFFILE
394 Specifies the name of the default global configuration file.
396 .SH FILES
397 .TP
398 .I /var/named/dnssec.conf
399 Built-in default global configuration file.
400 The name of the default global config file is settable via
401 the environment variable ZKT_CONFFILE.
402 Use
403 .I zkt-conf(8)
404 with option
405 .B \-w
406 or
407 .I dnssec-zkt(8)
408 with option
409 .B \-Z
410 to create an initial config file.
411 .TP
412 .I /var/named/dnssec-<view>.conf
413 View specific global configuration file.
414 .TP
415 .I ./dnssec.conf
416 Local configuration file.
417 The file contains typically only the diff to the global site wide config file.
418 Use for example
419 .fam C
420 .nf
421 .sp 0.5
422 $ zkt-conf -w -l -O "key_ttl: 5d"
423 .sp 0.5
424 .fi
425 .fam T
426 to create a local config file with a different key ttl time.
427 .TP
428 .I dnskey.db
429 The file contains the currently used key and zone signing keys.
430 It will be created by
431 .IR dnsssec-signer(8) .
432 The name of the file is settable via the dnssec configuration
433 file (parameter
434 .IR keyfile ).
435 .TP
436 .I zone.db
437 This is the zone file.
438 The name of the file is settable via the dnssec configuration
439 file (parameter
440 .IR zonefile ).
442 .SH BUGS
443 .PP
444 The named.conf parser is a bit rudimental and not
445 very well tested.
447 .SH AUTHORS
448 The man page is written by
449 Holger Zuleger and Mans Nilsson
451 .SH COPYRIGHT
452 Copyright (c) 2005 \- 2010 by Holger Zuleger.
453 Licensed under the BSD Licence. There is NO warranty; not even for MERCHANTABILITY or
454 FITNESS FOR A PARTICULAR PURPOSE.
455 .\"--------------------------------------------------
457 .SH SEE ALSO
458 dnssec-keygen(8), dnssec-signzone(8), rndc(8), named.conf(5), zkt-conf(8), zkt-ls(8), zkt-keygen(8)
459 .br
460 RFC4033, RFC4034, RFC4035
461 .br
462 [1] DNSSEC HOWTO Tutorial by Olaf Kolkman, RIPE NCC
463 .br
464 (http://www.nlnetlabs.nl/dnssec_howto/)
465 .br
466 [2] RFC4641 "DNSSEC Operational Practices" by Miek Gieben and Olaf Kolkman
467 .br
468 (http://www.ietf.org/rfc/rfc4641.txt)