rollmgr(3)

📦
version 2.2.3 · 3 versions
, in arch rolling

rollmgr(3) 🎀

okay bestie, welcome to the Net::DNS::SEC::Tools::rollmgr page from User Contributed Perl Documentation. It’s giving “talk to the DNSSEC-Tools rollerd rollover manager” energy, and there are two interface classes described here: general interfaces and communications interfaces 💅

✨ NAME ✨

Net::DNS::SEC::Tools::rollmgr — your little hotline to the DNSSEC-Tools rollover manager. No cap 🫶

🎀 SYNOPSIS 🎀

  use Net::DNS::SEC::Tools::rollmgr;

  $dir = rollmgr_dir();

  $idfile = rollmgr_idfile();

  $id = rollmgr_getid();

  rollmgr_dropid();

  rollmgr_rmid();

  rollmgr_cmdint();

  $runflag = rollmgr_running();

  rollmgr_halt();

  rollmgr_phasemsg('long');

  rollmgr_channel(1);
  ($cmd,$data) = rollmgr_getcmd();
  $ret = rollmgr_verifycmd($cmd);

  rollmgr_sendcmd(CHANNEL_CLOSE,ROLLCMD_ROLLZSK,"example.com");

  rollmgr_sendcmd(CHANNEL_WAIT,ROLLCMD_ROLLZSK,"example.com");
  ($retcode, $respmsg) = rollmgr_getresp();

  $descr = rollmgr_get_phase('KSK', $phasecnt);

💖 DESCRIPTION 💖

okay so the Net::DNS::SEC::Tools::rollmgr module gives you standard, platform-independent methods for a program to communicate with DNSSEC-Tools’ rollerd rollover manager. There are two interface classes described here: general interfaces and communications interfaces 🌸

🫶 GENERAL INTERFACES 🫶

The interfaces to the Net::DNS::SEC::Tools::rollmgr module are given below, bestie. Let’s go 👑

rollmgr_dir() 🌟

This routine returns rollerd’s directory. Cute and simple.

rollmgr_idfile() 🎀

This routine returns rollerd’s id file.

rollmgr_getid() 🔥

This routine returns rollerd’s process id. If a non-zero value is passed as an argument, the id file will be left open and accessible through the PIDFILE file handle. Peep the WARNINGS section below 👀

Return Values:

  • On success, the first portion of the file contents (up to 80 characters) is returned.
  • -1 — the id file does not exist.

rollmgr_dropid() 💖

This interface makes sure another instance of rollerd is not running, and then creates an id file for future reference.

Return Values:

  • 1 — the id file was successfully created for this process
  • 0 — another process is already acting as rollerd
  • -1 — unable to create the id file

rollmgr_rmid() 🦋

This interface deletes rollerd’s id file.

Return Values:

  • 1 — the id file was successfully deleted
  • 0 — no id file exists
  • -1 — the calling process is not rollerd
  • -2 — unable to delete the id file

rollmgr_cmdint() ⭐

This routine informs rollerd that a command has been sent via rollmgr_sendcmd().

Return Values:

  • -1 — an invalid process id was found for rollerd
  • Anything else indicates the number of processes that were signaled.
(This should only ever be 1.) 🫶

rollmgr_running() 🌈

This routine determines if rollerd is running and returns a value indicating the status.

Return Values:

  • 1 — rollerd is running.
  • 0 — The process listed in the rollerd process id file is not running.
  • -1 — Unable to get the rollerd process id.

rollmgr_halt() 💀

This routine informs rollerd to shut down.

In the current implementation, the return code from the kill() command is returned.

  • -1 — an invalid process id was found for rollerd
  • Anything else indicates the number of processes that were signaled.
(This should only ever be 1.) ✨

rollmgr_loadzone(ctlprog,opts,zone) 🔥

