.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "ROLLERD 1p" .TH ROLLERD 1p "2012-06-21" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" rollerd \- DNSSEC\-Tools daemon to manage DNSSEC key rollover .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& rollerd [\-options] \-rrfile .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBrollerd\fR daemon manages key rollover for zones. \fBrollerd\fR is just a scheduler for zone rollover; it uses \fBzonesigner\fR to perform the actual key generation, zone signing, and key manipulation. .PP \&\fBrollerd\fR manages both \s-1KSK\s0 and \s-1ZSK\s0 rollover, though only one rollover type per zone may take place at a time. Initiation of \s-1KSK\s0 rollovers takes precedence over the initiation of \s-1ZSK\s0 rollovers. .PP \&\fBrollerd\fR uses two methods of key rollover. The Pre-Publish Method of key rollover is used for \s-1ZSK\s0 key rollovers. The Double Signature Method of key rollover is used for \s-1KSK\s0 rollovers. These methods are described more fully below. .PP \&\fBrollerd\fR maintains zone rollover state in files called \fIrollrec\fR files; zone/key mappings are stored in \fIkeyrec\fR files. \fBrollerd\fR only modifies \&\fIrollrec\fR files. For the most part, \fBrollerd\fR does not modify \fIkeyrec\fR directly, but relies on \fBzonesigner\fR to update those files as needed. (The exceptions where \fBrollerd\fR modifies \fIkeyrec\fR files. At start-up, it will mark each managed zone's \fIkeyrec\fR file to indicate the zone is under \&\fBrollerd\fR's control. During the course of rollover, \fBrollerd\fR will also update a zone's rollover times in its \fIkeyrec\fR file.) .PP The administrator may control \fBrollerd\fR with the \fBrollctl\fR command. A large number of commands are available to control and modify \fBrollerd\fR's operation, as well as to retrieve information about rollover and daemon status. .PP The zone administrator will need to update their zone files periodically. If \&\fBrollerd\fR is managing zones, then problems could arise if modified zones were signed without \fBrollerd\fR's knowledge. To prevent such problems, \fBrollerd\fR can be configured to automatically re-sign a zone when its zonefile is found to be newer than its corresponding signed zonefile. (The files' \*(L"last modification\*(R" timestamps are compared.) The zone will be re-signed without any other rollover actions taking place, so no new keys will be generated, no key rollovers will occur, and the various rollover timers will be unaffected. .PP \&\fBrollerd\fR will perform these re-signs by default, but this can be further controlled by the \fIautosign\fR configuration parameter and \fBrollerd\fR's \&\fB\-autosign\fR/\fB\-noautosign\fR command line options. If \fBrollerd\fR is configured to not perform automatic re-signing, the administrator can still get this controlled behavior by use of the \fBzonesigner\fR or \fBrollctl\fR commands. .PP If the \fBrollrec\fR file does not exist or is of zero length, \fBrollerd\fR will give an error message and continue running. It will periodically wake up and check for a usable \fBrollrec\fR file. Once it finds the specified \fBrollrec\fR file exists and isn't empty, then it will proceed with normal rollover management. .SS "\s-1ZSK\s0 Rollover Using the Pre-Publish Method" .IX Subsection "ZSK Rollover Using the Pre-Publish Method" The Pre-Publish Method has four phases that are entered when it is time to perform \s-1ZSK\s0 rollover: .PP .Vb 4 \& 1. wait for old zone data to expire from caches \& 2. sign the zone with the KSK and Published ZSK \& 3. wait for old zone data to expire from caches \& 4. adjust keys in keyrec and sign the zone with new Current ZSK .Ve .PP \&\fBrollerd\fR uses the \fBzonesigner\fR command during \s-1ZSK\s0 rollover phases 2 and 4. \&\fBzonesigner\fR will generate keys as required and sign the zone during these two phases. .PP The Pre-Publish Method of key rollover is defined in the Step-by-Step \s-1DNS\s0 Security Operator Guidance Document. See that document for more detailed information. .SS "\s-1KSK\s0 Rollover Using the Double Signature Method" .IX Subsection "KSK Rollover Using the Double Signature Method" The Double Signature Method has seven phases that are entered when it is time to perform \s-1KSK\s0 rollover: .PP .Vb 7 \& 1. wait for old zone data to expire from caches \& 2. generate a new (published) KSK \& 3. wait for the old DNSKEY RRset to expire from caches \& 4. roll the KSKs \& 5. transfer new keyset to the parent \& 6. wait for parent to publish the new DS record \& 7. reload the zone .Ve .PP \&\fBrollerd\fR uses the \fBzonesigner\fR command during \s-1KSK\s0 rollover phases 2 and 4. \&\fBzonesigner\fR will generate keys as required and sign the zone during these two phases. .PP Currently, step 6 is handled manually. In step 5, \fBrollerd\fR informs the administrator via email that the zone's keyset must be transferred to its parent in order for rollover to continue. In step 6, after the keyset has been transferred to the parent and the parent has published a new \s-1DS\s0 record, the administrator uses \fBrollctl\fR to inform \fBrollerd\fR that the \s-1DS\s0 record has been published and rollover may continue. .PP The Double Signature Method of key rollover is defined in the Step-by-Step \&\s-1DNS\s0 Security Operator Guidance Document. See that document for more detailed information. .SS "\s-1KSK\s0 Rollover Using the Double Signature Method and \s-1RFC5011\s0" .IX Subsection "KSK Rollover Using the Double Signature Method and RFC5011" \&\s-1RFC5011\s0 describes how remote-validating resolvers must track \s-1KSK\s0 changes within a zone. If configured for \s-1RFC5011\s0 behavior, \fBrollerd\fR and \&\fBzonesigner\fR add an extra-long period of time between the point a new \s-1KSK\s0 is created and published and the point where the actual switch to using it takes place. \s-1RFC5011\s0 specifies that remote validators should add a \*(L"hold-down timer\*(R" to the rollover process, such that the new key is not added as a trust-anchor until 30 days have past. Thus, \fBrollerd\fR will wait for 60 days (by default) during phase 3 of the \s-1KSK\s0 rollover process if the \*(L"istrustanchor\*(R" field of the \fIrollrec\fR definition has been set to either 1 or \*(L"yes\*(R". To wait for a different length of time other than 60 days, use the \fBholddowntime\fR field. .PP At this time, the other conventions of \s-1RFC5011\s0 are not being followed. Specifically, it's not waiting for a while before removing the old key and it's not adding the revoke bit to the old key after switching. .SS "Site-Specific Rollover Actions" .IX Subsection "Site-Specific Rollover Actions" An administrator can specify site-specific commands to be run during the various rollover phases. The commands can be run in place of the default \&\fBrollerd\fR rollover actions, or in addition to them. This subsection describes how to make use of site-specific rollover actions. .PP This capability is provided to allow different installations to handle rollover according to their specific needs. For example, it is anticipated that this might be helpful to sites using \s-1HSM\s0 hardware, or to allow for enhanced reporting to administrators. This has been used with simple test programs to ensure that it actually works. However, it has not yet been used in actual \s-1HSM\s0 environment or with other production-level software replacements. .PP See the \fI\s-1ZSK\s0 Rollover Using the Pre-Publish Method\fR and \fI\s-1KSK\s0 Rollover Using the Double Signature Method\fR sections for descriptions of the default rollover actions. .PP \&\fB\s-1WARNING:\s0\fR This has the potential of being a dangerous capability. Be \&\fIvery\fR careful when setting up and using it. Take care with the site-specific commands to be executed and the permissions and ownership of \fBrollerd\fR and its data files. .PP \fIDNSSEC-Tools Configuration File Changes\fR .IX Subsection "DNSSEC-Tools Configuration File Changes" .PP The DNSSEC-Tools configuration file must be modified to tell \fBrollerd\fR what must be run for the non-default rollover phase actions. Key/value pairs may be set for each rollover phase to control how that phase differs from the default. .PP The value portion of the configuration entry contains the path to the site-specific phase command, along with any arguments it might need. Multiple commands are separated by bangs. .PP The reserved \fIdefault\fR command tells \fBrollerd\fR to use its normal rollover action for a particular phase. This may be combined with other commands to provide things such as specialized logging or notifications. .PP \&\fBrollerd\fR will only alter the behavior of a rollover phase if the configuration file contains an entry for that phase. If not, the default action will be taken. .PP For example, this configuration line tells \fBrollerd\fR that for \s-1ZSK\s0 rollover phase 2, instead of using its normal \fBzonesigner\fR executions it should run the \fBhsm-signer\fR command. .PP .Vb 1 \& prog\-zsk2 hsm\-signer .Ve .PP In this example, this configuration line informs \fBrollerd\fR that when entering \&\s-1KSK\s0 rollover phase 1 and \s-1ZSK\s0 rollover phase 1, it should execute the \&\fBlog-and-mail\fR command, then use the normal rollover action for those phases. .PP .Vb 2 \& prog\-ksk1 /usr/local/sbin/log\-and\-mail mary ! default \& prog\-zsk1 /usr/local/sbin/log\-and\-mail bob!default .Ve .PP The following configuration keys are used for controlling \s-1KSK\s0 rollover phases: \fIprog\-ksk1\fR, \fIprog\-ksk2\fR, \fIprog\-ksk3\fR, \fIprog\-ksk4\fR, \fIprog\-ksk5\fR, \&\fIprog\-ksk6\fR, and \fIprog\-ksk7\fR, .PP The following configuration keys are used for controlling \s-1ZSK\s0 rollover phases: \&\fIprog\-zsk1\fR, \fIprog\-zsk2\fR, \fIprog\-zsk3\fR, and \fIprog\-zsk4\fR. .PP The \fIprog-normal\fR configuration key controls the normal, non-rollover state. .PP \fISite-Specific Commands\fR .IX Subsection "Site-Specific Commands" .PP To be generally useful, the site-specific commands executed by \fBrollerd\fR will be given a standard set of arguments, and a standard set of exit values will be recognized. .PP The standard arguments from \fBrollerd\fR are: 1. zonename \- Zone to be handled. 2. phase \- Zone's current rollover phase (e.g., zsk1, ksk6, normal.) 3. rollrec name \- Zone's entry key in the rollrec file. 4. rollrec file \- The path to the rollrec file. 5. keyrec file \- The path to the zone's keyrec file. .PP The \fIprog-phase\fR entry in the configuration file may specify additional options and arguments for a command. These will be included on the execution command line \fIprior\fR to the standard arguments. .PP The standard exit values expected by \fBrollerd\fR are: 0. The zone can move to the next rollover phase. This is only applicable to the current command; other commands in this phase's command list must still be run. 1. The zone should stay in the current rollover phase. This is not necessarily the result of an error. 2. An error was found in the arguments given to the command. 3. An error was encountered during execution. .PP If a rollover phase's configuration entry lists multiple commands, they will be executed in the order listed. If any command in that command list fails, processing stops there. .PP The \fBrp-wrapper\fR command shows how a site-specific command may be written. \&\fBrp-wrapper\fR may be used as a skeleton on which to build a more useful rollover-phase command. .PP \fIConsiderations for Site-Specific Commands\fR .IX Subsection "Considerations for Site-Specific Commands" .PP The following should be taken into consideration when writing a site-specific command for a rollover phase. .IP "execution length" 4 .IX Item "execution length" A phase command should not execute very long. As currently written, \fBrollerd\fR serializes zone rollover. So the longer a phase command takes to execute, the longer it will take to get to the next zone. If a phase command sleeps or actively waits, so to speak, for the next phase timeout, then every zone \&\fBrollerd\fR manages will be left waiting. .IP "follow interface guidelines" 4 .IX Item "follow interface guidelines" Follow the standards for arguments and exit values. Not following the standards is likely to negatively affect zone rollover. .IP "frequency of command execution" 4 .IX Item "frequency of command execution" If \fBrollerd\fR is operating in its traditional \*(L"full list\*(R" processing mode, a phase command list will be executed every time \fBrollerd\fR cycles through its zone list and a zone is in that particular command's phase. For example, if prog_zsk1 is defined for example.com, that command list will be executed for example.com every time \fBrollerd\fR runs its zone list and finds example.com is in the \s-1ZSK\s0 phase 1 rollover state. A phase command \fBmust\fR take this into account so it doesn't perform its actions more frequently than necessary. This is most likely an issue for the various rollover wait states, and possibly the normal state. .Sp If \fBrollerd\fR is operating in the experimental \*(L"soon queue\*(R" processing mode, a phase command list will be executed for a zone only when a phase change occurs. Since phase changes are time queued, this should not happen more than once per phase. A phase command \fBshould\fR take this into account, in case the soon queue is reordered before the zone leaves the queue, or queue timing is relatively swift. This is most likely an issue for the various rollover wait states. .Sp \&\fB\s-1WARNING:\s0\fR \*(L"soon queue\*(R" processing is \fIexperimental\fR. Care should be taken when using this processing method, as it may still have some lingering bugs. .SS "Zone Reloading" .IX Subsection "Zone Reloading" \&\fBrollerd\fR has the opportunity to inform the \s-1DNS\s0 daemon to reload a zone in \&\s-1KSK\s0 phase 2, \s-1KSK\s0 phase 7, \s-1ZSK\s0 phase 2, and \s-1ZSK\s0 phase 4. This is the \&\fBrollerd\fR's default behavior. However, there are situations where this shouldn't be done, such as for off-line signing. .PP The \fBroll_loadzone\fR field of the DNSSEC-Tools configuration file is a boolean field that overrides the default to force the zone-reload behavior either on or off. This field takes precedence over the default. .PP Similarly, the \fB\-noreload\fR option prevents \fBrollerd\fR from requesting a zone reload, and it takes precedence over the \fBroll_loadzone\fR configuration field and the default. .SS "\fIrollrec\fP Files" .IX Subsection "rollrec Files" The zones to be managed by \fBrollerd\fR are described in a \fIrollrec\fR file. Generally speaking most people will want to use the \fBrollinit\fR command to create an initial \fIrollrec\fR file instead of typing their own from scratch. See the \s-1INITIALIZATION\s0 \s-1AND\s0 \s-1USAGE\s0 section below and the \fBrollinit\fR manual page for details. Each zone's entry contains data needed by \fBrollerd\fR and some data useful to a user. Below is a sample \fIrollrec\fR entry: .PP .Vb 10 \& roll "example.com" \& zonename "example.com" \& zonefile "example.com.signed" \& keyrec "example.com.krf" \& zonegroup "demo\-zones" \& directory "dir\-example.com" \& kskphase "0" \& zskphase "3" \& ksk_rollsecs "1172614842" \& ksk_rolldate "Tue Feb 27 22:20:42 2007" \& zsk_rollsecs "1172615087" \& zsk_rolldate "Tue Feb 27 22:24:47 2007" \& maxttl "60" \& display "1" \& phasestart "Tue Feb 27 22:25:07 2007" \& # optional records for RFC5011 rolling: \& istrustanchor "no" \& holddowntime "60D" .Ve .PP The first line gives the \fIrollrec\fR entry's name. The name distinguishes it from other \fIrollrec\fR entries and must be unique. This may be the zone's name, but this is not a requirement. The following lines give the zone's name, the zone's signed zone file, \fIkeyrec\fR file, the current rollover phases, the rollover timestamps, and other information. The zone group is optional and allows a set of related zones to be controlled with a single \&\fBrollctl\fR execution, rather than one execution per zone. .PP If either of the \fIzonefile\fR or \fIkeyrec\fR files do not exist, then a \*(L"roll\*(R" \&\fIrollrec\fR will be changed into a \*(L"skip\*(R" \fIrollrec\fR. That record will not be processed. .PP A more detailed explanation may be found in \fI\fIrollrec\fI\|(5)\fR. .SS "Directories" .IX Subsection "Directories" \&\fBrollerd\fR's execution directory is either the directory in which it is executed or the directory passed in the \fB\-directory\fR command-line option. Any files used by \fBrollerd\fR that were not specified with absolute paths use this directory as their base. .PP A \fIrollrec\fR file's \fIdirectory\fR field informs \fBrollerd\fR where the zone's files may be found. For that zone, \fBrollerd\fR will move into that directory, then return to its execution directory when it finishes rollover operations for that zone. If the \fIdirectory\fR value is a relative path, it will be appended to \fBrollerd\fR's execution directory. If the \fIdirectory\fR value is an absolute path, it will be used as is. .SS "Controlling \fBrollerd\fP with \fBrollctl\fP" .IX Subsection "Controlling rollerd with rollctl" The \fBrollctl\fR command is used to control the behavior of \fBrollerd\fR. A number of commands are available, such as starting or stopping rollover for a selected zone or all zones, turning on or off a \s-1GUI\s0 rollover display, and halting \fBrollerd\fR execution. The communications path between \fBrollerd\fR and \&\fBrollctl\fR is operating system-dependent. On Unix-like systems, it is a Unix pipe that should \fBonly\fR be writable by the user which runs \fIrollerd\fR. A more detailed explanation of \fBrollctl\fR may be found in \fI\fIrollctl\fI\|(8)\fR. .SS "A Note About Files and Filenames" .IX Subsection "A Note About Files and Filenames" There are a number of files and filenames used by \fBrollerd\fR and \&\fBzonesigner\fR. The user must be aware of the files used by these programs, where the files are located, and where the programs are executed. .PP By default, \fBrollerd\fR will change directory to the DNSSEC-Tools directory, though this may be changed by the \fB\-directory\fR option. Any programs started by \fBrollerd\fR, most importantly \fBzonesigner\fR, will run in this same directory. If files and directories referenced by these programs are named with relative paths, those paths must be relative to this directory. .PP The \fIrollrec\fR entry name is used as a key to the \fIrollrec\fR file and to the zone's \fIkeyrec\fR file. This entry does not have to be the name of the entry's domain, but it is a very good idea to make it so. Whatever is used for this entry name, the same name \fBmust\fR be used for the zone \fIkeyrec\fR in that zone's \fIkeyrec\fR file. .PP It is probably easiest to store \fIrollrec\fR files, \fIkeyrec\fR files, zone files, and key files in a single directory. .SH "INITIALIZATION AND USAGE" .IX Header "INITIALIZATION AND USAGE" The following steps must be taken to initialize and use \fBrollerd\fR. This assumes that zone files have been created, and that \s-1BIND\s0 and DNSSEC-Tools have been installed. .IP "0. sign zones" 4 .IX Item "0. sign zones" The zones to be managed by \fBrollerd\fR must be signed. Use \fBzonesigner\fR to create the signed zone files and the \fIkeyrec\fR files needed by \fBrollerd\fR. The \fIrollrec\fR file created in the next step \fBmust\fR use the \fIkeyrec\fR file names and the signed zone file names created here. .Sp This step is optional. If it is bypassed, then (in step 4 and later) \&\fBrollerd\fR will perform the initial key creation and zone signing of your zones using the defaults found in the DNSSEC-Tools configuration file. \&\fBrollerd\fR determines if it must perform these initial operations by whether it can find the \fIkeyrec\fR file for a zone (as specified in the \fIrollrec\fR file. If it can't, it performs the initial operations; if it can, it assumes the zone's initial operations have been performed. .IP "1. create \fIrollrec\fR file" 4 .IX Item "1. create rollrec file" Before \fBrollerd\fR may be used, a \fIrollrec\fR file must first be created. While this file may be built by hand, the \fBrollinit\fR command was written specifically to build the file. .IP "2. select operational parameters" 4 .IX Item "2. select operational parameters" A number of \fBrollerd\fR's operational parameters are taken from the DNSSEC-Tools configuration file. However, these may be overridden by command-line options. See the \s-1OPTIONS\s0 section below for more details. If non-standard parameters are desired to always be used, the appropriate fields in the DNSSEC-Tools configuration file may be modified to use these values. .IP "3. install the rollover configuration" 4 .IX Item "3. install the rollover configuration" The complete rollover configuration \*(-- \fBrollerd\fR, \fIrollrec\fR file, DNSSEC-Tools configuration file values, zone files \*(-- should be installed. The appropriate places for these locations are both installation-dependent and operating system-dependent. .IP "4. test the rollover configuration" 4 .IX Item "4. test the rollover configuration" The complete rollover configuration should be tested. .Sp Edit the zone files so that their zones have short \s-1TTL\s0 values. A minute \s-1TTL\s0 should be sufficient. Test rollovers of this speed should \fBonly\fR be done in a test environment without the real signed zone. .Sp Run the following command: .Sp .Vb 1 \& rollerd \-rrfile test.rollrec \-logfile \- \-loglevel info \-sleep 60 .Ve .Sp This command assumes the test \fIrollrec\fR file is \fBtest.rollrec\fR. It writes a fair amount of log messages to the terminal, and checks its queue every 60 seconds. Follow the messages to ensure that the appropriate actions, as required by the Pre-Publish Method, are taking place. .IP "5. set \fBrollerd\fR to start at boot" 4 .IX Item "5. set rollerd to start at boot" Once the configuration is found to work, \fBrollerd\fR should be set to start at system boot. The actual operations required for this step are operating system-dependent. .IP "6. reboot and verify" 4 .IX Item "6. reboot and verify" The system should be rebooted and the \fBrollerd\fR logfile checked to ensure that \fBrollerd\fR is operating properly. .SH "OPTIONS" .IX Header "OPTIONS" There are a number of operational parameters that define how \fBrollerd\fR works. These parameters define things such as the \fIrollrec\fR file, the logging level, and the log file. These parameters can be set in the DNSSEC-Tools configuration file or given as options on the \fBrollerd\fR command line. The command line options override values in the configuration file. .PP The following options are recognized: .IP "\fB\-alwayssign\fR" 4 .IX Item "-alwayssign" Tells \fBrollerd\fR to sign the zones that aren't in the middle of being rolled. This allows \fBrollerd\fR to refresh signed zone signatures and allows complete management of zone signing to be taken over by \fBrollerd\fR. .Sp The downside to using this option is that all the non-rolling zones will be signed after every sleep, which may be expensive computationally. .Sp Note: The zone files are not updated or installed at this time. Manual copying and installation are still needed. .IP "\fB\-autosign\fR | \fB\-noautosign\fR" 4 .IX Item "-autosign | -noautosign" Automatic zone-signing flag. If this is set, then a zone's zonefile will be re-signed (and only re-signed) if it is found to be newer than the corresponding signed zonefile. .IP "\fB\-directory dir\fR" 4 .IX Item "-directory dir" Sets the \fBrollerd\fR execution directory. This must be a valid directory. .IP "\fB\-display\fR" 4 .IX Item "-display" Starts the \fBblinkenlights\fR graphical display program to show the status of zones managed by \fBrollerd\fR. .IP "\fB\-dtconfig config_file\fR" 4 .IX Item "-dtconfig config_file" Name of an alternate DNSSEC-Tools configuration file to be processed. If specified, this configuration file is used \fIin place\fR of the normal DNSSEC-Tools configuration file \fBnot\fR in addition to it. Also, it will be handled prior to \fIkeyrec\fR files, \fIrollrec\fR files, and command-line options. .IP "\fB\-foreground\fR" 4 .IX Item "-foreground" Run in the foreground and do not fork into a daemon. .IP "\fB\-logfile log_file\fR" 4 .IX Item "-logfile log_file" Sets the \fBrollerd\fR log file to \fIlog_file\fR. This must be a valid logging file, meaning that if \fIlog_file\fR already exists, it must be a regular file. The only exceptions to this are if \&\fIlogfile\fR is \fB/dev/stdout\fR, \fB/dev/tty\fR, \fB\-\fR. Of these three, using a \&\fIlog_file\fR of \fB\-\fR is preferable since Perl will properly convert the \fB\-\fR to the process' standard output. .IP "\fB\-loglevel level\fR" 4 .IX Item "-loglevel level" Sets \fBrollerd\fR's logging level to \fIlevel\fR. \fB\f(BIrollmgr.pm\fB\|(3)\fR contains a list of the valid logging levels. .IP "\fB\-noreload\fR" 4 .IX Item "-noreload" Prevents \fBrollerd\fR from telling the \s-1DNS\s0 daemon to reload zones. .IP "\fB\-parameters\fR" 4 .IX Item "-parameters" Prints a set of \fBrollerd\fR parameters and then exits. This shows the parameters with which \fBrollerd\fR will execute, but very little parameter validation is performed. .IP "\fB\-pidfile pid_file\fR" 4 .IX Item "-pidfile pid_file" Stores the running process \s-1PID\s0 into \fIpid_file\fR. This defaults to \&\fB/var/run/rollerd.pid\fR on most systems. .IP "\fB\-rrfile rollrec_file\fR" 4 .IX Item "-rrfile rollrec_file" Name of the \fIrollrec\fR file to be processed. This is the only required \&\*(L"option\*(R". .IP "\fB\-realm realm_name\fR" 4 .IX Item "-realm realm_name" Name of the realm in which \fBrollerd\fR is running. This is for use with the DNSSEC-Tools realms facility as a means of easily identifying different instantiations of \fBrollerd\fR. It is informational only (e.g., \fBps\fR output and log files) and is not used for anything else. .IP "\fB\-singlerun\fR" 4 .IX Item "-singlerun" Processes all needed steps once and exits. This is not the ideal way to run \&\fBrollerd\fR, but it is potentially useful for environments where keying material is only available when specific hardware tokens have been made available. .Sp The timing between the steps will be potentially longer since the time between \fBrollerd\fR runs is dependent on when \fBrollerd\fR is executed. \&\*(L"cmd\*(R" lines must be added to the \fIrollrec\fR file to do particular actions. .Sp The following lines should serve as examples: .Sp .Vb 4 \& cmd "rollzsk example.com" \& cmd "rollksk example.com" \& cmd "dspub example.com" # (for when the parent publishes \& # the new ksk) .Ve .Sp The \fI\-singlerun\fR option implicitly implies \fI\-foreground\fR as well. .IP "\fB\-sleep sleeptime\fR" 4 .IX Item "-sleep sleeptime" Sets \fBrollerd\fR's sleep time to \fIsleeptime\fR. The sleep time is the amount of time (in seconds) \fBrollerd\fR waits between processing its \fIrollrec\fR\-based queue. .IP "\fB\-username username\fR" 4 .IX Item "-username username" \&\fBusername\fR is the user for which the \fBrollerd\fR daemon will be executed. The \fBrollerd\fR process' effective uid will be set to the uid corresponding to \fBusername\fR. .Sp If \fBusername\fR is a username, it must correspond to a valid uid; if it is a uid, it must correspond to a valid username. .Sp If \fBrollerd\fR does not have the appropriate O/S magic (e.g., for Unix, installed as \fIsetuid\fR program and owned by root) then it will only be able to switch to those users to which the executing user has privilege to switch. This restriction is dependent on the operating system and the manner by which \&\fBrollerd\fR is installed. .Sp When using this option, the target user must have access to the various directories, logs, and data files that \fBrollerd\fR requires to execute. Without this access, proper execution cannot occur. .IP "\fB\-zsargs arglist\fR" 4 .IX Item "-zsargs arglist" Additional \fBzonesigner\fR arguments that will be passed to all \fBzonesigner\fR executions. These arguments will override the corresponding arguments in the DNSSEC-Tools configuration file, and the zones' \fIkeyrec\fR files. If a zone's \&\fBrollrec\fR entry contains a \fIzsargs\fR field, then it will be used instead of those specified by this argument. .Sp Given the \fBrollerd\fR argument processing, the new arguments for \fBzonesigner\fR cannot be specified as expected. Instead, the arguments should be given in the following manner. The leading dash should be replaced with an equals sign. If the option takes an argument, the space that would separate the option from the option's argument should also be replaced by an equals sign. If multiple arguments will be passed via \fB\-zsargs\fR, quotes must be used to group them into a single argument. .Sp \&\fBrollerd\fR translates these arguments to the appropriate format for \&\fBzonesigner\fR. These examples should clarify the modifications: .Sp .Vb 4 \& normal zonesigner option rollerd \-zsargs option \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& \-nokrfile \-zsargs =nokrfile \& \-zskcount 5 \-kskcount 3 \-zsargs "=zskcount=5 =kskcount=3" .Ve .IP "\fB\-Version\fR" 4 .IX Item "-Version" Displays the version information for \fBrollerd\fR and the DNSSEC-Tools package. .IP "\fB\-help\fR" 4 .IX Item "-help" Display a usage message. .IP "\fB\-verbose\fR" 4 .IX Item "-verbose" Verbose output will be given. .SH "ASSUMPTIONS" .IX Header "ASSUMPTIONS" \&\fBrollerd\fR uses the \fBrndc\fR command to communicate with the \s-1BIND\s0 \&\fBnamed\fR daemon. Therefore, it assumes that appropriate measures have been taken so that this communication is possible. .SH "KNOWN PROBLEMS" .IX Header "KNOWN PROBLEMS" The following problems (or potential problems) are known: .IP "\-" 4 Any process that can write to the rollover socket can send commands to \&\fBrollerd\fR. This is probably not a Good Thing. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2005\-2012 \s-1SPARTA\s0, Inc. All rights reserved. See the \s-1COPYING\s0 file included with the DNSSEC-Tools package for details. .SH "AUTHOR" .IX Header "AUTHOR" Wayne Morrison, tewok@tislabs.com .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fB\f(BIblinkenlights\fB\|(8)\fR, \&\fB\f(BIdtrealms\fB\|(8)\fR, \&\fB\f(BInamed\fB\|(8)\fR, \&\fB\f(BIrndc\fB\|(8)\fR, \&\fB\f(BIrp\-wrapper\fB\|(8)\fR, \&\fB\f(BIrollchk\fB\|(8)\fR, \&\fB\f(BIrollctl\fB\|(8)\fR, \&\fB\f(BIrollinit\fB\|(8)\fR, \&\fB\f(BIzonesigner\fB\|(8)\fR .PP \&\fB\f(BINet::DNS::SEC::Tools::conf.pm\fB\|(3)\fR, \&\fB\f(BINet::DNS::SEC::Tools::defaults.pm\fB\|(3)\fR, \&\fB\f(BINet::DNS::SEC::Tools::keyrec.pm\fB\|(3)\fR, \&\fB\f(BINet::DNS::SEC::Tools::rolllog.pm\fB\|(3)\fR, \&\fB\f(BINet::DNS::SEC::Tools::rollmgr.pm\fB\|(3)\fR, \&\fB\f(BINet::DNS::SEC::Tools::rollrec.pm\fB\|(3)\fR .PP \&\fB\f(BIrollrec\fB\|(5)\fR