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