.\" 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 "rollmgr 3pm" .TH rollmgr 3pm "2012-06-28" "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" Net::DNS::SEC::Tools::rollmgr \- Communicate with the DNSSEC\-Tools rollover manager. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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(\*(Aqlong\*(Aq); \& \& 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(\*(AqKSK\*(Aq, $phasecnt); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBNet::DNS::SEC::Tools::rollmgr\fR module provides standard, platform-independent methods for a program to communicate with DNSSEC\-Tools' \&\fBrollerd\fR rollover manager. There are two interface classes described here: general interfaces and communications interfaces. .SH "GENERAL INTERFACES" .IX Header "GENERAL INTERFACES" The interfaces to the \fBNet::DNS::SEC::Tools::rollmgr\fR module are given below. .IP "\fI\fIrollmgr_dir()\fI\fR" 4 .IX Item "rollmgr_dir()" This routine returns \fBrollerd\fR's directory. .IP "\fI\fIrollmgr_idfile()\fI\fR" 4 .IX Item "rollmgr_idfile()" This routine returns \fBrollerd\fR's id file. .IP "\fI\fIrollmgr_getid()\fI\fR" 4 .IX Item "rollmgr_getid()" This routine returns \fBrollerd\fR's process id. If a non-zero value is passed as an argument, the id file will be left open and accessible through the \s-1PIDFILE\s0 file handle. See the \s-1WARNINGS\s0 section below. .Sp Return Values: .Sp .Vb 3 \& On success, the first portion of the file contents \& (up to 80 characters) is returned. \& \-1 is returned if the id file does not exist. .Ve .IP "\fI\fIrollmgr_dropid()\fI\fR" 4 .IX Item "rollmgr_dropid()" This interface ensures that another instance of \fBrollerd\fR is not running and then creates a id file for future reference. .Sp Return Values: .Sp .Vb 3 \& 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 .Ve .IP "\fI\fIrollmgr_rmid()\fI\fR" 4 .IX Item "rollmgr_rmid()" This interface deletes \fBrollerd\fR's id file. .Sp Return Values: .Sp .Vb 4 \& 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 .Ve .IP "\fI\fIrollmgr_cmdint()\fI\fR" 4 .IX Item "rollmgr_cmdint()" This routine informs \fBrollerd\fR that a command has been sent via \&\fI\fIrollmgr_sendcmd()\fI\fR. .Sp Return Values: .Sp .Vb 4 \& \-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.) .Ve .IP "\fI\fIrollmgr_running()\fI\fR" 4 .IX Item "rollmgr_running()" This routine determines if rollerd is running and returns a value indicating the status. .Sp Return Values: .Sp .Vb 4 \& 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. .Ve .IP "\fI\fIrollmgr_halt()\fI\fR" 4 .IX Item "rollmgr_halt()" This routine informs \fBrollerd\fR to shut down. .Sp In the current implementation, the return code from the \fB\f(BIkill()\fB\fR command is returned. .Sp .Vb 4 \& \-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.) .Ve .IP "\fI\fIrollmgr_phasemsg()\fI\fR" 4 .IX Item "rollmgr_phasemsg()" This routine sets the phase-message length. of phase-related log messages used by \fBrollerd\fR. The valid levels are \*(L"long\*(R" and \*(L"short\*(R", with \*(L"long\*(R" being the default value. .Sp 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 \s-1ZSK\s0 rollover phase 3 will look like this: \*(L"\s-1ZSK\s0 phase 3 (Waiting for old zone data to expire from caches)\*(R". .Sp 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 \s-1ZSK\s0 rollover phase 3 will look like this: \*(L"\s-1ZSK\s0 phase 3\*(R". .Sp Return Values: .Sp .Vb 2 \& 1 \- the phase\-message length was set \& 0 \- an invalid phase\-message length was specified .Ve .SH "ROLLERD COMMUNICATIONS INTERFACES" .IX Header "ROLLERD COMMUNICATIONS INTERFACES" .IP "\fIrollmgr_channel(serverflag)\fR" 4 .IX Item "rollmgr_channel(serverflag)" This interface sets up a persistent channel for communications with \fBrollerd\fR. If \fIserverflag\fR is true, then the server's side of the channel is created. If \fIserverflag\fR is false, then the client's side of the channel is created. .Sp 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. .Sp Return Values: .Sp .Vb 7 \& 1 \- Communications channel successfully established. \& 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. .Ve .IP "\fIrollmgr_queuecmd(cmdname, value)\fR" 4 .IX Item "rollmgr_queuecmd(cmdname, value)" This interface internally remembers a command and it's optional value for later processing. See the \fI\fIrollmgr_getcmd()\fI\fR next for further details. .IP "\fI\fIrollmgr_getcmd()\fI\fR" 4 .IX Item "rollmgr_getcmd()" \&\fI\fIrollmgr_getcmd()\fI\fR processes commands that need to be dealt with. If there are any internally stored commands queued via the \&\fI\fIrollmgr_queuecmd()\fI\fR function, they are dealt with first. After that it retrieves a command sent over \fBrollerd\fR's communications channel by a client program. The command and the command's data are sent in each message. .Sp The command and the command's data are returned to the caller. .IP "\fIrollmgr_sendcmd(closeflag,cmd,data)\fR" 4 .IX Item "rollmgr_sendcmd(closeflag,cmd,data)" \&\fI\fIrollmgr_sendcmd()\fI\fR sends a command to \fBrollerd\fR. The command must be one of the commands from the table below. This interface creates a communications channel to \fBrollerd\fR and sends the message. The channel is not closed, in case the caller wants to receive a response from \fBrollerd\fR. .Sp The available commands and their required data are: .Sp .Vb 10 \& command data purpose \& \-\-\-\-\-\-\- \-\-\-\- \-\-\-\-\-\-\- \& ROLLCMD_DISPLAY 1/0 start/stop rollerd\*(Aqs \& graphical display \& ROLLCMD_DSPUB zone\-name a DS record has been \& published \& ROLLCMD_DSPUBALL none DS records published for all \& zones in KSK rollover phase 6 \& ROLLCMD_GETSTATUS none currently unused \& ROLLCMD_LOGFILE log filename change the log file \& ROLLCMD_LOGLEVEL log level set a new logging level \& ROLLCMD_LOGMSG log message add a message to the log \& ROLLCMD_LOGTZ timezone set timezone for log messages \& ROLLCMD_MERGERRFS rollrec files merge rollrec files with the \& current rollrec file \& ROLLCMD_PHASEMSG long/short set long or short phase \& messages \& ROLLCMD_QUEUELIST none returns the names and next \& event time of zones in the \& "soon queue \& (experimental) \& ROLLCMD_QUEUESTATUS none returns information about \& the state of soon\-queue \& processing \& (experimental) \& ROLLCMD_ROLLALL none resume rollover for all \& suspended zones \& ROLLCMD_ROLLALLZSKS none force all zones to start \& ZSK rollover \& ROLLCMD_ROLLKSK zone\-name force a zone to start \& KSK rollover \& ROLLCMD_ROLLREC rollrec\-name change rollerd\*(Aqs rollrec file \& ROLLCMD_ROLLZONE zone name restart rollover for a \& suspended zone \& ROLLCMD_ROLLZSK zone\-name force a zone to start \& ZSK rollover \& ROLLCMD_RUNQUEUE none rollerd runs through \& its queue \& ROLLCMD_SHUTDOWN none stop rollerd \& ROLLCMD_SIGNZONE zone sign a zone (no rollover) \& ROLLCMD_SIGNZONEs all or active sign all or active zones \& ROLLCMD_SKIPALL none suspend all rollovers \& ROLLCMD_SKIPZONE zone name suspend rollover for a \& rolling zone \& ROLLCMD_SLEEPTIME seconds\-count set rollerd\*(Aqs sleep time \& ROLLCMD_SPLITRRF rollrec\-name, move a set of zones from the \& zone names current rollrec file into a \& new rollrec file \& ROLLCMD_STATUS none get status of rollerd \& ROLLCMD_ZONEGROUP zonegroup name get info on all zonegroups \& or a particular zonegroup \& ROLLCMD_ZONELOG zone name set the logging level for \& logging level a particular zone \& ROLLCMD_ZONESTATUS none get status of the zones \& ROLLCMD_ZSARGS zonesigner args add a (probably temporary) \& zone list set of options to the signing \& of a set of zones .Ve .Sp The data aren't checked for validity by \fI\fIrollmgr_sendcmd()\fI\fR; validity checking is a responsibility of \fBrollerd\fR. .Sp If the caller does not need a response from \fBrollerd\fR, then \fIcloseflag\fR should be set to \fB\s-1CHANNEL_CLOSE\s0\fR; if a response is required then \&\fIcloseflag\fR should be \fB\s-1CHANNEL_WAIT\s0\fR. These values are boolean values, and the constants aren't required. .Sp On success, 1 is returned. If an invalid command is given, 0 is returned. .IP "\fI\fIrollmgr_getresp()\fI\fR" 4 .IX Item "rollmgr_getresp()" After executing a client command sent via \fI\fIrollmgr_sendcmd()\fI\fR, \fBrollerd\fR will send a response to the client. \fI\fIrollmgr_getresp()\fI\fR allows the client to retrieve the response. .Sp A return code and a response string are returned, in that order. Both are specific to the command sent. .IP "\fIrollmgr_verifycmd(cmd)\fR" 4 .IX Item "rollmgr_verifycmd(cmd)" \&\fI\fIrollmgr_verifycmd()\fI\fR verifies that \fIcmd\fR is a valid command for \fBrollerd\fR. 1 is returned for a valid command; 0 is returned for an invalid command. .Sp 1 is returned for a valid command; 0 is returned for an invalid command. .IP "\fIrollmgr_get_phase(phasetype, phasenum)\fR" 4 .IX Item "rollmgr_get_phase(phasetype, phasenum)" \&\fI\fIrollmgr_get_phase()\fI\fR returns a description of a particular phase for a particular type of rollover. \fIphasetype\fR specifies the type of rollover, and may be \*(L"\s-1KSK\s0\*(R" or \*(L"\s-1ZSK\s0\*(R". \fIphasenum\fR specifies the phase number whose description is desired. This must be an integer between 0 and 7 (\s-1KSK\s0) or 0 and 4 (\s-1ZSK\s0). If an invalid phase type or phase number is specified, an empty string is returned. .SH "WARNINGS" .IX Header "WARNINGS" 1. \fI\fIrollmgr_getid()\fI\fR attempts to exclusively lock the id file. Set a timer if this matters to you. .PP 2. \fI\fIrollmgr_getid()\fI\fR 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. .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(BIrollctl\fB\|(1)\fR .PP \&\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::rollrec.pm\fB\|(3)\fR .PP \&\fB\f(BIrollerd\fB\|(8)\fR