This routine informs a name server to reload a zone’s zone file. The $ctlprog argument is the command that will be run to control the name server. If this is an empty string, then the default value for DNSSEC-Tools will be used. The $opts argument is a set of options to be passed to ctlprog. The $zone argument is the name of the zone to be reloaded.

The command line to be run is built in this format:

<$zone> <$opts> reload <$zone>

This format assumes that the rndc command will be used for signalling the name server.

The return value will be the return code from running $ctlprog.

rollmgr_phasemsg() 🧚

This routine sets the phase-message 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".

Return Values:

  • 1 — the phase-message length was set
  • 0 — an invalid phase-message length was specified

🌈 ROLLERD COMMUNICATIONS INTERFACES 🌈

okay so this is the whole group chat with rollerd, bestie — every function here is about setting up the channel, queueing commands, sending commands, and getting the tea back. no cap, all the deets are staying. 💅

💖 rollmgr_channel(serverflag)

This interface sets up a persistent channel for communications with rollerd. If serverflag is true, then the server's side of the channel is created. If serverflag is false, then the client's side of the channel is created.

Currently, the connection may only be made to the localhost. This may be changed to allow remote connections, if this is found to be needed.

Return Values:

  • 1 — communications channel successfully established. slay.
  • 0 — unable to connect to the server.
  • -1 — unable to create a Unix socket.
  • -2 — unable to bind to the Unix socket. (server only)
  • -3 — unable to change the permissions on the Unix socket. (server only)
  • -4 — unable to listen on the Unix socket. (server only)
  • -5 — the socket name was longer than allowed for a Unix socket.

🎀 rollmgr_queuecmd(cmdname, value)

This interface internally remembers a command and its optional value for later processing. See rollmgr_getcmd() next for further details. it’s giving “hold that thought” energy. 🫶

🦋 rollmgr_getcmd()

rollmgr_getcmd() processes commands that need to be dealt with. If there are any internally stored commands queued via the rollmgr_queuecmd() function, they are dealt with first. After that it retrieves a command sent over rollerd's communications channel by a client program. The command and the command's data are sent in each message.

The command and the command's data are returned to the caller. literally the whole package. ✨

👑 rollmgr_sendcmd(closeflag,cmd,data)

rollmgr_sendcmd() sends a command to rollerd. The command must be one of the commands from the table below. This interface creates a communications channel to rollerd and sends the message. The channel is not closed, in case the caller wants to receive a response from rollerd.

