Linux Certif

Toute la documentation sur la certification Linux LPI

Net::DNS::SEC::Tools::rollrec.3pm

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_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();
 
   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"
         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"
         # 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 {\it 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.

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_del(rollrec_name)

This routine deletes a rollrec from the rollrec file and the internal representation of the file contents. The rollrec is deleted from both the %rollrecs hash table and the @rollreclines array.

Only the rollrec itself is deleted from the file. Any associated comments and blank lines surrounding it are left intact. The rollrec file is not written after rollrec_del(), though it is internally marked as having been modified.

Return values are:

     0 successful rollrec deletion
 
     -1 unknown name
 
 

rollrec_close()

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

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_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, then 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.

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_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_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_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 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_newrec(type,name)
This interface creates a new rollrec. The rollrec_name field in the rollrec is set to the values of the name parameter. The type parameter must be either ``roll'' or ``skip''.
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-2010 SPARTA, Inc. All rights reserved. See the COPYING file included with the DNSSEC-Tools package for details.

AUTHOR

Wayne Morrison, tewok@users.sourceforge.net

SEE ALSO

lsroll(1), rollchk(8), rollinit(8)

Net::DNS::SEC::Tools::keyrec(3), Net::DNS::SEC::Tools::keyrec(5)

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 1540:

You can't have =items (as at line 1547) unless the first thing after the =over is an =item

Around line 1568:

You can't have =items (as at line 1574) unless the first thing after the =over is an =item