.\" 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 "realm 3pm"
.TH realm 3pm "2012-06-14" "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"
Realm \- Realm\-related data used by DNSSEC\-Tools programs.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The DNSSEC-Tools \fBdtrealms\fR command manages a group of distinct rollover
environments running on a single host.  These distinct rollover environments
are called \fIrealms\fR.  \fBdtrealms\fR uses a \fIrealm\fR file to properly create
and manage each of its realms.
.PP
A \fIrealms\fR file is organized in sets of \fIrealm\fR records.  Each \fIrealm\fR
record describes the execution environment of a single rollover instance.
A \fIrealm\fR consists of a set of keyword/value entries.
.PP
The DNSSEC-Tools \fBrealm.pm\fR module manipulates the contents of a \fIrealm\fR
file.  Module interfaces exist for looking up \fIrealm\fR records, creating new
records, and modifying existing records.
.PP
Comment lines and blank lines are ignored by the DNSSEC-Tools programs.
Comment lines start with either a '#' character or a ';' character.
.PP
A \fIrealm\fR's name may consist of alphabetic characters, numbers, and several
special characters.  The special characters are the minus sign, the plus sign,
the underscore, the comma, the period, the colon, the forward-slash, the
space, and the tab.  This name is an identifier.
.PP
The values in a \fIrealm\fR's entries may consist of alphabetic characters,
numbers, and several special characters.  The special characters are the
minus sign, the plus sign, the underscore, the comma, the period, the
colon, the forward-slash, the space, and the tab.
.SH "REALM FIELDS"
.IX Header "REALM FIELDS"
The fields in a \fIrealm\fR record are:
.PP
.Vb 1
\& * administrator
.Ve
.PP
This is the email address for the realm's administrative user.
.PP
.Vb 1
\& * args
.Ve
.PP
The user-specified arguments for the rollover manager.  This is not a
required field.
.PP
.Vb 1
\& * configdir
.Ve
.PP
This field contains the name of the directory in which \fBdtrealms\fR will
find the realm's configuration information.  This directory must contain
a subdirectory named \fBdnssec-tools\fR, and the realm's configuration file
will be stored there.  This is a required field.
.PP
.Vb 1
\& * display
.Ve
.PP
This boolean field indicates whether or not the realm should be displayed
by the \fBgrandvizier\fR program.  This is an optional field.
.PP
.Vb 1
\& * hoard
.Ve
.PP
This field contains the pathname to a collection of files used to build a
realm.  This field is \fBonly\fR used by the \fBbuildrealms\fR program.
.PP
.Vb 1
\& * manager
.Ve
.PP
This field contains the name of the rollover manager program for the realm.
If this is not defined, then \fBrollerd\fR will be used.
.PP
.Vb 1
\& * realmdir
.Ve
.PP
This field contains the name of the directory in which \fBdtrealms\fR will
execute the realm's rollover manager.  This is a required field.
.PP
.Vb 1
\& * rollrec
.Ve
.PP
The realm's \fBrollrec\fR file.  This file will be used by the rollover manager
to control the rollover environment.
.PP
.Vb 1
\& * state
.Ve
.PP
This field contains the realm's state.  It must be either \*(L"active\*(R" or
\&\*(L"inactive\*(R".
.PP
.Vb 1
\& * statedir
.Ve
.PP
This field contains the name of the directory in which \fBrollerd\fR and other
DNSSEC-Tools programs will find the realm's state information.  If this is
not specified, the \fBconfigdir\fR directory will be used.
.PP
.Vb 1
\& * user
.Ve
.PP
This field contains the name of the user that the realm will be executed as.
This is an optional field.  \fIThis is not yet implemented in \f(BIdtrealms\fI.\fR
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The following are examples of \fIrealm\fRs:
.PP
.Vb 11
\&    realm "example"
\&            state           "active"
\&            configdir       "/realms/configs/example"
\&            statedir        "/realms/states/example"
\&            realmdir        "/realms/realms/example"
\&            rollrec         "demo\-example.rollrec"
\&            administrator   "zonefolks@example.com"
\&            display         "1"
\&            manager         "rollerd"
\&            args            "\-sleep 600 \-loglevel phase \-logfile log.example"
\&            user            "zonemgr"
\&
\&    realm "testing"
\&            state           "inactive"
\&            configdir       "/realms/configs/testing"
\&            realmdir        "/realms/realms/testing"
\&            rollrec         "demo\-testing.rollrec"
\&            display         "1"
\&            manager         "rollerd\-tester"
\&            args            "\-sleep 60 \-loglevel tmi \-logfile log.testing"
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 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(BIbuildrealms\fB\|(8)\fR,
\&\fB\f(BIdtrealms\fB\|(8)\fR,
\&\fB\f(BIgrandvizier\fB\|(8)\fR,
\&\fB\f(BIlsrealm\fB\|(8)\fR,
\&\fB\f(BIrealmchk\fB\|(8)\fR,
\&\fB\f(BIrealminit\fB\|(8)\fR
.PP
\&\fB\f(BINet::DNS::SEC::Tools::keyrec\fB\|(3)\fR,
\&\fB\f(BINet::DNS::SEC::Tools::rollrec\fB\|(3)\fR
.PP
\&\fB\f(BIkeyrec\fB\|(5)\fR