Provided by: dnssec-tools_2.0-1_all 
NAME
Net::DNS::SEC::Tools::rollrec - Manipulate a DNSSEC-Tools rollrec file.
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 "bob@bobhost.example.com"
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-2013 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
lsroll(1), rollchk(8), rollinit(8)
Net::DNS::SEC::Tools::keyrec(3), Net::DNS::SEC::Tools::keyrec(5)