.\" 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 "REALMINIT 1p"
.TH REALMINIT 1p "2012-06-21" "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"
realminit \- Create new realm records for a DNSSEC\-Tools realms file.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  realminit [options] <realm1> ... <realmN>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBrealminit\fR creates new \fIrealm\fR entries for a \fBrealms\fR file.  \fBdtrealms\fR
manages multiple distinct DNSSEC-Tools rollover environments running
simultaneously.  Each rollover environment, called a realm, is defined in a
\&\fBrealms\fR file.  \fBdtrealms\fR uses this file to determine how to run the
rollover environment.  This is useful for such things as managing very large
collections of zones, segregating customer zones, and software tests.
.PP
The newly generated \fIrealm\fR entries are written to standard output,
unless the \fB\-out\fR option is specified.
.PP
A \fBrealms\fR file contains a number of entries, one for each managed \fIrealm\fR.
A \fIrealm\fR entry has this format:
.PP
.Vb 10
\&    realm "example"
\&        state          "active"
\&        configdir      "/usr/realms/configs/example"
\&        statedir       "/usr/realms/states/example"
\&        realmsdir      "/usr/realms/realms\-files/example"
\&        rollrec        "example.rrf"
\&        administrator  "bob@cat.example.com"
\&        display        "1"
\&        manager        "rollerd"
\&        args           "\-display \-loglevel phase"
.Ve
.PP
Multiple \fIrealm\fR entries may be created with a single execution of
\&\fBrealminit\fR.  Except for the entry's name field, the entries will be exactly
the same unless the '=' metacharacter is used in the command-line options.  If
the values of the \fBconfigdir\fR, \fBstatedir\fR, \fBrealmdir\fR, \fBrollrec\fR,
\&\fBadministrator\fR, \fBargs\fR, or \fBuser\fR options contain an '=', then it will be
replaced with the realm's name when building the entry.  See the \s-1EXAMPLES\s0
section for examples of how options are used by \fBrealminit\fR.
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\fBrealminit\fR may be given the following options:
.IP "\fB\-active\fR" 4
.IX Item "-active"
This indicates that \fBdtrealms\fR should start the realm when \fBdtrealms\fR
starts.  \fIrealms\fR are active by default.
.IP "\fB\-administrator\fR" 4
.IX Item "-administrator"
This is the email address for the realm's administrator.
.IP "\fB\-args\fR" 4
.IX Item "-args"
This is a set of command-line arguments passed to the realm's
rollover manager when the realm is started.
.IP "\fB\-configdir\fR" 4
.IX Item "-configdir"
This is the realm's configuration directory.  This will contain such files
as the DNSSEC-Tools configuration file for that realm.
.IP "\fB\-display\fR" 4
.IX Item "-display"
This indicates if the realm should be included in \fBgrandvizier\fR output.
.IP "\fB\-inactive\fR" 4
.IX Item "-inactive"
This indicates that \fBdtrealms\fR should not start the realm when \fBdtrealms\fR
starts.
.IP "\fB\-manager\fR" 4
.IX Item "-manager"
This is the rollover manager for the realm.  \fBrollerd\fR is the default
rollover manager, but other managers may be used.
.IP "\fB\-out output-file\fR" 4
.IX Item "-out output-file"
The new \fIrealm\fR entries will be appended to \fIoutput-file\fR.
The file will be created if it does not exist.
.Sp
If this option is not given, the new \fIrollrec\fR entries will be written
to standard output.
.IP "\fB\-realmdir\fR" 4
.IX Item "-realmdir"
This is the realm's data directory.  This directory is expected to contain the
\&\fBrollrec\fR file, zone files, \fBkeyrec\fR files, and key files for the zones in
that realm.
.IP "\fB\-rollrec\fR" 4
.IX Item "-rollrec"
This is the path to the realm's \fBrollrec\fR file.  This is used to control
rollover actions for the realm.  If it is not an absolute path, it will be
assumed to be relative to the \fBrealmdir\fR field.
.IP "\fB\-statedir\fR" 4
.IX Item "-statedir"
This is the realm's state directory.  This will contain such files as that
realm's \fBrollrec\fR lock file and the \fBrollerd\fR communications socket.  If the
\&\fBstatedir\fR is not defined for a realm, then the realm's \fBconfigdir\fR is used
for that value.
.IP "\fB\-user\fR" 4
.IX Item "-user"
This is the user that the realm is executed as.
(\fIThis is not yet implemented in \f(BIdtrealms\fI.\fR)
.IP "\fB\-help\fR" 4
.IX Item "-help"
Display a usage message.
.IP "\fB\-Version\fR" 4
.IX Item "-Version"
Display version information for \fBrealminit\fR and DNSSEC-Tools.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The following options should make clear how \fBrealminit\fR deals with options
and the new \fIrealm\fRs.  Example 1 will show the complete new \fIrealm\fR record.
For the sake of brevity, the remaining examples will only show the fields
relevant to that example.  Further examples will also use short-hand forms
of the option names.
.SS "Example 1.  One realm, with \-statedir"
.IX Subsection "Example 1.  One realm, with -statedir"
This example shows the \fIrealm\fR generated by giving \fBrealminit\fR a single
realm.
.PP
.Vb 1
\&    $ realminit \-active \-configdir /realms/confs/example \-statedir /realms/states/example \-realmdir /realms/realms/example \-rollrec example.rrf \-admin bob@cat.example.com \-args "\-loglevel phase \-logfile logger" example
\&
\&    realm       "example"
\&        state           "active"
\&        configdir       "/realms/confs/example"
\&        statedir        "/realms/states/example"
\&        realmdir        "/realms/realms/example"
\&        rollrec         "example.rrf"
\&        administrator   "bob@cat.example.com"
\&        display         "1"
\&        manager         "rollerd"
\&        args            "\-loglevel phase \-logfile logger"
.Ve
.SS "Example 2.  One realm, without \-statedir"
.IX Subsection "Example 2.  One realm, without -statedir"
This example shows the \fIrealm\fR generated by giving \fBrealminit\fR a single
realm.
.PP
.Vb 1
\&    $ realminit \-active \-configdir /realms/confs/example \-realmdir /realms/realms/example \-rollrec example.rrf \-admin bob@cat.example.com \-args "\-loglevel phase \-logfile logger" example
\&
\&    realm       "example"
\&        state           "active"
\&        configdir       "/realms/confs/example"
\&        statedir        "/realms/confs/example"
\&        ...
.Ve
.SS "Example 3.  Two realms, without metacharacters"
.IX Subsection "Example 3.  Two realms, without metacharacters"
This example shows the \fIrealms\fR generated by giving \fBrealminit\fR two
realms, without using the special \*(L"=\*(R" metacharacter.
.PP
.Vb 1
\&    $ realminit \-configdir /realms/confs/example \-statedir /realms/states/example \-realmdir /realms/realms/example \-rollrec example.rrf \-admin bob@cat.example.com example test
\&
\&    realm       "example"
\&        configdir       "/realms/confs/example"
\&        statedir        "/realms/states/example"
\&        realmdir        "/realms/realms/example"
\&        rollrec         "example.rrf"
\&        administrator   "bob@cat.example.com"
\&        ...
\&
\&    realm       "test"
\&        configdir       "/realms/confs/example"
\&        statedir        "/realms/states/example"
\&        realmdir        "/realms/realms/example"
\&        rollrec         "example.rrf"
\&        administrator   "bob@cat.example.com"
\&        ...
.Ve
.SS "Example 4.  Two realms, with metacharacters"
.IX Subsection "Example 4.  Two realms, with metacharacters"
This example shows the \fIrealms\fR generated by giving \fBrealminit\fR two
realms, and that uses the special \*(L"=\*(R" metacharacter.
.PP
.Vb 1
\&    $ realminit \-configdir /realms/confs/= \-statedir /realms/states/= \-realmdir /realms/realms/= \-rollrec =.rrf \-admin bob@cat.=.com example test
\&
\&    realm       "example"
\&        configdir       "/realms/confs/example"
\&        statedir        "/realms/states/example"
\&        realmdir        "/realms/realms/example"
\&        rollrec         "example.rrf"
\&        administrator   "bob@cat.example.com"
\&        ...
\&
\&    realm       "test"
\&        configdir       "/realms/confs/test"
\&        statedir        "/realms/states/test"
\&        realmdir        "/realms/realms/test"
\&        rollrec         "test.rrf"
\&        administrator   "bob@cat.test.com"
\&        ...
.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(BIlsrealm\fB\|(1)\fR,
\&\fB\f(BIdtrealms\fB\|(8)\fR,
\&\fB\f(BIrealmchk\fB\|(8)\fR
.PP
\&\fB\f(BINet::DNS::SEC::Tools::realm.pm\fB\|(3)\fR,
.PP
\&\fB\f(BIfile\-realmrec.pm\fB\|(5)\fR