SYNOPSIS

use Net::DNS::SEC::Tools::rollrec;
rollrec_lock();
rollrec_read("localhost.rollrec");
$valid = rollrec_current();
$rrinfo = rollrec_info();
@rrnames = rollrec_names();
$flag = rollrec_exists("example.com");
$rrec = rollrec_fullrec("example.com");
%rrhash = %$rrec;
$zname = $rrhash{"maxttl"};
$val = rollrec_recval("example.com","zonefile");
rollrec_add("roll","example.com",\%rollfields);
rollrec_add("skip","example.com",\%rollfields);
rollrec_del("example.com");
rollrec_rename("example.com","subdom.example.com");
rollrec_type("example.com","roll");
rollrec_type("example.com","skip");
rollrec_setval("example.com","zonefile","db.example.com");
rollrec_delfield("example.com","directory");
rollrec_settime("example.com");
rollrec_settime("example.com",0);
@rollrecfields = rollrec_fields();
$default_file = rollrec_default();
$count = rollrec_merge("primary.rrf", "new0.rrf", "new1.rrf");
@retvals = rollrec_split("new-rollrec.rrf", @rollrec_list);
%zgroups = rollrec_zonegroups();
@zgroup = rollrec_zonegroup($zonegroupname);
@zgcmds = rollrec_zonegroup_cmds();
rollrec_write();
rollrec_close();
rollrec_discard();
rollrec_unlock();

DESCRIPTION

The Net::DNS::SEC::Tools::rollrec module manipulates the contents of a DNSSEC-Tools rollrec file. rollrec files describe the status of a zone rollover process, as performed by the DNSSEC-Tools programs. Module interfaces exist for looking up rollrec records, creating new records, and modifying existing records.

A rollrec file is organized in sets of rollrec records. rollrecs describe the state of a rollover operation. A rollrec consists of a set of keyword/value entries. The following is an example of a rollrec:

    roll "example"
        zonename                "example.com"
        zonefile                "/etc/dnssec-tools/zones/db.example.com"
        keyrec                  "/etc/dnssec-tools/keyrec/example.keyrec"
        zonegroup               "example zones"
        directory               "/etc/dnssec-tools/dir-example.com"
        kskphase                "0"
        zskphase                "2"
        maxttl                  "86400"
        administrator           "[email protected]"
        phasestart              "Wed Mar 09 21:49:22 2005"
        display                 "0"
        loglevel                "info"
        rollrec_rollsecs        "1115923362"
        rollrec_rolldate        "Tue Mar 09 19:12:54 2005"
        curerrors               0
        maxerrors               5
        # optional records:
        istrustanchor           "yes"
        holddowntime            "8W"

Additionally, commands to be acted upon at start-up can be defined using the ``cmd'' token as shown in the following example.

    cmd "rollzsk example.com"

Use this feature with caution and only if you understand the internals of rollerd and exactly what will be done by the specified command.

The first step in using this module must be to read the rollrec file. The rollrec_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 rollrec.pm routines) and in an array (for preserving formatting and comments.)

After the file has been read, the contents are referenced using rollrec_fullrec() and rollrec_recval(). The rollrec_add(), rollrec_setval(), and rollrec_settime() interfaces are used to modify the contents of a rollrec record.

If the rollrec file has been modified, it must be explicitly written or the changes will not saved. rollrec_write() saves the new contents to disk. rollrec_close() saves the file and close the Perl file handle to the rollrec file. If a rollrec file is no longer wanted to be open, yet the contents should not be saved, rollrec_discard() gets rid of the data closes and the file handle without saving any modified data.

On reading a rollrec file, consecutive blank lines are collapsed into a single blank line. As rollrec entries are added and deleted, files merged and files split, it is possible for blocks of consecutive blanks lines to grow. This blank-line collapsing will prevent these blocks from growing excessively.

There is a special rollrec called the info rollrec. It contains information about the rollrec file, such as the version of rollrecs stored within the file. It is only accessible through the rollrec_info() interface, and the rollrec_current() interface will indicate if the file's version number is current.

ROLLREC LOCKING

