Ubuntu Manpage: Net::DNS::SEC::Tools::rollrec - Manipulate a DNSSEC-Tools rollrec file.

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.

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, tewok@tislabs.com

NAME

SYNOPSIS

DESCRIPTION

ROLLREC LOCKING

ROLLREC INTERFACES

ROLLREC INTERNAL INTERFACES

ROLLREC DEBUGGING INTERFACES

COPYRIGHT

AUTHOR

SEE ALSO