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   "[email protected]"
                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, [email protected]