Provided by: dnssec-tools_2.2-2_all 
NAME
Net::DNS::SEC::Tools::realm - Manipulate a DNSSEC-Tools realm file.
SYNOPSIS
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",\%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();
DESCRIPTION
The Net::DNS::SEC::Tools::realm module manipulates the contents of a DNSSEC-Tools realm
file. realm files describe the status of a zone rollover environment, as managed by the
DNSSEC-Tools programs. Module interfaces exist for looking up realm records, creating new
records, and modifying existing records.
A realm file is organized in sets of realm records. realms describe the state of a
rollover environment. A realm consists of a set of keyword/value entries. The following
is an example of a realm:
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"
The first step in using this module must be to read the realm file. The realm_read()
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 realm.pm routines) and in an array
(for preserving formatting and comments.)
After the file has been read, the contents are referenced using realm_fullrec() and
realm_recval(). The realm_add() and realm_setval() interfaces are used to modify the
contents of a realm record.
If the realm file has been modified, it must be explicitly written or the changes will not
saved. realm_write() saves the new contents to disk. realm_close() saves the file and
close the Perl file handle to the realm file. If a realm file is no longer wanted to be
open, yet the contents should not be saved, realm_discard() gets rid of the data closes
and the file handle without saving any modified data.
On reading a realm file, consecutive blank lines are collapsed into a single blank line.
As realm 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.
REALM LOCKING
This module includes interfaces for synchronizing access to the realm files. This
synchronization is very simple and relies upon locking and unlocking a single lock file
for all realm files.
realm locking is not required before using this module, but it is recommended. The
expected use of these facilities follows:
realm_lock() || die "unable to lock realm file\n";
realm_read();
... perform other realm operations ...
realm_close();
realm_unlock();
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 realm locking is performed.
This synchronization method has the disadvantage of having a single lockfile as a
bottleneck to all realm file access. However, it reduces complexity in the locking
interfaces and cuts back on the potential number of required lockfiles.
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.
REALM INTERFACES
The interfaces to the realm.pm module are given below.
realm_add(realm_type,realm_name,fields)
This routine adds a new realm to the realm file and the internal representation of the
file contents. The realm is added to both the %realms hash table and the @realmlines
array. Entries are only added if they are defined for realms.
realm_type is the type of the realm. This must be "realm". realm_name is the name of
the realm. fields is a reference to a hash table that contains the name/value realm
fields. The keys of the hash table are always converted to lowercase, but the entry
values are left as given.
A blank line is added after the final line of the new realm. The realm file is not
written after realm_add(), though it is internally marked as having been modified.
realm_del(realm_name)
This routine deletes a realm from the realm file and the internal representation of
the file contents. The realm is deleted from both the %realms hash table and the
@realmlines array.
Only the realm itself is deleted from the file. Any associated comments and blank
lines surrounding it are left intact. The realm file is not written after
realm_del(), though it is internally marked as having been modified.
Return values are:
0 successful realm deletion
-1 unknown name
realm_close()
This interface saves the internal version of the realm file (opened with realm_read())
and closes the file handle.
realm_delfield(realm_name,field)
Deletes the given field from the specified realm. The file is not written after
updating the value, but the internal file-modified flag is set. The value is saved in
both %realms and in @realmlines.
Return values:
0 - failure (realm not found or realm does not
contain the field)
1 - success
realm_discard()
This routine removes a realm file from use by a program. The internally stored data
are deleted and the realm file handle is closed. However, modified data are not saved
prior to closing the file handle. Thus, modified and new data will be lost.
realm_exists(realm_name)
This routine returns a boolean flag indicating if the realm named in realm_name
exists.
realm_fullrec(realm_name)
realm_fullrec() returns a reference to the realm specified in realm_name.
realm_lock()
realm_lock() locks the realm lockfile. An exclusive lock is requested, so the
execution will suspend until the lock is available. If the realm synchronization file
does not exist, it will be created. If the process can't create the synchronization
file, an error will be returned.
Success or failure is returned.
realm_merge(target_realm_file, realm_file1, ... realm_fileN)
This interface merges the specified realm files. It reads each file and parses them
into a realm hash table and a file-contents array. The resulting merge is written to
the file named by target_realm_file. If another realm is already open, it is saved
and closed prior to opening the new realm.
If target_realm_file is an existing realm file, its contents will be merged with the
other files passed to realm_merge(). If the file does not exist, realm_merge() will
create it and merge the remaining files into it.
Upon success, realm_read() returns the number of realms read from the file.
Failure return values:
-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
realm_names()
This routine returns a list of the realm names from the file.
realm_read(realm_file)
This interface reads the specified realm file and parses it into a realm hash table
and a file-contents array. realm_read() must be called prior to any of the other
realm.pm calls. If another realm is already open, it is saved and closed prior to
opening the new realm.
realm_read() attempts to open the realm file for reading and writing. If this fails,
then it attempts to open the file for reading only.
realm_read() is a front-end for realm_readfile(). It sets up the module's saved data
in preparation for reading a new realm file. These house-keeping actions are not
performed by realm_readfile().
Upon success, realm_read() returns the number of realms read from the file.
Failure return values:
-1 specified realm file doesn't exit
-2 unable to open realm file
-3 duplicate realm names in file
realm_readfile(realm_file_handle)
This interface reads the specified file handle to a realm file and parses the file
contents into a realm hash table and a file-contents array. The hash table and file-
contents array are not cleared prior to adding data to them.
Upon success, realm_read() returns zero.
Failure return values:
-1 duplicate realm names in file
realm_rectype(realm_name,rectype)
Set the type of the specified realm record. The file is not written after updating
the value, but the internal file-modified flag is set. The value is saved in both
%realms and in @realmlines.
realm_name is the name of the realm that will be modified. rectype is the new type of
the realm, which must be "realm".
Return values:
0 - failure (invalid record type or realm not found)
1 - success
realm_recval(realm_name,realm_field)
This routine returns the value of a specified field in a given realm. realm_name is
the name of the particular realm to consult. realm_field is the field name within
that realm.
For example, the current realm file contains the following realm.
realm "example"
rollrec "example.rrf"
The call:
realm_recval("example","rollrec")
will return the value "example.rrf".
realm_rename(old_realm_name,new_realm_name)
This routine renames the realm named by old_realm_name to new_realm_name. The actual
effect is to change the name in the realm line to new_realm_name. The name is changed
in the internal version of the the realm file only. The file itself is not changed,
but must be saved by calling either realm_write(), realm_save(), or realm_saveas().
old_realm_name must be the name of an existing realm. Conversely, new_realm_name must
not name an existing realm.
Return values:
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
realm_setval(realm_name,field,value)
Set the value of a name/field pair in a specified realm. The file is not written
after updating the value, but the internal file-modified flag is set. The value is
saved in both %realms and in @realmlines.
realm_name is the name of the realm that will be modified. If the named realm does
not exist, it will be created as a "realm"-type realm. field is the realm field which
will be modified. value is the new value for the field.
realm_split(new_realm_file,realm_names)
Move a set of realm entries from the current realm file to a new file. The moved
realm entries are removed both from the current file and from the internal module data
representing that file.
The new_realm_file parameter holds the name of the new realm file. If this file
doesn't exist, it will be created. If it does exist, the realm entries will be
appended to that file.
realm_names is a list of realm entries that will be moved from the current file to the
file named in new_realm_file. If some of the given realm 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.
Only the realm entries themselves will be moved to the new realm file. Any associated
comments will be left in the current realm file.
On success, the count of moved realm entries is returned. Error returns are given
below.
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.
realm_unlock()
realm_unlock() unlocks the realm synchronization file.
realm_write()
This interface saves the internal version of the realm file (opened with
realm_read()). 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 realm file, it is not rewritten.
realm_write() gets an exclusive lock on the realm file while writing.
REALM INTERNAL INTERFACES
The interfaces described in this section are intended for internal use by the realm.pm
module. However, there are situations where external entities may have need of them. Use
with caution, as misuse may result in damaged or lost realm files.
realm_init()
This routine initializes the internal realm data. Pending changes will be lost. A
new realm file must be read in order to use the realm.pm interfaces again.
realm_default()
This routine returns the name of the default realm file.
REALM DEBUGGING INTERFACES
The following interfaces display information about the currently parsed realm file. They
are intended to be used for debugging and testing, but may be useful at other times.
realm_dump_hash()
This routine prints the realm file as it is stored internally in a hash table. The
realms are printed in alphabetical order, with the fields alphabetized for each realm.
New realms and realm fields are alphabetized along with current realms and fields.
Comments from the realm file are not included with the hash table.
realm_dump_array()
This routine prints the realm file as it is stored internally in an array. The realms
are printed in the order given in the file, with the fields ordered in the same
manner. New realms are appended to the end of the array. realm fields added to
existing realms are added at the beginning of the realm entry. Comments and vertical
whitespace are preserved as given in the realm file.
COPYRIGHT
Copyright 2012-2014 SPARTA, Inc. All rights reserved. See the COPYING file included with
the DNSSEC-Tools package for details.
AUTHOR
Wayne Morrison, tewok@tislabs.com
SEE ALSO
lsrealm(1), realmchk(8), realminit(8)
Net::DNS::SEC::Tools::realm(3),