Net::DNS::SEC::Tools::rollrec(3pm)

1rollrec(3)            User Contributed Perl Documentation           rollrec(3)
2
3
4

NAME

6       Net::DNS::SEC::Tools::rollrec - Manipulate a DNSSEC-Tools rollrec file.
7

SYNOPSIS

9         use Net::DNS::SEC::Tools::rollrec;
10
11         rollrec_lock();
12         rollrec_read("localhost.rollrec");
13
14         @rrnames = rollrec_names();
15
16         $flag = rollrec_exists("example.com");
17
18         $rrec = rollrec_fullrec("example.com");
19         %rrhash = %$rrec;
20         $zname = $rrhash{"maxttl"};
21
22         $val = rollrec_recval("example.com","zonefile");
23
24         rollrec_add("roll","example.com",\%rollfields);
25         rollrec_add("skip","example.com",\%rollfields);
26
27         rollrec_del("example.com");
28
29         rollrec_type("example.com","roll");
30         rollrec_type("example.com","skip");
31
32         rollrec_setval("example.com","zonefile","db.example.com");
33
34         rollrec_delfield("example.com","directory");
35
36         rollrec_settime("example.com");
37         rollrec_settime("example.com",0);
38
39         @rollrecfields = rollrec_fields();
40
41         $default_file = rollrec_default();
42
43         rollrec_write();
44         rollrec_close();
45         rollrec_discard();
46
47         rollrec_unlock();
48

DESCRIPTION

50       The Net::DNS::SEC::Tools::rollrec module manipulates the contents of a
51       DNSSEC-Tools rollrec file.  rollrec files describe the status of a zone
52       rollover process, as performed by the DNSSEC-Tools programs.  Module
53       interfaces exist for looking up rollrec records, creating new records,
54       and modifying existing records.
55
56       A rollrec file is organized in sets of rollrec records.  rollrecs
57       describe the state of a rollover operation.  A rollrec consists of a
58       set of keyword/value entries.  The following is an example of a roll‐
59       rec:
60
61           roll "example.com"
62               zonefile                "/usr/etc/dnssec-tools/zones/db.example.com"
63               keyrec                  "/usr/etc/dnssec-tools/keyrec/example.keyrec"
64               directory               "/usr/etc/dnssec-tools/dir-example.com"
65               kskphase                "0"
66               zskphase                "2"
67               maxttl                  "86400"
68               administrator           "bob@bobhost.example.com"
69               phasestart              "Wed Mar 09 21:49:22 2005"
70               display                 "0"
71               loglevel                "info"
72               rollrec_rollsecs        "1115923362"
73               rollrec_rolldate        "Tue Mar 09 19:12:54 2005"
74
75       The first step in using this module must be to read the rollrec file.
76       The rollrec_read() interface reads the file and parses it into an
77       internal format.  The file's records are copied into a hash table (for
78       easy reference by the rollrec.pm routines) and in an array (for pre‐
79       serving formatting and comments.)
80
81       After the file has been read, the contents are referenced using roll‐
82       rec_fullrec() and rollrec_recval().  The rollrec_add(), rollrec_set‐
83       val(), and rollrec_settime() interfaces are used to modify the contents
84       of a {\it rollrec} record.
85
86       If the rollrec file has been modified, it must be explicitly written or
87       the changes will not saved.  rollrec_write() saves the new contents to
88       disk.  rollrec_close() saves the file and close the Perl file handle to
89       the rollrec file.  If a rollrec file is no longer wanted to be open,
90       yet the contents should not be saved, rollrec_discard() gets rid of the
91       data closes and the file handle without saving any modified data.
92

ROLLREC LOCKING

94       This module includes interfaces for synchronizing access to the rollrec
95       files.  This synchronization is very simple and relies upon locking and
96       unlocking a single lock file for all rollrec files.
97
98       rollrec locking is not required before using this module, but it is
99       recommended.  The expected use of these facilities follows:
100
101           rollrec_lock() ⎪⎪ die "unable to lock rollrec file\n";
102           rollrec_read();
103           ... perform other rollrec operations ...
104           rollrec_close();
105           rollrec_unlock();
106
107       Synchronization is performed in this manner due to the way the module's
108       functionality is implemented, as well as providing flexibility to users
109       of the module.  It also provides a clear delineation in callers' code
110       as to where and when rollrec locking is performed.
111
112       This synchronization method has the disadvantage of having a single
113       lockfile as a bottleneck to all rollrec file access.  However, it
114       reduces complexity in the locking interfaces and cuts back on the
115       potential number of required lockfiles.
116
117       Using a single synchronization file may not be practical in large
118       installations.  If that is found to be the case, then this will be
119       reworked.
120