This module includes interfaces for synchronizing access to the rollrec files. This synchronization is very simple and relies upon locking and unlocking a single lock file for all rollrec files.

rollrec locking is not required before using this module, but it is recommended. The expected use of these facilities follows:

    rollrec_lock() || die "unable to lock rollrec file\n";
    rollrec_read();
    ... perform other rollrec operations ...
    rollrec_close();
    rollrec_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 rollrec locking is performed.

This synchronization method has the disadvantage of having a single lockfile as a bottleneck to all rollrec 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.

ROLLREC INTERFACES

The interfaces to the rollrec.pm module are given below.

rollrec_add(rollrec_type,rollrec_name,fields)

This routine adds a new rollrec to the rollrec file and the internal representation of the file contents. The rollrec is added to both the %rollrecs hash table and the @rollreclines array. Entries are only added if they are defined for rollrecs.

rollrec_type is the type of the rollrec. This must be either ``roll'' or ``skip''. rollrec_name is the name of the rollrec. fields is a reference to a hash table that contains the name/value rollrec fields. The keys of the hash table are always converted to lowercase, but the entry values are left as given.

Timestamp fields are added at the end of the rollrec. These fields have the key values rollrec_gensecs and rollrec_gendate.

A blank line is added after the final line of the new rollrec. The rollrec file is not written after rollrec_add(), though it is internally marked as having been modified.

rollrec_close()

This interface saves the internal version of the rollrec file (opened with rollrec_read()) and closes the file handle.

rollrec_current()

This routine returns a boolean indicating if this open rollrec is current, as defined by the version number in the info rollrec. Versions 0, 1, and 2 are considered to be equivalent.

Return values are:

    1 rollrec is current
    0 rollrec is obsolete
    0 rollrec has an invalid version

The last condition shouldn't ever happen and it could be argued that a failure value should be returned. However, an easy two-value boolean function was wanted, not a three-value function.

rollrec_del(rollrec_name)

This routine deletes a rollrec from the set of rollrecs loaded into memory by the rollrec.pm module. The rollrec is deleted from both the %rollrecs hash table and the @rollreclines array.

The rollrec file is not written after rollrec_del(), though the collection of rollrecs is internally marked as having been modified.

Only the rollrec itself is deleted. Any associated comments and blank lines surrounding it are left intact.

Return values are:

     0 successful rollrec deletion
    -1 unknown name

rollrec_delfield(rollrec_name,field)

Deletes the given field from the specified rollrec. The file is not written after updating the value, but the internal file-modified flag is set. The value is saved in both %rollrecs and in @rollreclines.

Return values:

    0 - failure (rollrec not found or rollrec does not
        contain the field)
    1 - success

rollrec_discard()

This routine removes a rollrec file from use by a program. The internally stored data are deleted and the rollrec file handle is closed. However, modified data are not saved prior to closing the file handle. Thus, modified and new data will be lost.

rollrec_exists(rollrec_name)

This routine returns a boolean flag indicating if the rollrec named in rollrec_name exists.

rollrec_fullrec(rollrec_name)

rollrec_fullrec() returns a reference to the rollrec specified in rollrec_name.

rollrec_info()

rollrec_info() returns a reference to the info rollrec given in the current file. This interface is the only way for a calling program to retrieve this information.

rollrec_lock()

rollrec_lock() locks the rollrec lockfile. An exclusive lock is requested, so the execution will suspend until the lock is available. If the rollrec 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.

rollrec_merge(target_rollrec_file, rollrec_file1, ... rollrec_fileN)

This interface merges the specified rollrec files. It reads each file and parses them into a rollrec hash table and a file-contents array. The resulting merge is written to the file named by target_rollrec_file. If another rollrec is already open, it is saved and closed prior to opening the new rollrec.

If target_rollrec_file is an existing rollrec file, its contents will be merged with the other files passed to rollrec_merge(). If the file does not exist, rollrec_merge() will create it and merge the remaining files into it.

The info rollrec can affect how the merging will work. If the target_rollrec_file is doesn't exist or is empty, then a simple info rollrec will be added to the file. No part of the info rollrecs will be merged into that of the target_rollrec_file.

