NAME¶
rollctl - Send commands to the DNSSEC-Tools rollover daemon
SYNOPSIS¶
rollctl [options]
DESCRIPTION¶
The
rollctl command sends commands to the DNSSEC-Tools rollover daemon,
rollerd. Only one option may be specified on a command line.
In most cases,
rollerd will send a response to
rollctl.
rollctl will print a success or failure message, as appropriate.
If
rollctl is run as a PAR-packed command, it will use its own local copy
of the
dnssec-tools.conf file. This file will be found in the package
directory.
OPTIONS¶
The following options are handled by
rollctl.
- -display
- Starts the rollover status GUI.
- -dspub zone
- Indicates that zone's parent has published a new DS
record for zone.
Multiple zones can be specified on the command line. For instance, this
command will send the dspub command to rollerd for three
zones.
$ rollctl -dspub example1.com example2.com example3.com
- -dspuball
- Indicates that DS records have been published for all zones
in phase 6 of KSK rollover.
- -group
- Indicates that the specified command should apply to a zone
group instead of a zone. Consequently, the specified zone must actually be
a zone group. This option must be used in conjunction with another
command.
This option only applies to the following commands: -dspub,
-rollksk, -rollzone, -rollzsk, and -skipzone.
This command will have no effect if it is given to other other
commands.
- -halt [now]
- Cleanly halts rollerd execution. If the optional
now parameter is given, then rollerd will be halted
immediately, rather than allowing it to complete its currently queued
operations.
- -logfile logfile
- Sets the rollerd log file to logfile. This
must be a valid logging file, meaning that if logfile already
exists, it must be a regular file. The only exceptions to this are if
logfile is /dev/stdout or /dev/tty.
- -loglevel loglevel
- Sets the rollerd logging level to loglevel.
This must be one of the valid logging levels defined in
rollmgr.pm (3).
If a logging level is not specified, then the list of valid levels will be
printed and rollctl will exit. The list is given in both text and
numeric forms.
- -logtz logtz
- Sets the rollerd logging timezone to
loglevel. This must be either gmt (for Greenwich Mean Time
or local (for the host's local time.)
- -mergerrfs rollrec0 ... rollrecN
- Tells rollerd to merge the specified rollrec
files with its active rollrec file. The names of the rollrec
files must not contain colons.
- -nodisplay
- Stops the rollover status GUI.
- -phasemsg length
- length is the default length of phase-related log
messages used by rollerd. The valid levels are "long" and
"short", with "long" being the default value.
The long message length means that a phase description will be included with
some log messages. For example, the long form of a message about ZSK
rollover phase 3 will look like this: "ZSK phase 3 (Waiting for old
zone data to expire from caches)".
The short message length means that a phase description will not be included
with some log messages. For example, the short form of a message about ZSK
rollover phase 3 will look like this: "ZSK phase 3".
- -rollall
- Resumes rollover for all zones in the current
rollrec file that have been suspended. ("skip" zones are
suspended.)
- -rollallksks
- Initiates KSK rollover for all the zones defined in the
current rollrec file that aren't currently in rollover.
- -rollallzsks
- Initiates ZSK rollover for all the zones defined in the
current rollrec file that aren't currently in rollover.
- -rollksk zone
- Initiates KSK rollover for the zone named by zone.
Multiple zones can be specified on the command line. For instance, this
command will send the rollksk command to rollerd for three
zones.
$ rollctl -rollksk example1.com example2.com example3.com
- -rollrec rollrec_file
- Sets the rollrec file to be processed by
rollerd to rollrec_file.
- -rollzone zone
- Resumes rollover for the suspended zone named by
zone.
Multiple zones can be specified on the command line. For instance, this
command will send the rollzone command to rollerd for three
zones.
$ rollctl -rollzone example1.com example2.com example3.com
- -rollzsk zone
- Initiates rollover for the zone named by zone.
Multiple zones can be specified on the command line. For instance, this
command will send the rollzsk command to rollerd for three
zones.
$ rollctl -rollzsk example1.com example2.com example3.com
- -runqueue
- Wakes up rollerd and has it run its queue of
rollrec entries.
- -shutdown
- Synonym for -halt.
- -signzone zone
- Signs zone's zonefile without performing any
rollover actions. The zone is signed with the keys most recently used to
sign the zone. No new keys will be generated.
- -signzones [all | active]
- Signs the zonefiles of zones managed by rollerd,
without performing any rollover actions. If the all option is
given, then all of rollerd's zones will be signed. If the
active option is given, then only those zones which aren't in the
skip stage will be signed. The zones are signed with the keys most
recently used to sign each zone. No new keys will be generated.
- -skipall
- Suspends rollover for all zones in the current
rollrec file.
- -skipzone zone
- Suspends rollover for the zone named by zone.
Multiple zones can be specified on the command line. For instance, this
command will send the skipzone command to rollerd for three
zones.
$ rollctl -skipzone example1.com example2.com example3.com
- -sleeptime seconds
- Sets rollerd's sleep time to seconds seconds.
sleeptime must be an integer at least as large as the
$MIN_SLEEP value in rollerd.
- -splitrrf new-rrf zone0 ... zoneN
- Tells rollerd to move a set of rollrec
entries from the current rollrec file into a new file. The new file
is named in the new-rrf parameter. The rollrec entries whose
names correspond to the zone0 to zoneN list are moved to the
new file. The name of the new rollrec file and the zone names must
not contain colons.
- -status
- Has rollerd write several of its operational
parameters to its log file. The parameters are also reported to
rollctl, which prints them to the screen.
- -zonegroup [zone-group]
- Requests information about zone groups from rollerd.
If the optional zone-group argument is not given, then
rollerd will return a list of the defined zone groups and the
number of zones in each. If a zone-group is specified, then
rollerd will return a list of the zones in that group.
(While this is using the term "zone", it is actually referring to
the name of the rollrec entries. For a particular rollrec
entry, the rollrec name is usually the same as the zone name, but
this is not a requirement.)
- -zonelog
- Set the logging level for the specified zone. The new
logging level is only for the current execution of rollerd and is
not saved to the active rollrec file.
The arguments for this command must be in the format
"zone:loglevel". For example, this command will send the
zonelog command to rollerd for three zones.
$ rollctl -zonelog example1.com:info example2.com:6 example3.com:err
- -zonestatus
- Has rollerd write the status of zones in the current
rollrec file to the rollerd log file. The status is also
reported to rollctl, which prints it to the screen. rollctl
prints it in columnar fashion to enhance readability. The columns, in
order, are: rollrec name, zone name, roll/skip state, and rollover phase.
Example:
anothersub anothersub.example.com skip KSK 1
example.com example.com roll KSK 1
site1.in.subzone.example.com subzone.example.com roll KSK 3
site1.subzone.example.com subzone.example.com roll KSK 3
- -zsargs arglist zones
- Provides additional zonesigner arguments for a given
set of zones. These arguments will override the arguments in the
DNSSEC-Tools defaults file, the DNSSEC-Tools configuration file, and the
zones' keyrec files.
The zonesigner argument list is given in arglist. Given the
rollctl argument processing, the new arguments for
zonesigner 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. rollerd translates these arguments to
the appropriate format for zonesigner. These examples should
clarify the modifications:
normal zonesigner option -zsargs options
------------------------ ---------------
-nokrfile =nokrfile
-zskcount 5 =zskcount=5
The zones list is a space-separated list of zones. All the new
zonesigner arguments will be applied to all the listed
zones.
The "=clear" argument is special. rollerd translates it to
"-clear", which is not a normal zonesigner option.
Instead, rollerd recognizes "-clear" as an indicator that
it should remove the zsargs field from the rollrec records
for the specified zones.
The following are valid uses of -zsargs:
# rollctl -zsargs =ksklength=2048 example.com
# rollctl -zsargs =ksklen=2048 =zsklen=2048 example.com test.com
- -Version
- Displays the version information for rollctl and the
DNSSEC-Tools package.
- -quiet
- Prevents output from being given. Both error and non-error
output is stopped.
- -help
- Displays a usage message.
EXIT CODES¶
rollctl may give the following exit codes:
- 0 - Successful execution
- 1 - Error sending the command to rollerd.
- 2 - Missing argument.
- 3 - Too many commands specified.
- 200 - Rollerd is not running.
- 201 - Configuration file checks failed.
FUTURE¶
The following modifications may be made in the future:
- command execution order
- The commands will be executed in the order given on the
command line rather than in alphabetical order.
COPYRIGHT¶
Copyright 2006-2012 SPARTA, Inc. All rights reserved. See the COPYING file
included with the DNSSEC-Tools package for details.
AUTHOR¶
Wayne Morrison, tewok@tislabs.com
SEE ALSO¶
Net::DNS::SEC::Tools::rollmgr.pm(3),
Net::DNS::SEC::Tools::rollrec.pm (3)
rollerd(8)