ROLLREC INTERFACES

122       The interfaces to the rollrec.pm module are given below.
123
124       rollrec_add(rollrec_type,rollrec_name,fields)
125           This routine adds a new rollrec to the rollrec file and the inter‐
126           nal representation of the file contents.  The rollrec is added to
127           both the %rollrecs hash table and the @rollreclines array.  Entries
128           are only added if they are defined for rollrecs.
129
130           rollrec_type is the type of the rollrec.  This must be either
131           "roll" or "skip".  rollrec_name is the name of the rollrec.  fields
132           is a reference to a hash table that contains the name/value rollrec
133           fields.  The keys of the hash table are always converted to lower‐
134           case, but the entry values are left as given.
135
136           Timestamp fields are added at the end of the rollrec.  These fields
137           have the key values rollrec_gensecs and rollrec_gendate.
138
139           A blank line is added after the final line of the new rollrec.  The
140           rollrec file is not written after rollrec_add(), though it is
141           internally marked as having been modified.
142
143       rollrec_del(rollrec_name)
144           This routine deletes a rollrec from the rollrec file and the inter‐
145           nal representation of the file contents.  The rollrec is deleted
146           from both the %rollrecs hash table and the @rollreclines array.
147
148           Only the rollrec itself is deleted from the file.  Any associated
149           comments and blank lines surrounding it are left intact.  The roll‐
150           rec file is not written after rollrec_del(), though it is inter‐
151           nally marked as having been modified.
152
153           Return values are:
154
155               0 successful rollrec deletion
156
157               -1 unknown name
158
159       rollrec_close()
160           This interface saves the internal version of the rollrec file
161           (opened with rollrec_read()) and closes the file handle.
162
163       rollrec_delfield(rollrec_name,field)
164           Deletes the given field from the specified rollrec.  The file is
165           not written after updating the value, but the internal file-modi‐
166           fied flag is set.  The value is saved in both %rollrecs and in
167           @rollreclines.
168
169           Return values:
170
171               0 - failure (rollrec not found or rollrec does not
172                   contain the field)
173               1 - success
174
175       rollrec_discard()
176           This routine removes a rollrec file from use by a program.  The
177           internally stored data are deleted and the rollrec file handle is
178           closed.  However, modified data are not saved prior to closing the
179           file handle.  Thus, modified and new data will be lost.
180
181       rollrec_exists(rollrec_name)
182           This routine returns a boolean flag indicating if the rollrec named
183           in rollrec_name exists.
184
185       rollrec_fullrec(rollrec_name)
186           rollrec_fullrec() returns a reference to the rollrec specified in
187           rollrec_name.
188
189       rollrec_lock()
190           rollrec_lock() locks the rollrec lockfile.  An exclusive lock is
191           requested, so the execution will suspend until the lock is avail‐
192           able.  If the rollrec synchronization file does not exist, it will
193           be created.  If the process can't create the synchronization file,
194           an error will be returned.  Success or failure is returned.
195
196       rollrec_names()
197           This routine returns a list of the rollrec names from the file.
198
199       rollrec_read(rollrec_file)
200           This interface reads the specified rollrec file and parses it into
201           a rollrec hash table and a file contents array.  rollrec_read()
202           must be called prior to any of the other rollrec.pm calls.  If
203           another rollrec is already open, then it is saved and closed prior
204           to opening the new rollrec.
205
206           rollrec_read() attempts to open the rollrec file for reading and
207           writing.  If this fails, then it attempts to open the file for
208           reading only.
209
210           Upon success, rollrec_read() returns the number of rollrecs read
211           from the file.
212
213           Failure return values:
214
215               -1 specified rollrec file doesn't exit
216
217               -2 unable to open rollrec file
218
219               -3 duplicate rollrec names in file
220
221       rollrec_rectype(rollrec_name,rectype)
222           Set the type of the specified rollrec record.  The file is not
223           written after updating the value, but the internal file-modified
224           flag is set.  The value is saved in both %rollrecs and in @rollre‐
225           clines.
226
227           rollrec_name is the name of the rollrec that will be modified.
228           rectype is the new type of the rollrec, which must be either "roll"
229           or "skip".
230
231           Return values:
232
233               0 - failure (invalid record type or rollrec not found)
234               1 - success
235
236       rollrec_recval(rollrec_name,rollrec_field)
237           This routine returns the value of a specified field in a given
238           rollrec.  rollrec_name is the name of the particular rollrec to
239           consult.  rollrec_field is the field name within that rollrec.
240
241           For example, the current rollrec file contains the following roll‐
242           rec.
243
244               roll        "example.com"
245                           zonefile        "db.example.com"
246
247           The call:
248
249               rollrec_recval("example.com","zonefile")
250
251           will return the value "db.example.com".
252
253       rollrec_settime(rollrec_name,val)
254           Set the phase-start timestamp in the rollrec specified by roll‐
255           rec_name to the current time.  If the optional val parameter is
256           given and it is zero, then the phase-start timestamp is set to a
257           null value.
258
259           The file is not written after updating the value.
260
261       rollrec_setval(rollrec_name,field,value)
262           Set the value of a name/field pair in a specified rollrec.  The
263           file is not written after updating the value, but the internal
264           file-modified flag is set.  The value is saved in both %rollrecs
265           and in @rollreclines.
266
267           rollrec_name is the name of the rollrec that will be modified.  If
268           the named rollrec does not exist, it will be created as a
269           "roll"-type rollrec.  field is the rollrec field which will be mod‐
270           ified.  value is the new value for the field.
271
272       rollrec_unlock()
273           rollrec_unlock() unlocks the rollrec synchronization file.
274
275       rollrec_write()
276           This interface saves the internal version of the rollrec file
277           (opened with rollrec_read()).  It does not close the file handle.
278           As an efficiency measure, an internal modification flag is checked
279           prior to writing the file.  If the program has not modified the
280           contents of the rollrec file, it is not rewritten.
281