The available commands and their required data are:

  • ROLLCMD_DISPLAY — data: 1/0; purpose: start/stop rollerd's graphical display.
  • ROLLCMD_DSPUB — data: zone-name; purpose: a DS record has been published.
  • ROLLCMD_DSPUBALL — data: none; purpose: DS records published for all zones in KSK rollover phase 5.
  • ROLLCMD_GETSTATUS — data: none; purpose: currently unused.
  • ROLLCMD_LOGFILE — data: log filename; purpose: change the log file.
  • ROLLCMD_LOGLEVEL — data: log level; purpose: set a new logging level.
  • ROLLCMD_LOGMSG — data: log message; purpose: add a message to the log.
  • ROLLCMD_LOGTZ — data: timezone; purpose: set timezone for log messages.
  • ROLLCMD_MERGERRFS — data: rollrec files; purpose: merge rollrec files with the current rollrec file.
  • ROLLCMD_PHASEMSG — data: long/short; purpose: set long or short phase messages.
  • ROLLCMD_QUEUELIST — data: none; purpose: returns the names and next event time of zones in the "soon queue" (experimental).
  • ROLLCMD_QUEUESTATUS — data: none; purpose: returns information about the state of soon-queue processing (experimental).
  • ROLLCMD_ROLLALL — data: none; purpose: resume rollover for all suspended zones.
  • ROLLCMD_ROLLALLZSKS — data: none; purpose: force all zones to start ZSK rollover.
  • ROLLCMD_ROLLKSK — data: zone-name; purpose: force a zone to start KSK rollover.
  • ROLLCMD_ROLLREC — data: rollrec-name; purpose: change rollerd's rollrec file.
  • ROLLCMD_ROLLZONE — data: zone name; purpose: restart rollover for a suspended zone.
  • ROLLCMD_ROLLZSK — data: zone-name; purpose: force a zone to start ZSK rollover.
  • ROLLCMD_RUNQUEUE — data: none; purpose: rollerd runs through its queue.
  • ROLLCMD_SHUTDOWN — data: none; purpose: stop rollerd.
  • ROLLCMD_SIGNZONE — data: zone; purpose: sign a zone (no rollover).
  • ROLLCMD_SIGNZONEs — data: all or active; purpose: sign all or active zones.
  • ROLLCMD_SKIPALL — data: none; purpose: suspend all rollovers.
  • ROLLCMD_SKIPZONE — data: zone name; purpose: suspend rollover for a rolling zone.
  • ROLLCMD_SLEEPTIME — data: seconds-count; purpose: set rollerd's sleep time.
  • ROLLCMD_SPLITRRF — data: rollrec-name, zone names; purpose: move a set of zones from the current rollrec file into a new rollrec file.
  • ROLLCMD_STATUS — data: none; purpose: get status of rollerd.
  • ROLLCMD_ZONEGROUP — data: zonegroup name; purpose: get info on all zonegroups or a particular zonegroup.
  • ROLLCMD_ZONELOG — data: zone name, logging level; purpose: set the logging level for a particular zone.
  • ROLLCMD_ZONESTATUS — data: none; purpose: get status of the zones.
  • ROLLCMD_ZSARGS — data: zonesigner args, zone list; purpose: add a (probably temporary) set of options to the signing of a set of zones.

The data aren't checked for validity by rollmgr_sendcmd(); validity checking is a responsibility of rollerd.

If the caller does not need a response from rollerd, then closeflag should be set to CHANNEL_CLOSE; if a response is required then closeflag should be CHANNEL_WAIT. These values are boolean values, and the constants aren't required.

On success, 1 is returned. If an invalid command is given, 0 is returned.

🌸 rollmgr_getresp()

After executing a client command sent via rollmgr_sendcmd(), rollerd will send a response to the client. rollmgr_getresp() allows the client to retrieve the response.

A return code and a response string are returned, in that order. Both are specific to the command sent. iykyk. 💜

🧚 rollmgr_verifycmd(cmd)

rollmgr_verifycmd() verifies that cmd is a valid command for rollerd. 1 is returned for a valid command; 0 is returned for an invalid command.

1 is returned for a valid command; 0 is returned for an invalid command. yes, it really says it twice, and we are keeping it twice, bestie. 💅

⭐ rollmgr_get_phase(phasetype, phasenum)

rollmgr_get_phase() returns a description of a particular phase for a particular type of rollover. phasetype specifies the type of rollover, and may be "KSK" or "ZSK". phasenum specifies the phase number whose description is desired. This must be an integer between 0 and 7 (KSK) or 0 and 4 (ZSK). If an invalid phase type or phase number is specified, an empty string is returned.

⚠️ WARNINGS ⚠️

  1. rollmgr_getid() attempts to exclusively lock the id file. Set a timer if this matters to you.
  2. rollmgr_getid() has a nice little race condition. We should lock the file prior to opening it, but we can't do so without it being open.
okay these are real warnings, not just vibes — the race condition is literally in the original and we’re not pretending otherwise. 💀

Copyright 2005-2014 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 🌈

  • rollctl(1)
  • Net::DNS::SEC::Tools::keyrec.pm(3)
  • Net::DNS::SEC::Tools::rolllog.pm(3)
  • Net::DNS::SEC::Tools::rollrec.pm(3)
  • rndc(8)
  • rollerd(8)

This page is serving perl v5.44.0, dated 2026-10-17, and it's the rollmgr(3) manual — k bye bestie, go slay some rollover commands! 🎀✨💖

📦 where this page comes from