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");
@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 will prevent these blocks from growing excessively.
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_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_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.
Upon success, rollrec_read() 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.
- 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)
- 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.
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.
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.
- 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-2012 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)