ROLLREC INTERNAL INTERFACES

283           The interfaces described in this section are intended for internal
284           use by the rollrec.pm module.  However, there are situations where
285           external entities may have need of them.  Use with caution, as mis‐
286           use may result in damaged or lost rollrec files.
287
288       rollrec_init()
289           This routine initializes the internal rollrec data.  Pending
290           changes will be lost.  An open rollrec file handle will remain
291           open, though the data are no longer held internally.  A new rollrec
292           file must be read in order to use the rollrec.pm interfaces again.
293
294       rollrec_newrec(type,name)
295           This interface creates a new rollrec.  The rollrec_name field in
296           the rollrec is set to the values of the name parameter.  The type
297           parameter must be either "roll" or "skip".
298
299       rollrec_default()
300           This routine returns the name of the default rollrec file.
301

ROLLREC DEBUGGING INTERFACES

303           The following interfaces display information about the currently
304           parsed rollrec file.  They are intended to be used for debugging
305           and testing, but may be useful at other times.
306
307       rollrec_dump_hash()
308           This routine prints the rollrec file as it is stored internally in
309           a hash table.  The rollrecs are printed in alphabetical order, with
310           the fields alphabetized for each rollrec.  New rollrecs and rollrec
311           fields are alphabetized along with current rollrecs and fields.
312           Comments from the rollrec file are not included with the hash ta‐
313           ble.
314
315       rollrec_dump_array()
316           This routine prints the rollrec file as it is stored internally in
317           an array.  The rollrecs are printed in the order given in the file,
318           with the fields ordered in the same manner.  New rollrecs are
319           appended to the end of the array.  rollrec fields added to existing
320           rollrecs are added at the beginning of the rollrec entry.  Comments
321           and vertical whitespace are preserved as given in the rollrec file.
322

COPYRIGHT

324       Copyright 2004-2007 SPARTA, Inc.  All rights reserved.  See the COPYING
325       file included with the DNSSEC-Tools package for details.
326

AUTHOR

328       Wayne Morrison, tewok@users.sourceforge.net
329