.\" -*- 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 "realm 3"
.TH realm 3 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
Net::DNS::SEC::Tools::realm \- Manipulate a DNSSEC\-Tools realm file.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::DNS::SEC::Tools::realm;
\&
\&  realm_lock();
\&  realm_read("localhost.realm");
\&
\&  @rlmnames = realm_names();
\&
\&  $flag = realm_exists("example");
\&
\&  $rrec = realm_fullrec("example");
\&  %rrhash = %$rrec;
\&  $zname = $rrhash{"maxttl"};
\&
\&  $val = realm_recval("example","state");
\&
\&  realm_add("realm","example",\e%realmfields);
\&
\&  realm_del("example");
\&
\&  realm_rename("example","test\-realm");
\&
\&  realm_setval("example","rollrec","example.rrf");
\&
\&  realm_delfield("example","user");
\&
\&  @realmfields = realm_fields();
\&
\&  $count = realmrec_merge("primary.realm", "new0.realm", "new1.realm");
\&  @retvals = realmrec_split("new\-realm.rrf", @list_of_realms);
\&
\&
\&  $default_file = realm_default();
\&
\&  realm_write();
\&  realm_close();
\&  realm_discard();
\&
\&  realm_unlock();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBNet::DNS::SEC::Tools::realm\fR module manipulates the contents of a
DNSSEC-Tools \fIrealm\fR file.  \fIrealm\fR files describe the status of a
zone rollover environment, as managed by the DNSSEC-Tools programs.  Module
interfaces exist for looking up \fIrealm\fR records, creating new records,
and modifying existing records.
.PP
A \fIrealm\fR file is organized in sets of \fIrealm\fR records.  \fIrealm\fRs
describe the state of a rollover environment.  A \fIrealm\fR consists of a set
of keyword/value entries.  The following is an example of a \fIrealm\fR:
.PP
.Vb 9
\&        realm "production"
\&                state           "active"
\&                realmdir        "/usr/etc/dnssec\-tools/realms/production"
\&                configdir       "/usr/etc/dnssec\-tools/configs/production"
\&                rollrec         "production.rollrec"
\&                administrator   "sysfolks@example.com"
\&                display         "1"
\&                args            "\-loglevel phase \-logfile log.prod \-display"
\&                user            "prodmgr"
.Ve
.PP
The first step in using this module must be to read the \fIrealm\fR file.  The
\&\fR\f(BIrealm_read()\fR\fI\fR interface reads the file and parses it into an internal
format.  The file's records are copied into a hash table (for easy reference
by the \fBrealm.pm\fR routines) and in an array (for preserving formatting and
comments.)
.PP
After the file has been read, the contents are referenced using
\&\fR\f(BIrealm_fullrec()\fR\fI\fR and \fI\fR\f(BIrealm_recval()\fR\fI\fR.  The \fI\fR\f(BIrealm_add()\fR\fI\fR and
\&\fI\fR\f(BIrealm_setval()\fR\fI\fR interfaces are used to modify the contents of a \fIrealm\fR
record.
.PP
If the \fIrealm\fR file has been modified, it must be explicitly written or the
changes will not saved.  \fR\f(BIrealm_write()\fR\fI\fR saves the new contents to disk.
\&\fI\fR\f(BIrealm_close()\fR\fI\fR saves the file and close the Perl file handle to the \fIrealm\fR
file.  If a \fIrealm\fR file is no longer wanted to be open, yet the contents
should not be saved, \fI\fR\f(BIrealm_discard()\fR\fI\fR gets rid of the data closes and the
file handle \fBwithout\fR saving any modified data.
.PP
On reading a \fIrealm\fR file, consecutive blank lines are collapsed into a
single blank line.  As \fIrealm\fR entries are added and deleted, files merged
and files split, it is possible for blocks of consecutive blanks lines to
grow.  This will prevent these blocks from growing excessively.
.SH "REALM LOCKING"
.IX Header "REALM LOCKING"
This module includes interfaces for synchronizing access to the \fIrealm\fR
files.  This synchronization is very simple and relies upon locking and
unlocking a single lock file for all \fIrealm\fR files.
.PP
\&\fIrealm\fR locking is not required before using this module, but it is
recommended.  The expected use of these facilities follows:
.PP
.Vb 5
\&    realm_lock() || die "unable to lock realm file\en";
\&    realm_read();
\&    ... perform other realm operations ...
\&    realm_close();
\&    realm_unlock();
.Ve
.PP
Synchronization is performed in this manner due to the way the module's
functionality is implemented, as well as providing flexibility to users
of the module.  It also provides a clear delineation in callers' code as
to where and when \fIrealm\fR locking is performed.
.PP
This synchronization method has the disadvantage of having a single lockfile
as a bottleneck to all \fIrealm\fR file access.  However, it reduces complexity
in the locking interfaces and cuts back on the potential number of required
lockfiles.
.PP
Using a single synchronization file may not be practical in large
installations.  If that is found to be the case, then this will be reworked.
.SH "REALM INTERFACES"
.IX Header "REALM INTERFACES"
The interfaces to the \fBrealm.pm\fR module are given below.
.IP \fIrealm_add(realm_type,realm_name,fields)\fR 4
.IX Item "realm_add(realm_type,realm_name,fields)"
This routine adds a new \fIrealm\fR to the \fIrealm\fR file and the internal
representation of the file contents.  The \fIrealm\fR is added to both the
\&\fR\f(CI%realms\fR\fI\fR hash table and the \fI\fR\f(CI@realmlines\fR\fI\fR array.  Entries are only
added if they are defined for \fIrealm\fRs.
.Sp
\&\fIrealm_type\fR is the type of the \fIrealm\fR.  This must be "realm".
\&\fIrealm_name\fR is the name of the \fIrealm\fR.  \fIfields\fR is a reference to a
hash table that contains the name/value \fIrealm\fR fields.  The keys of the
hash table are always converted to lowercase, but the entry values are
left as given.
.Sp
A blank line is added after the final line of the new \fIrealm\fR.  The \fIrealm\fR
file is not written after \fR\f(BIrealm_add()\fR\fI\fR, though it is internally marked as
having been modified.
.IP \fIrealm_del(realm_name)\fR 4
.IX Item "realm_del(realm_name)"
This routine deletes a \fIrealm\fR from the \fIrealm\fR file and the internal
representation of the file contents.  The \fIrealm\fR is deleted from both
the \fR\f(CI%realms\fR\fI\fR hash table and the \fI\fR\f(CI@realmlines\fR\fI\fR array.
.Sp
Only the \fIrealm\fR itself is deleted from the file.  Any associated comments
and blank lines surrounding it are left intact.  The \fIrealm\fR file is not
written after \fR\f(BIrealm_del()\fR\fI\fR, though it is internally marked as having been
modified.
.Sp
Return values are:
.Sp
.Vb 2
\&     0 successful realm deletion
\&    \-1 unknown name
.Ve
.IP \fR\f(BIrealm_close()\fR\fI\fR 4
.IX Item "realm_close()"
This interface saves the internal version of the \fIrealm\fR file (opened with
\&\fR\f(BIrealm_read()\fR\fI\fR) and closes the file handle.
.IP \fIrealm_delfield(realm_name,field)\fR 4
.IX Item "realm_delfield(realm_name,field)"
Deletes the given field from the specified \fIrealm\fR.  The file is
\&\fBnot\fR written after updating the value, but the internal file-modified flag
is set.  The value is saved in both \fR\f(CI%realms\fR\fI\fR and in \fI\fR\f(CI@realmlines\fR\fI\fR.
.Sp
Return values:
.Sp
.Vb 3
\&    0 \- failure (realm not found or realm does not
\&        contain the field)
\&    1 \- success
.Ve
.IP \fR\f(BIrealm_discard()\fR\fI\fR 4
.IX Item "realm_discard()"
This routine removes a \fIrealm\fR file from use by a program.  The internally
stored data are deleted and the \fIrealm\fR file handle is closed.  However,
modified data are not saved prior to closing the file handle.  Thus, modified
and new data will be lost.
.IP \fIrealm_exists(realm_name)\fR 4
.IX Item "realm_exists(realm_name)"
This routine returns a boolean flag indicating if the \fIrealm\fR named in
\&\fIrealm_name\fR exists.
.IP \fIrealm_fullrec(realm_name)\fR 4
.IX Item "realm_fullrec(realm_name)"
\&\fR\f(BIrealm_fullrec()\fR\fI\fR returns a reference to the \fIrealm\fR specified in
\&\fIrealm_name\fR.
.IP \fR\f(BIrealm_lock()\fR\fI\fR 4
.IX Item "realm_lock()"
\&\fR\f(BIrealm_lock()\fR\fI\fR locks the \fIrealm\fR lockfile.  An exclusive lock is
requested, so the execution will suspend until the lock is available.  If the
\&\fIrealm\fR synchronization file does not exist, it will be created.  If the
process can't create the synchronization file, an error will be returned.
.Sp
Success or failure is returned.
.IP "\fIrealm_merge(target_realm_file, realm_file1, ... realm_fileN)\fR" 4
.IX Item "realm_merge(target_realm_file, realm_file1, ... realm_fileN)"
This interface merges the specified \fIrealm\fR files.  It reads each file
and parses them into a \fIrealm\fR hash table and a file-contents array.
The resulting merge is written to the file named by \fItarget_realm_file\fR.
If another \fIrealm\fR is already open, it is saved and closed prior to
opening the new \fIrealm\fR.
.Sp
If \fItarget_realm_file\fR is an existing \fIrealm\fR file, its contents will
be merged with the other files passed to \fR\f(BIrealm_merge()\fR\fI\fR.  If the file
does not exist, \fI\fR\f(BIrealm_merge()\fR\fI\fR will create it and merge the remaining
files into it.
.Sp
Upon success, \fR\f(BIrealm_read()\fR\fI\fR returns the number of \fIrealm\fRs read from
the file.
.Sp
Failure return values:
.Sp
.Vb 5
\&    \-1 no realm files were given to realm_merge
\&    \-2 unable to create target realm file
\&    \-3 unable to read first realm file
\&    \-4 an error occurred while reading the realm names
\&    \-5 realm files were duplicated in the list of realm files
.Ve
.IP \fR\f(BIrealm_names()\fR\fI\fR 4
.IX Item "realm_names()"
This routine returns a list of the \fIrealm\fR names from the file.
.IP \fIrealm_read(realm_file)\fR 4
.IX Item "realm_read(realm_file)"
This interface reads the specified \fIrealm\fR file and parses it into a
\&\fIrealm\fR hash table and a file-contents array.  \fR\f(BIrealm_read()\fR\fI\fR \fBmust\fR be
called prior to any of the other \fBrealm.pm\fR calls.  If another \fIrealm\fR
is already open, it is saved and closed prior to opening the new \fIrealm\fR.
.Sp
\&\fR\f(BIrealm_read()\fR\fI\fR attempts to open the \fIrealm\fR file for reading and
writing.  If this fails, then it attempts to open the file for reading only.
.Sp
\&\fR\f(BIrealm_read()\fR\fI\fR is a front-end for \fI\fR\f(BIrealm_readfile()\fR\fI\fR.  It sets up the
module's saved data in preparation for reading a new \fIrealm\fR file.  These
house-keeping actions are not performed by \fI\fR\f(BIrealm_readfile()\fR\fI\fR.
.Sp
Upon success, \fR\f(BIrealm_read()\fR\fI\fR returns the number of \fIrealm\fRs read from
the file.
.Sp
Failure return values:
.Sp
.Vb 3
\&    \-1 specified realm file doesn\*(Aqt exit
\&    \-2 unable to open realm file
\&    \-3 duplicate realm names in file
.Ve
.IP \fIrealm_readfile(realm_file_handle)\fR 4
.IX Item "realm_readfile(realm_file_handle)"
This interface reads the specified file handle to a \fIrealm\fR file and
parses the file contents into a \fIrealm\fR hash table and a file-contents
array.  The hash table and file-contents array are \fBnot\fR cleared prior
to adding data to them.
.Sp
Upon success, \fR\f(BIrealm_read()\fR\fI\fR returns zero.
.Sp
Failure return values:
.Sp
.Vb 1
\&    \-1 duplicate realm names in file
.Ve
.IP \fIrealm_rectype(realm_name,rectype)\fR 4
.IX Item "realm_rectype(realm_name,rectype)"
Set the type of the specified \fIrealm\fR record.  The file is
\&\fBnot\fR written after updating the value, but the internal file-modified flag
is set.  The value is saved in both \fR\f(CI%realms\fR\fI\fR and in \fI\fR\f(CI@realmlines\fR\fI\fR.
.Sp
\&\fIrealm_name\fR is the name of the \fIrealm\fR that will be modified.
\&\fIrectype\fR is the new type of the \fIrealm\fR, which must be "realm".
.Sp
Return values:
.Sp
.Vb 2
\&    0 \- failure (invalid record type or realm not found)
\&    1 \- success
.Ve
.IP \fIrealm_recval(realm_name,realm_field)\fR 4
.IX Item "realm_recval(realm_name,realm_field)"
This routine returns the value of a specified field in a given \fIrealm\fR.
\&\fIrealm_name\fR is the name of the particular \fIrealm\fR to consult.
\&\fIrealm_field\fR is the field name within that \fIrealm\fR.
.Sp
For example, the current \fIrealm\fR file contains the following \fIrealm\fR.
.Sp
.Vb 2
\&    realm       "example"
\&                rollrec        "example.rrf"
.Ve
.Sp
The call:
.Sp
.Vb 1
\&    realm_recval("example","rollrec")
.Ve
.Sp
will return the value "example.rrf".
.IP \fIrealm_rename(old_realm_name,new_realm_name)\fR 4
.IX Item "realm_rename(old_realm_name,new_realm_name)"
This routine renames the \fIrealm\fR named by \fIold_realm_name\fR to
\&\fInew_realm_name\fR.  The actual effect is to change the name in the \fIrealm\fR
line to \fInew_realm_name\fR.  The name is changed in the internal version of the
the \fIrealm\fR file only.  The file itself is not changed, but must be saved by
calling either \fR\f(BIrealm_write()\fR\fI\fR, \fI\fR\f(BIrealm_save()\fR\fI\fR, or \fI\fR\f(BIrealm_saveas()\fR\fI\fR.
.Sp
\&\fIold_realm_name\fR must be the name of an existing \fIrealm\fR.  Conversely,
\&\fInew_realm_name\fR must not name an existing \fIrealm\fR.
.Sp
Return values:
.Sp
.Vb 6
\&     0 \- success
\&    \-1 \- old_realm_name was null or empty
\&    \-2 \- new_realm_name was null or empty
\&    \-3 \- old_realm_name is not an existing realm
\&    \-4 \- new_realm_name is already a realm
\&    \-5 \- internal error that should never happen
.Ve
.IP \fIrealm_setval(realm_name,field,value)\fR 4
.IX Item "realm_setval(realm_name,field,value)"
Set the value of a name/field pair in a specified \fIrealm\fR.  The file is
\&\fBnot\fR written after updating the value, but the internal file-modified flag
is set.  The value is saved in both \fR\f(CI%realms\fR\fI\fR and in \fI\fR\f(CI@realmlines\fR\fI\fR.
.Sp
\&\fIrealm_name\fR is the name of the \fIrealm\fR that will be modified.  If the
named \fIrealm\fR does not exist, it will be created as a "realm"\-type
\&\fIrealm\fR.
\&\fIfield\fR is the \fIrealm\fR field which will be modified.
\&\fIvalue\fR is the new value for the field.
.IP \fIrealm_split(new_realm_file,realm_names)\fR 4
.IX Item "realm_split(new_realm_file,realm_names)"
Move a set of \fIrealm\fR entries from the current \fIrealm\fR file to a new
file.  The moved \fIrealm\fR entries are removed both from the current file
and from the internal module data representing that file.
.Sp
The \fInew_realm_file\fR parameter holds the name of the new \fIrealm\fR file.
If this file doesn't exist, it will be created.  If it does exist, the
\&\fIrealm\fR entries will be appended to that file.
.Sp
\&\fIrealm_names\fR is a list of \fIrealm\fR entries that will be moved from the
current file to the file named in \fInew_realm_file\fR.  If some of the given
\&\fIrealm\fR names are invalid, the valid names will be moved to the new file
and the invalid names will be returned in a list to the caller.
.Sp
Only the \fIrealm\fR entries themselves will be moved to the new \fIrealm\fR
file.  Any associated comments will be left in the current \fIrealm\fR file.
.Sp
On success, the count of moved \fIrealm\fR entries is returned.  Error returns
are given below.
.Sp
Failure return values:
    \-1 \- no target realm file given in new_realm_file
    \-2 \- no realm names given in realm_names
    \-3 \- none of the realm names given are existing realms
    \-4 \- unable to open new_realm_file
    \-5 \- invalid realm names were specified in realm_names,
         followed by the list of bad names.
.IP \fR\f(BIrealm_unlock()\fR\fI\fR 4
.IX Item "realm_unlock()"
\&\fR\f(BIrealm_unlock()\fR\fI\fR unlocks the \fIrealm\fR synchronization file.
.IP \fR\f(BIrealm_write()\fR\fI\fR 4
.IX Item "realm_write()"
This interface saves the internal version of the \fIrealm\fR file (opened with
\&\fR\f(BIrealm_read()\fR\fI\fR).  It does not close the file handle.  As an efficiency
measure, an internal modification flag is checked prior to writing the file.
If the program has not modified the contents of the \fIrealm\fR file, it is not
rewritten.
.Sp
\&\fR\f(BIrealm_write()\fR\fI\fR gets an exclusive lock on the \fIrealm\fR file while writing.
.SH "REALM INTERNAL INTERFACES"
.IX Header "REALM INTERNAL INTERFACES"
The interfaces described in this section are intended for internal use by the
\&\fBrealm.pm\fR module.  However, there are situations where external entities
may have need of them.  Use with caution, as misuse may result in damaged or
lost \fIrealm\fR files.
.IP \fR\f(BIrealm_init()\fR\fI\fR 4
.IX Item "realm_init()"
This routine initializes the internal \fIrealm\fR data.  Pending changes will
be lost.  A new \fIrealm\fR file must be read in order to use the \fBrealm.pm\fR
interfaces again.
.IP \fR\f(BIrealm_default()\fR\fI\fR 4
.IX Item "realm_default()"
This routine returns the name of the default \fIrealm\fR file.
.SH "REALM DEBUGGING INTERFACES"
.IX Header "REALM DEBUGGING INTERFACES"
The following interfaces display information about the currently parsed
\&\fIrealm\fR file.  They are intended to be used for debugging and testing, but
may be useful at other times.
.IP \fR\f(BIrealm_dump_hash()\fR\fI\fR 4
.IX Item "realm_dump_hash()"
This routine prints the \fIrealm\fR file as it is stored internally in a hash
table.  The \fIrealm\fRs are printed in alphabetical order, with the fields
alphabetized for each \fIrealm\fR.  New \fIrealm\fRs and \fIrealm\fR fields are
alphabetized along with current \fIrealm\fRs and fields.  Comments from the
\&\fIrealm\fR file are not included with the hash table.
.IP \fR\f(BIrealm_dump_array()\fR\fI\fR 4
.IX Item "realm_dump_array()"
This routine prints the \fIrealm\fR file as it is stored internally in an
array.  The \fIrealm\fRs are printed in the order given in the file, with the
fields ordered in the same manner.  New \fIrealm\fRs are appended to the end
of the array.  \fIrealm\fR fields added to existing \fIrealm\fRs are added at
the beginning of the \fIrealm\fR entry.  Comments and vertical whitespace are
preserved as given in the \fIrealm\fR file.
.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"
\&\fBlsrealm\|(1)\fR,
\&\fBrealmchk\|(8)\fR,
\&\fBrealminit\|(8)\fR
.PP
\&\fBNet::DNS::SEC::Tools::realm\|(3)\fR,