Provided by: dnssec-tools_2.0-1_all bug

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 5 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-2013 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)