.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "REALMCTL 1"
.TH REALMCTL 1 2023-07-29 "perl v5.38.0" "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
realmctl \- Send commands to the DNSSEC\-Tools realms daemon
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  realmctl [options]
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBrealmctl\fR command sends commands to \fBdtrealms\fR, the DNSSEC-Tools realms
daemon.  In most cases, \fBdtrealms\fR will send a response to \fBrealmctl\fR.
\&\fBrealmctl\fR will print a success or failure message, as appropriate.  Only one
option may be specified on a command line.
.SH OPTIONS
.IX Header "OPTIONS"
The following options are handled by \fBrealmctl\fR.
.IP \fB\-allstart\fR 4
.IX Item "-allstart"
Starts all suspended realms.
.IP \fB\-allstop\fR 4
.IX Item "-allstop"
Stops all running realms.
.IP "\fB\-cmd \-\- realm cmd args\fR" 4
.IX Item "-cmd -- realm cmd args"
.PD 0
.IP "\fB\-command \-\- realm cmd args\fR" 4
.IX Item "-command -- realm cmd args"
.PD
Sends a command to the specified realm.  The command given as \fIcmd\fR will be
sent to the \fBrollerd\fR running in realm \fIrealm\fR.
.Sp
The double-dash given above is critical for proper argument parsing of the
command line.
.Sp
All command-line arguments, as \fIargs\fR above, following the realm name and
command name will be sent as the command.
.Sp
Whatever output the command gives will be returned to \fBrealmctl\fR, which will
then print that output.  The command's return code will be appended to the
command's output.  No attempt will be made to analyze the output for
success or failure.
.Sp
For example, this command will tell the realm \fBgiant-isp\fR to stop
rollover of zone \fIbob.example.com\fR:
.Sp
.Vb 1
\&   $ realmctl \-command \-\- giant\-isp rollctl \-skipzone bob.example.com
.Ve
.Sp
\&\fBWarning:\fR  This is an inherently dangerous command.  When choosing a user
under which the realm and rollover commands will be executed, be aware that
this problem exists.  \fBrealmctl\fR \fImay\fR be modified in the future to
restrict the commands that may be executed with this option.
.IP \fB\-display\fR 4
.IX Item "-display"
Starts the realms status GUI.
.IP "\fB\-halt\fR [now]" 4
.IX Item "-halt [now]"
Cleanly halts \fBdtrealms\fR execution.
.IP "\fB\-logfile logfile\fR" 4
.IX Item "-logfile logfile"
Sets the \fBdtrealms\fR log file to \fIlogfile\fR.  This must be a valid logging
file, meaning that if \fIlogfile\fR already exists, it must be a regular file.
The only exceptions to this are if \fIlogfile\fR is \fB/dev/stdout\fR or
\&\fB/dev/tty\fR.
.IP "\fB\-loglevel loglevel\fR" 4
.IX Item "-loglevel loglevel"
Sets the \fBdtrealms\fR logging level to \fIloglevel\fR.
This must be one of the valid logging levels defined in \fBrealmmgr.pm\|(3)\fR.
.Sp
If a logging level is not specified, then the list of valid levels will be
printed and \fBrealmctl\fR will exit.  The list is given in both text and numeric
forms.
.IP "\fB\-logtz logtz\fR" 4
.IX Item "-logtz logtz"
Sets the \fBdtrealms\fR logging timezone to \fIloglevel\fR.  This must be either
\&\fIgmt\fR (for Greenwich Mean Time or \fIlocal\fR (for the host's local time.)
.IP \fB\-nodisplay\fR 4
.IX Item "-nodisplay"
Stops the realms status GUI.
.IP \fB\-realmstatus\fR 4
.IX Item "-realmstatus"
Gets the current status of all the realms from \fBdtrealms\fR.  For each realm,
the name, execution status, and zone counts are printed.  The zone counts
are, in order, the number of zones in normal state, the number of zones in
ZSK rollover, the number of zones in KSK rollover, and the number of zones
waiting in KSK phase 6.  The zone counts are determined by sending the
realm's rollover manager an information request.  Therefore, if the zone is
inactive, the zone counts are not included.
.Sp
Example:
.Sp
.Vb 3
\&    dev     active     normal: 18   ZSK: 3   KSK: 1   KSK phase 6: 0
\&    test\-r  inactive
\&    money   active     normal: 10   ZSK: 0   KSK: 0   KSK phase 6: 1
.Ve
.IP \fB\-shutdown\fR 4
.IX Item "-shutdown"
Synonym for \fB\-halt\fR.
.IP "\fB\-startrealm realm\fR" 4
.IX Item "-startrealm realm"
Starts the suspended realm named by \fIrealm\fR.  Multiple realms can be
specified on the command line.  For instance, this command will send the
\&\fIstartrealm\fR command to \fBdtrealms\fR for three realms.
.Sp
.Vb 1
\&    $ realmctl \-startrealm testing production customers
.Ve
.IP \fB\-status\fR 4
.IX Item "-status"
Has \fBdtrealms\fR write several of its operational parameters to its log file.
The parameters are also reported to \fBrealmctl\fR, which prints them to the
screen.
.IP "\fB\-stoprealm realm\fR" 4
.IX Item "-stoprealm realm"
Stops the realm named by \fIrealm\fR.  Multiple realms can be specified on the
command line.  For instance, this command will send the \fIstoprealm\fR command
to \fBdtrealms\fR for two realms.
.Sp
.Vb 1
\&    $ realmctl \-stoprealm big\-isp\-3 misc\-customers
.Ve
.IP \fB\-Version\fR 4
.IX Item "-Version"
Displays the version information for \fBrealmctl\fR and the DNSSEC-Tools package.
.IP \fB\-quiet\fR 4
.IX Item "-quiet"
Prevents output from being given.  Both error and non-error output is stopped.
.IP \fB\-help\fR 4
.IX Item "-help"
Displays a usage message.
.SH "EXIT CODES"
.IX Header "EXIT CODES"
\&\fBrealmctl\fR may give the following exit codes:
.IP "0 \- Successful execution" 4
.IX Item "0 - Successful execution"
.PD 0
.IP "1 \- Error sending the command to \fBdtrealms\fR." 4
.IX Item "1 - Error sending the command to dtrealms."
.IP "2 \- Missing realm argument." 4
.IX Item "2 - Missing realm argument."
.IP "3 \- Too many command options specified." 4
.IX Item "3 - Too many command options specified."
.IP "4 \- Missing argument for \fB\-cmd\fR or \fB\-command\fR." 4
.IX Item "4 - Missing argument for -cmd or -command."
.IP "5 \- No option specified." 4
.IX Item "5 - No option specified."
.IP "200 \- dtrealms is not running." 4
.IX Item "200 - dtrealms is not running."
.IP "201 \- Configuration file checks failed." 4
.IX Item "201 - Configuration file checks failed."
.PD
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2012\-2014 SPARTA, Inc.  All rights reserved.
See the COPYING 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"
\&\fBNet::DNS::SEC::Tools::realmmgr.pm\|(3)\fR,
\&\fBNet::DNS::SEC::Tools::realm.pm\|(3)\fR
.PP
\&\fBdtrealms\|(8)\fR,
\&\fBrollctl\|(8)\fR
\&\fBrollerd\|(8)\fR