If the file does exist but doesn't have an info rollrec rollrec, then then the source's info rollrec is copied to the target. The files' info rollrecs must either have the same version or the versions must all be less than the version of the target_rollrec_file.

Upon success, rollrec_merge() returns the number of rollrecs read from the file.

Failure return values:

    -1 no rollrec files were given to rollrec_merge
    -2 unable to create target rollrec file
    -3 unable to read first rollrec file
    -4 an error occurred while reading the rollrec names
    -5 rollrec files were duplicated in the list of rollrec files

rollrec_names()

This routine returns a list of the rollrec names from the file. The name of the info rollrec is not included in this list.

rollrec_read(rollrec_file)

This interface reads the specified rollrec file and parses it into a rollrec hash table and a file-contents array. rollrec_read() must be called prior to any of the other rollrec.pm calls. If another rollrec is already open, it is saved and closed prior to opening the new rollrec.

rollrec_read() attempts to open the rollrec file for reading and writing. If this fails, then it attempts to open the file for reading only.

rollrec_read() is a front-end for rollrec_readfile(). It sets up the module's saved data in preparation for reading a new rollrec file. These house-keeping actions are not performed by rollrec_readfile().

Upon success, rollrec_read() returns the number of rollrecs read from the file.

Failure return values:

    -1 specified rollrec file doesn't exit
    -2 unable to open rollrec file
    -3 duplicate rollrec names in file

rollrec_readfile(rollrec_file_handle,mergeflag)

This interface reads the specified file handle to a rollrec file and parses the file contents into a rollrec hash table and a file-contents array. The hash table and file-contents array are not cleared prior to adding data to them.

The mergeflag argument indicates whether the call will be merging a rollrec file with a previously read rollrec or if it will be reading a fresh rollrec file.

Upon success, rollrec_read() returns zero.

Failure return values:

    -1 duplicate rollrec names in file

rollrec_rectype(rollrec_name,rectype)

Set the type of the specified rollrec record. The file is not written after updating the value, but the internal file-modified flag is set. The value is saved in both %rollrecs and in @rollreclines.

rollrec_name is the name of the rollrec that will be modified. rectype is the new type of the rollrec, which must be either ``roll'' or ``skip''.

Return values:

    0 - failure (invalid record type or rollrec not found)
    1 - success

rollrec_recval(rollrec_name,rollrec_field)

This routine returns the value of a specified field in a given rollrec. rollrec_name is the name of the particular rollrec to consult. rollrec_field is the field name within that rollrec.

For example, the current rollrec file contains the following rollrec.

    roll        "example.com"
                zonefile        "db.example.com"

The call:

    rollrec_recval("example.com","zonefile")

will return the value ``db.example.com''.

rollrec_rename(old_rollrec_name,new_rollrec_name)

This routine renames the rollrec named by old_rollrec_name to new_rollrec_name. The actual effect is to change the name in the roll or skip line to new_rollrec_name. The name is changed in the internal version of the the rollrec file only. The file itself is not changed, but must be saved by calling either rollrec_write(), rollrec_save(), or rollrec_saveas().

old_rollrec_name must be the name of an existing rollrec. Conversely, new_rollrec_name must not name an existing rollrec.

Return values:

     0 - success
    -1 - old_rollrec_name was null or empty
    -2 - new_rollrec_name was null or empty
    -3 - old_rollrec_name is not an existing rollrec
    -4 - new_rollrec_name is already a rollrec
    -5 - internal error that should never happen

rollrec_settime(rollrec_name,val)

Set the phase-start timestamp in the rollrec specified by rollrec_name to the current time. If the optional val parameter is given and it is zero, then the phase-start timestamp is set to a null value.

The file is not written after updating the value.

rollrec_setval(rollrec_name,field,value)

Set the value of a name/field pair in a specified rollrec. The file is not written after updating the value, but the internal file-modified flag is set. The value is saved in both %rollrecs and in @rollreclines.

rollrec_name is the name of the rollrec that will be modified. If the named rollrec does not exist, it will be created as a ``roll''-type rollrec. field is the rollrec field which will be modified. value is the new value for the field.

