.\" -*- 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 "DTREALMS 1"
.TH DTREALMS 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
dtrealms \- Displays defaults defined for DNSSEC\-Tools
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  dtrealms [options] <realm\-file>
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBdtrealms\fR manages multiple distinct DNSSEC-Tools rollover environments
running simultaneously.  Each rollover environment, called a \fBrealm\fR, is
defined in a \fBrealms\fR file.  \fBdtrealms\fR uses this file to determine how the
rollover environment must be initialized such that it can run independently of
the other rollover environments on a particular system.  This is useful for
such things as managing very large collections of zones, segregating customer
zones, and software tests.
.PP
The \fBrealms\fR file may be created with \fBrealminit\fR.  Currently, the distinct
environment for each realm must be created manually.  It is hoped that a tool
will soon be available to assist with creating each realm's environment.
.PP
\&\fBdtrealms\fR isn't necessary for running multiple realms.  However, it does
make it easier to manage multiple realms running consecutively.
.SH "REALM SETUP"
.IX Header "REALM SETUP"
A realm is primarily defined by its entry in a \fBrealms\fR file.  Four fields
in particular describe where the realm's files are located and how it runs.
These are the realm's configuration directory, state directory, realm
directory, and \fBrollrec\fR file.  These directories are used to set the
\&\fBDT_STATEDIR\fR and \fBDT_SYSCONFDIR\fR environment variables, and the \fBrollrec\fR
file defines which zones are managed by the realm's rollover manager.
.PP
\&\fIhttps://www.dnssec\-tools.org/wiki/index.php/Rollover_Realms:_Multiple,_Simultaneous,_Independent_Rollover_Environments\fR has more information on creating
realms.
.IP \fBconfigdir\fR 4
.IX Item "configdir"
The \fBconfigdir\fR field of the \fBrealms\fR file contains the name of the realm's
configuration directory.  This file gives command paths and configuration
values for running the DNSSEC-Tools.  The DNSSEC-Tools modules expects this
directory hierarchy to contain a \fBdnssec-tools\fR subdirectory, and a
\&\fBdnssec\-tools.conf\fR file within that subdirectory.  The path fields in the
configuration file point to various things, such as commands and key archives.
It is recommended that these paths only point within the \fBconfigdir\fR
hierarchy, other than for system utilities.
.Sp
The \fBDT_SYSCONFDIR\fR environment variable is set to the \fBconfigdir\fR field.
This will tell the DNSSEC-Tools programs and modules where to find their
required data.
.IP \fBstatedir\fR 4
.IX Item "statedir"
The \fBstatedir\fR field of the \fBrealms\fR file contains the name of the realm's
state directory.  This directory contains such files as the \fBrollrec\fR lock
file and the \fBrollerd\fR communications socket.  If a realm definition does not
contain a \fBstatedir\fR field, then that realm will use the \fBconfigdir\fR field
as its \fBstatedir\fR field.
.Sp
The \fBDT_STATEDIR\fR environment variable is set to the \fBstatedir\fR field.  This
will tell the DNSSEC-Tools programs and modules where to find these files.
.IP \fBrealmdir\fR 4
.IX Item "realmdir"
The \fBrealmdir\fR field of the \fBrealms\fR file contains the name of the directory
in which the realm executes.  This is where the realm's zone, key, and other
files are located.
.IP \fBrollrec\fR 4
.IX Item "rollrec"
The \fBrollrec\fR field of the \fBrealms\fR file is the name of the file that
controls zone rollover.  This file points to the various \fBkeyrec\fR files that
define the locations of the zone files and their associated key files.  A
realm's \fBrollrec\fR file can locate these files anywhere on the system, but it
is \fIstrongly\fR recommended that they all remain within the realm's \fBrealmdir\fR
hierarchy.
.PP
While the DNSSEC-Tools programs will work fine if a realm's configuration,
state, and realm directories are actually one directory, it is recommended
that at the least the \fBrealmdir\fR files be separated from the \fBconfigdir\fR
and \fBstatedir\fR files.
.PP
It is further recommended that the files for the various realms be segregated
from each other.
.SH OPTIONS
.IX Header "OPTIONS"
The following options are handled by \fBdtrealms\fR.
.IP \fB\-directory\fR 4
.IX Item "-directory"
Directory in which \fBdtrealms\fR will be executed.  Any relative paths given
in realms configuration files will use this directory as their base.
.IP \fB\-display\fR 4
.IX Item "-display"
Start the \fBgrandvizier\fR display program to give a graphical indication of
realm status.
.IP \fB\-foreground\fR 4
.IX Item "-foreground"
Run \fBdtrealms\fR in the foreground instead of as a daemon.
.IP \fB\-logfile\fR 4
.IX Item "-logfile"
Logging file to use.
.IP \fB\-loglevel\fR 4
.IX Item "-loglevel"
Logging level to use when writing to the log file.  See \fBrolllog\|(3)\fR for
more details.
.IP \fB\-logtz\fR 4
.IX Item "-logtz"
Time zone to use with the log file.  This must be either "gmt" or "local".
.IP \fB\-Version\fR 4
.IX Item "-Version"
Displays the version information for \fBdtrealms\fR and the DNSSEC-Tools package.
.IP \fB\-help\fR 4
.IX Item "-help"
Displays a help message and exits.
.SH WARNING
.IX Header "WARNING"
This is an early prototype.  Consider it to be beta quality.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2011\-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"
\&\fBgrandvizier\|(8)\fR,
\&\fBlsrealm\|(8)\fR,
\&\fBrealminit\|(8)\fR,
\&\fBrealmset\|(8)\fR
.PP
\&\fBNet::DNS::SEC::Tools::realm.pm\|(3)\fR,
\&\fBNet::DNS::SEC::Tools::realmmgr.pm\|(3)\fR,
\&\fBNet::DNS::SEC::Tools::rolllog.pm\|(3)\fR