diff options
Diffstat (limited to 'contrib/zkt/dnssec-signer.8')
| -rw-r--r-- | contrib/zkt/dnssec-signer.8 | 436 |
1 files changed, 436 insertions, 0 deletions
diff --git a/contrib/zkt/dnssec-signer.8 b/contrib/zkt/dnssec-signer.8 new file mode 100644 index 0000000..07c3c6c --- /dev/null +++ b/contrib/zkt/dnssec-signer.8 @@ -0,0 +1,436 @@ +.TH dnssec-signer 8 "June 27, 2008" "ZKT 0.96" "" +\" turn off hyphenation +.\" if n .nh +.nh +.SH NAME +dnssec-signer \(em Secure DNS zone signing tool + +.SH SYNOPSYS +.na +.B dnssec-signer +.RB [ \-L|--logfile +.IR "file" ] +.RB [ \-V|--view +.IR "view" ] +.RB [ \-c +.IR "file" ] +.RB [ \-fhnr ] +.RB [ \-v +.RB [ \-v ]] +.B \-N +.I "named.conf" +.RI [ zone +.RI "" ... ] +.br +.B dnssec-signer +.RB [ \-L|--logfile +.IR "file" ] +.RB [ \-V|--view +.IR "view" ] +.RB [ \-c +.IR "file" ] +.RB [ \-fhnr ] +.RB [ \-v +.RB [ \-v ]] +.RB [ \-D +.IR "directory" ] +.RI [ zone +.RI "" ... ] +.br +.B dnssec-signer +.RB [ \-L|--logfile +.IR "file" ] +.RB [ \-V|--view +.IR "view" ] +.RB [ \-c +.IR "file" ] +.RB [ \-fhnr ] +.RB [ \-v +.RB [ \-v ]] +.B \-o +.IR "origin" +.RI [ zonefile ] + +.SH DESCRIPTION +The +.I dnssec-signer +command is a wrapper around +.I dnssec-signzone(8) +and +.I dnssec-keygen(8) +to sign a zone and manage the necessary zone keys. +It's able to increment the serial number before signing the zone +and can trigger +.I named(8) +to reload the signed zone file. +The command controls several secure zones and, if started in regular +intervals via +.IR cron(8) , +can do all that stuff automatically. +.PP +In the most useful usage scenario the command will be called with option +.B \-N +to read the secure zones out of the given +.I named.conf +file. +If you have a configuration file with views, you have to use option +-V viewname or --view viewname to specify the name of the view. +Alternatively you could link the executable file to a second name like +.I dnssec-signer-viewname +and use that command to specify the name of the view. +All master zone statements will be scanned for filenames +ending with ".signed". +These zones will be checked if the necessary zone- and key signing keys +are existent and fresh enough to be used in the signing process. +If some out-dated keys where found, new keying material will be generated via +the +.I dnssec-keygen(8) +command and the old ones will be marked as depreciated. +So the command do anything needed for a zone key rollover as defined by [2]. +.PP +If the resigning interval is reached or any new key must be announced, +the serial number of the zone will be incremented and the +.I dnssec-signzone(8) +command will be evoked to sign the zone. +After that, if the option +.B \-r +is given, the +.I rndc(8) +command will be called to reload the zone on the +nameserver. +.PP +In the second form of the command it's possible to specify a directory +tree with the option +.B \-D +.IR dir . +Every secure zone found in a subdirectory below +.I dir +will be signed. +However, it's also possible to reduce the signing to those +zones given as arguments. +In directory mode the pre-requisite is, that the directory name is +exactly (including the trailing dot) the same as the zone name. +.PP +In the last form of the command, the functionality is more or less the same +as the +.I dnssec-signzone (8) +command. +The parameter specify the zone file name and the option +.B \-o +takes the name of the zone. +.PP +If neither +.B \-N +nor +.B \-D +nor +.B \-o +is given, then the default directory specified in the +.I dnssec.conf +file by the parameter +.I zonedir +will be used as the top level directory. + +.SH OPTIONS +.TP +.BI \-L " file|dir" ", \-\-logfile=" file|dir +Specify the name of a log file or a directory where +logfiles are created with a name like +.fam C +.\"# define LOG_FNAMETMPL "/zkt-%04d-%02d-%02dT%02d%02d%02dZ.log" +.RI zkt- YYYY-MM-DD T hhmmss Z.log . +.fam T +.\" \&. +If the argument is not an absolute path name and a zone directory +is specified in the config file, this will prepend the given name. +This option is also settable in the dnssec.conf file via the parameter +.BI LogFile . +.br +The default is no file logging, but error logging to syslog with facility +.BI USER +at level +.BI ERROR +is enabled by default. +These parameters are settable via the config file parameter +.BI "SyslogFacility:" , +.BI "SyslogLevel:" , +.BI "LogFile:" +and +.BI "Loglevel" . +.br +There is an additional parameter +.BI VerboseLog: +which specifies the verbosity (0|1|2) of messages that will be logged +with level +.BI DEBUG +to file and syslog. + +.TP +.BI \-V " view" ", \-\-view=" view +Try to read the default configuration out of a file named +.I dnssec-<view>.conf . +Instead of specifying the \-V or --view option every time, +it's also possible to create a hard or softlink to the +executable file with an additional name like +.I dnssec-zkt-<view> . +.TP +.BI \-c " file" ", \-\-config=" file +Read configuration values out of the specified file. +Otherwise the default config file is read or build-in defaults +will be used. +.TP +.BI \-O " optstr" ", \-\-config-option=" optstr +Set any config file option via the commandline. +Several config file options could be specified at the argument string +but have to be delimited by semicolon (or newline). +.TP +.BR \-f ", " \-\-force +Force a resigning of the zone, regardless if the resigning interval +is reached, or any new keys must be announced. +.TP +.BR \-n ", " \-\-noexec +Don't execute the +.I dnssec-signzone(8) +command. +Currently this option is of very limited usage. +.TP +.BR \-r ", " \-\-reload +Reload the zone via +.I rndc(8) +after successful signing. +In a production environment it's recommended to use this option +to be sure that a freshly signed zone will be immediately propagated. +However, that's only feasable if the named runs on the signing +machine, which is not recommended. +Otherwise the signed zonefile must be copied to the production +server before reloading the zone. +If this is the case, the parameter +.I propagation +in the +.I dnssec.conf +file must be set to a reasonable value. +.TP +.BR \-v ", " \-\-verbose +Verbose mode (recommended). +A second +.B \-v +will be a little more verbose. +.TP +.BR \-h ", " \-\-help +Print out the online help. + +.SH SAMPLE USAGE +.TP +.fam C +.B "dnssec-signer \-N /var/named/named.conf \-r \-v \-v +.fam T +Sign all secure zones found in the named.conf file and, if necessary, +trigger a reload of the zone. +Print some explanatory remarks on stdout. +.TP +.fam C +.B "dnssec-signer \-D zonedir/example.net. \-f \-v \-v +.fam T +Force the signing of the zone found in the directory +.I zonedir/example.net . +Do not reload the zone. +.TP +.fam C +.B "dnssec-signer \-D zonedir \-f \-v \-v example.net. +.fam T +Same as above. +.TP +.fam C +.B "dnssec-signer \-f \-v \-v example.net. +.fam T +Same as above if the +.I dnssec.conf +file contains the path of the parent directory of the +.I example.net +zone. +.TP +.fam C +.B "dnssec-signer \-f \-v \-v \-o example.net. zone.db +.fam T +Same as above if we are in the directory containing the +.I example.net +files. +.TP +.fam C +.B "dnssec-signer \-\-config-option='ResignInterval 1d; Sigvalidity 28h; \e +.B ZSK_lifetime 2d;' \-v \-v \-o example.net. zone.db +.fam T +.br +Sign the example.net zone but overwrite some config file values with the parameters +given on the commandline. + +.SH Zone setup and initial preparation +.TP +Create a separate directory for every secure zone. +.br +This is useful because there are many additional files needed to +secure a zone. +Besides the zone file +.RI ( zone.db ), +there is a signed zone file +.RI ( zone.db.signed), +a minimum of four files containing the keying material, +a file called +.I dnskey.db +with the current used keys, +and the +.I dsset- +and +.IR keyset- files +created by the +.I dnssec-signzone(8) +command. +So in summary there is a minimum of nine files used per secure zone. +For every additional key there are two extra files and +every delegated subzone creates also two or three files. +.TP +Name the directory just like the zone. +.br +That's only needed if you want to use the dnssec-signer command in +directory mode +.RB ( \-D ). +Then the name of the zone will be parsed out of the directory name. +.TP +Change the name of the zone file to \fIzone.db\fP +Otherwise you have to set the name via the +.I dnssec.conf +parameter +.IR zonefile , +or you have to use the option +.B \-o +to name the zone and specify the zone file as argument. +.TP +Add the name of the signed zonefile to the \fInamed.conf\fP file +The filename is the name of the zone file with the +extension +.IR .signed . +Create an empty file with the name +.IB zonefile .signed +in the zone directory. +.TP +Include the keyfile in the zone. +The name of the keyfile is settable by the +.I dnssec.conf +parameter +.I keyfile . +The default is +.I dnskey.db . +.br +.if t \{\ +.nf +.fam C + ... + IN NS ns1.example.net. + IN NS ns2.example.net. +$INCLUDE dnskey.db + ... +.fi +.fam T +.\} +.TP +Control the format of the SOA-Record +For automatic incrementation of the serial number, the SOA-Record +must be formated, so that the serial number is on a single line and +left justified in a field of at least 10 spaces! +.if t \{\ +.fam C +.fi 0 +@ IN SOA ns1.example.net. hostmaster.example.net. ( + 60 ; Serial + 43200 ; Refresh + 1800 ; Retry + 2W ; Expire + 7200 ); Minimum +.fi +.fam T +.\} +If you use a BIND Verison of 9.4 or greater and +use the unixtime format for the serial number (See parameter +Serialformat in +.IR dnssec.conf ) +than this is not necessary. +.TP +Try to sign the zone +If the current working directory is the directory of the zone +.IR example.net , +use the command +.fam C +.nf +.sp 0.5 + $ dnssec-signer \-D .. \-v \-v example.net + $ dnssec-signer \-o example.net. +.sp 0.5 +.fi +.fam T +to create the initial keying material and a signed zone file. +Then try to load the file on the name server. + +.SH ENVIRONMENT VARIABLES +.TP +ZKT_CONFFILE +Specifies the name of the default global configuration files. + +.SH FILES +.TP +.I /var/named/dnssec.conf +Built-in default global configuration file. +The name of the default global config file is settable via +the environment variable ZKT_CONFFILE. +Use +.I dnssec-zkt(8) +with option +.B \-Z +to create an initial config file. +.TP +.I /var/named/dnssec-<view>.conf +View specific global configuration file. +.TP +.I ./dnssec.conf +Local configuration file. +.TP +.I dnskey.db +The file contains the currently used key and zone signing keys. +It will be created by +.IR dnsssec-signer(8) . +The name of the file is settable via the dnssec configuration +file (parameter +.IR keyfile ). +.TP +.I zone.db +This is the zone file. +The name of the file is settable via the dnssec configuration +file (parameter +.IR zonefile ). + +.SH BUGS +.PP +The zone name given as an argument must be ending with a dot. +.PP +The named.conf parser is a little bit rudimental and not +very well tested. + +.SH AUTHOR +Holger Zuleger + +.SH COPYRIGHT +Copyright (c) 2005 \- 2008 by Holger Zuleger. +Licensed under the GPL 2. There is NO warranty; not even for MERCHANTABILITY or +FITNESS FOR A PARTICULAR PURPOSE. +.\"-------------------------------------------------- +.SH SEE ALSO +dnssec-keygen(8), dnssec-signzone(8), rndc(8), named.conf(5), dnssec-zkt(8) +.br +RFC4033, RFC4034, RFC4035 +.br +[1] DNSSEC HOWTO Tutorial by Olaf Kolkman, RIPE NCC +.br +(http://www.nlnetlabs.nl/dnssec_howto/) +.br +[2] RFC4641 "DNSSEC Operational Practices" by Miek Gieben and Olaf Kolkman +.br +(http://www.ietf.org/rfc/rfc4641.txt) |