rollrec_split(new_rollrec_file,rollrec_names)

Move a set of rollrec entries from the current rollrec file to a new file. The moved rollrec entries are removed both from the current file and from the internal module data representing that file.

The new_rollrec_file parameter holds the name of the new rollrec file. If this file doesn't exist, it will be created. If it does exist, the rollrec entries will be appended to that file.

rollrec_names is a list of rollrec entries that will be moved from the current file to the file named in new_rollrec_file. If some of the given rollrec 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 rollrec entries themselves will be moved to the new rollrec file. Any associated comments will be left in the current rollrec file.

rollrec-splitting gets interesting with the addition of the info rollrec. If the new_rollrec_file file doesn't exist, the source rollrec file's info rollrec is copied to the target file. If the file does exist but doesn't have an info rollrec, then then the source's info rollrec is copied to the target. If the target file exists and has an info rollrec, then the two files must have matching version numbers.

On success, the count of moved rollrec entries is returned. Error returns are given below.

Failure return values:
    -1 - no target rollrec file given in new_rollrec_file
    -2 - no rollrec names given in rollrec_names
    -3 - none of the rollrec names given are existing rollrecs
    -4 - unable to open new_rollrec_file
    -5 - invalid rollrec names were specified in rollrec_names,
         followed by the list of bad names
    -6 - target's info rollrec has previous version than current
    -7 - target's info rollrec has (undefined) later version
         than current
    -8 - target's info rollrec exists without version number

rollrec_unlock()

rollrec_unlock() unlocks the rollrec synchronization file.

rollrec_write()

This interface saves the internal version of the rollrec file (opened with rollrec_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 rollrec file, it is not rewritten.

rollrec_write() gets an exclusive lock on the rollrec file while writing.

rollrec_zonegroup($zonegroupname)

This interface returns a list of the zones in the zonegroup (named by $zonegroupname) defined in the current rollrec file. Null is returned if there are no zones in the zonegroup.

While this is using the term ``zone'', it is actually referring to the name of the rollrec entries. For a particular rollrec entry, the rollrec name is usually the same as the zone name, but this is not a requirement.

rollrec_zonegroup_cmds()

This interface returns a list of the rollctl commands whose behavior changes when they are used with the -group option.

rollrec_zonegroups()

This interface returns a hash table of the zonegroups defined in the current rollrec file. The hash key is the name of the zonegroup; the hash value is the number of zones in the zonegroup. Null is returned if there are no zonegroups in the rollrec file.

While this is using the term ``zone'', it is actually referring to the name of the rollrec entries. For a particular rollrec entry, the rollrec name is usually the same as the zone name, but this is not a requirement.

ROLLREC INTERNAL INTERFACES

The interfaces described in this section are intended for internal use by the rollrec.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 rollrec files.

rollrec_init()

This routine initializes the internal rollrec data. Pending changes will be lost. An open rollrec file handle will remain open, though the data are no longer held internally. A new rollrec file must be read in order to use the rollrec.pm interfaces again.

rollrec_default()

This routine returns the name of the default rollrec file.

ROLLREC DEBUGGING INTERFACES

The following interfaces display information about the currently parsed rollrec file. They are intended to be used for debugging and testing, but may be useful at other times.

rollrec_dump_hash()

This routine prints the rollrec file as it is stored internally in a hash table. The rollrecs are printed in alphabetical order, with the fields alphabetized for each rollrec. New rollrecs and rollrec fields are alphabetized along with current rollrecs and fields. Comments from the rollrec file are not included with the hash table.

rollrec_dump_array()

This routine prints the rollrec file as it is stored internally in an array. The rollrecs are printed in the order given in the file, with the fields ordered in the same manner. New rollrecs are appended to the end of the array. rollrec fields added to existing rollrecs are added at the beginning of the rollrec entry. Comments and vertical whitespace are preserved as given in the rollrec file.

COPYRIGHT

Copyright 2006-2014 SPARTA, Inc. All rights reserved. See the COPYING file included with the DNSSEC-Tools package for details.

AUTHOR

Wayne Morrison, [email protected]