ROLLCTL(1)

📦

version 2.2.3 · 2 versions

2.2.3 · fedora 43 (latest)
2.2.3 · fedora 44

rollctl 💅✨

okay bestie, gather round, because this one is a DNSSEC-Tools girly through and through 🎀 she lives in the User Contributed Perl Documentation section and her whole personality is sending commands to the rollover daemon. iconic behavior honestly.

NAME 🦋

rollctl — sends commands to the DNSSEC-Tools rollover daemon. no cap, that's literally her whole job and she does it flawlessly.

SYNOPSIS ✨

rollctl [options]

DESCRIPTION 💖

so the tea is: rollctl sends commands to the DNSSEC-Tools rollover daemon, rollerd. and here's the thing — only one option may be specified on a command line. one. singular. she's monogamous with her options, okay?? 🙈

in most cases, rollerd will send a response back to rollctl, and rollctl will print a success or failure message, as appropriate. so you always know what's up. communication queen 👑

if rollctl is run as a PAR-packed command, it will use its own local copy of the dnssec-tools.conf file. that file will be found in the package directory. self-sufficient baddie 🫶

OPTIONS 🌈

the following options are handled by rollctl. buckle up bestie, there's a lot of them and they're all important.

-display — starts the rollover status GUI. visual girly pop 💅
-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. go big or go home 🎀
-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. it's a team player, she never shows up alone.

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.

lowkey note that the original says "other other commands" — that's not me being cute, that's just how it was written, and I'm not about to edit the queen's words 💀

-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. so like... graceful exit vs. ✨dramatic exit✨
-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. rules are rules babe 📝
-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. so if you're indecisive she'll just show you the menu 🍓

-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.)

yes, it says loglevel in the timezone description, and yes, the parentheses are a little wonky. I'm keeping it exactly as-is because the facts do not change, only the vibe 💅

-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. colon-free zone only 🚫
-nodisplay — stops the rollover status GUI. closing the curtains, show's over 🎬
-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.) we're un-skipping everyone, it's a comeback era 🔥
-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. rise and grind ☀️
-shutdown — synonym for -halt. same energy, different name.
-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. just a lil refresh, no new lore 🧚
-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. everybody take five 💤
-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. she needs her beauty sleep and there's a hard minimum, okay?? 😴
-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. again with the colon ban 🚫
-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. double the receipts 📋
-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. she said "I'm overriding all of that, actually" 💅

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. main character gets a title card 👑
-quiet — prevents output from being given. both error and non-error output is stopped. silent. mysterious. no notes 🤫
-help — displays a usage message.

EXIT CODES 🍓

rollctl may give the following exit codes. she communicates through numbers, iykyk:

0 — successful execution ✨
1 — error sending the command to rollerd.
2 — missing argument.
3 — too many commands specified. (remember, ONE option only bestie 😭)
200 — rollerd is not running.
201 — configuration file checks failed.

FUTURE 🔮

the following modifications may be made in the future. manifesting ✨

command execution order — the commands will be executed in the order given on the command line rather than in alphabetical order. so she'd finally listen to you in the order you actually said things. growth 🌱

okay and that's just part one of this whole saga, there's more coming, don't go anywhere bestie — 💖

💖 COPYRIGHT 💖

👑 AUTHOR 👑

This masterpiece was brought to you by Wayne Morrison, who you can reach at tewok@tislabs.com. main character energy tbh 🫶💅

🦋 SEE ALSO 🦋

Net::DNS::SEC::Tools::rollmgr.pm(3) — the rollmgr module, iykyk 🌸
Net::DNS::SEC::Tools::rollrec.pm(3) — the rollrec module, also iconic 💜
rollerd(8) — the daemon doing the actual rolling, no cap 🔥

and that's a wrap on ROLLCTL(1) 🎀 — this page is from perl v5.42.0, dated 2025-07-23, and yes that's the whole entire manpage, you ate it all, so proud of you bestie 💖✨🦋🌸💅🫶

📦 where this page comes from

fedora 43: dnssec-tools 2.2.3-30.fc43 · LicenseRef-Callaway-BSD
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms