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         $valid = rollrec_current();
15         $rrinfo = rollrec_info();
16
17         @rrnames = rollrec_names();
18
19         $flag = rollrec_exists("example.com");
20
21         $rrec = rollrec_fullrec("example.com");
22         %rrhash = %$rrec;
23         $zname = $rrhash{"maxttl"};
24
25         $val = rollrec_recval("example.com","zonefile");
26
27         rollrec_add("roll","example.com",\%rollfields);
28         rollrec_add("skip","example.com",\%rollfields);
29
30         rollrec_del("example.com");
31
32         rollrec_rename("example.com","subdom.example.com");
33
34         rollrec_type("example.com","roll");
35         rollrec_type("example.com","skip");
36
37         rollrec_setval("example.com","zonefile","db.example.com");
38
39         rollrec_delfield("example.com","directory");
40
41         rollrec_settime("example.com");
42         rollrec_settime("example.com",0);
43
44         @rollrecfields = rollrec_fields();
45
46         $default_file = rollrec_default();
47
48         $count = rollrec_merge("primary.rrf", "new0.rrf", "new1.rrf");
49         @retvals = rollrec_split("new-rollrec.rrf", @rollrec_list);
50
51         %zgroups = rollrec_zonegroups();
52         @zgroup = rollrec_zonegroup($zonegroupname);
53         @zgcmds = rollrec_zonegroup_cmds();
54
55         rollrec_write();
56         rollrec_close();
57         rollrec_discard();
58
59         rollrec_unlock();
60

DESCRIPTION

62       The Net::DNS::SEC::Tools::rollrec module manipulates the contents of a
63       DNSSEC-Tools rollrec file.  rollrec files describe the status of a zone
64       rollover process, as performed by the DNSSEC-Tools programs.  Module
65       interfaces exist for looking up rollrec records, creating new records,
66       and modifying existing records.
67
68       A rollrec file is organized in sets of rollrec records.  rollrecs
69       describe the state of a rollover operation.  A rollrec consists of a
70       set of keyword/value entries.  The following is an example of a
71       rollrec:
72
73           roll "example"
74               zonename                "example.com"
75               zonefile                "/etc/dnssec-tools/zones/db.example.com"
76               keyrec                  "/etc/dnssec-tools/keyrec/example.keyrec"
77               zonegroup               "example zones"
78               directory               "/etc/dnssec-tools/dir-example.com"
79               kskphase                "0"
80               zskphase                "2"
81               maxttl                  "86400"
82               administrator           "bob@bobhost.example.com"
83               phasestart              "Wed Mar 09 21:49:22 2005"
84               display                 "0"
85               loglevel                "info"
86               rollrec_rollsecs        "1115923362"
87               rollrec_rolldate        "Tue Mar 09 19:12:54 2005"
88               curerrors               0
89               maxerrors               5
90               # optional records:
91               istrustanchor           "yes"
92               holddowntime            "8W"
93
94       Additionally, commands to be acted upon at start-up can be defined
95       using the "cmd" token as shown in the following example.
96
97           cmd "rollzsk example.com"
98
99       Use this feature with caution and only if you understand the internals
100       of rollerd and exactly what will be done by the specified command.
101
102       The first step in using this module must be to read the rollrec file.
103       The rollrec_read() interface reads the file and parses it into an
104       internal format.  The file's records are copied into a hash table (for
105       easy reference by the rollrec.pm routines) and in an array (for
106       preserving formatting and comments.)
107
108       After the file has been read, the contents are referenced using
109       rollrec_fullrec() and rollrec_recval().  The rollrec_add(),
110       rollrec_setval(), and rollrec_settime() interfaces are used to modify
111       the contents of a rollrec record.
112
113       If the rollrec file has been modified, it must be explicitly written or
114       the changes will not saved.  rollrec_write() saves the new contents to
115       disk.  rollrec_close() saves the file and close the Perl file handle to
116       the rollrec file.  If a rollrec file is no longer wanted to be open,
117       yet the contents should not be saved, rollrec_discard() gets rid of the
118       data closes and the file handle without saving any modified data.
119
120       On reading a rollrec file, consecutive blank lines are collapsed into a
121       single blank line.  As rollrec entries are added and deleted, files
122       merged and files split, it is possible for blocks of consecutive blanks
123       lines to grow.  This blank-line collapsing will prevent these blocks
124       from growing excessively.
125
126       There is a special rollrec called the info rollrec.  It contains
127       information about the rollrec file, such as the version of rollrecs
128       stored within the file.  It is only accessible through the
129       rollrec_info() interface, and the rollrec_current() interface will
130       indicate if the file's version number is current.
131

ROLLREC LOCKING

133       This module includes interfaces for synchronizing access to the rollrec
134       files.  This synchronization is very simple and relies upon locking and
135       unlocking a single lock file for all rollrec files.
136
137       rollrec locking is not required before using this module, but it is
138       recommended.  The expected use of these facilities follows:
139
140           rollrec_lock() || die "unable to lock rollrec file\n";
141           rollrec_read();
142           ... perform other rollrec operations ...
143           rollrec_close();
144           rollrec_unlock();
145
146       Synchronization is performed in this manner due to the way the module's
147       functionality is implemented, as well as providing flexibility to users
148       of the module.  It also provides a clear delineation in callers' code
149       as to where and when rollrec locking is performed.
150
151       This synchronization method has the disadvantage of having a single
152       lockfile as a bottleneck to all rollrec file access.  However, it
153       reduces complexity in the locking interfaces and cuts back on the
154       potential number of required lockfiles.
155
156       Using a single synchronization file may not be practical in large
157       installations.  If that is found to be the case, then this will be
158       reworked.
159

ROLLREC INTERFACES

161       The interfaces to the rollrec.pm module are given below.
162
163       rollrec_add(rollrec_type,rollrec_name,fields)
164           This routine adds a new rollrec to the rollrec file and the
165           internal representation of the file contents.  The rollrec is added
166           to both the %rollrecs hash table and the @rollreclines array.
167           Entries are only added if they are defined for rollrecs.
168
169           rollrec_type is the type of the rollrec.  This must be either
170           "roll" or "skip".  rollrec_name is the name of the rollrec.  fields
171           is a reference to a hash table that contains the name/value rollrec
172           fields.  The keys of the hash table are always converted to
173           lowercase, but the entry values are left as given.
174
175           Timestamp fields are added at the end of the rollrec.  These fields
176           have the key values rollrec_gensecs and rollrec_gendate.
177
178           A blank line is added after the final line of the new rollrec.  The
179           rollrec file is not written after rollrec_add(), though it is
180           internally marked as having been modified.
181
182       rollrec_close()
183           This interface saves the internal version of the rollrec file
184           (opened with rollrec_read()) and closes the file handle.
185
186       rollrec_current()
187           This routine returns a boolean indicating if this open rollrec is
188           current, as defined by the version number in the info rollrec.
189           Versions 0, 1, and 2 are considered to be equivalent.
190
191           Return values are:
192
193               1 rollrec is current
194               0 rollrec is obsolete
195               0 rollrec has an invalid version
196
197           The last condition shouldn't ever happen and it could be argued
198           that a failure value should be returned.  However, an easy two-
199           value boolean function was wanted, not a three-value function.
200
201       rollrec_del(rollrec_name)
202           This routine deletes a rollrec from the set of rollrecs loaded into
203           memory by the rollrec.pm module.  The rollrec is deleted from both
204           the %rollrecs hash table and the @rollreclines array.
205
206           The rollrec file is not written after rollrec_del(), though the
207           collection of rollrecs is internally marked as having been
208           modified.
209
210           Only the rollrec itself is deleted.  Any associated comments and
211           blank lines surrounding it are left intact.
212
213           Return values are:
214
215                0 successful rollrec deletion
216               -1 unknown name
217
218       rollrec_delfield(rollrec_name,field)
219           Deletes the given field from the specified rollrec.  The file is
220           not written after updating the value, but the internal file-
221           modified flag is set.  The value is saved in both %rollrecs and in
222           @rollreclines.
223
224           Return values:
225
226               0 - failure (rollrec not found or rollrec does not
227                   contain the field)
228               1 - success
229
230       rollrec_discard()
231           This routine removes a rollrec file from use by a program.  The
232           internally stored data are deleted and the rollrec file handle is
233           closed.  However, modified data are not saved prior to closing the
234           file handle.  Thus, modified and new data will be lost.
235
236       rollrec_exists(rollrec_name)
237           This routine returns a boolean flag indicating if the rollrec named
238           in rollrec_name exists.
239
240       rollrec_fullrec(rollrec_name)
241           rollrec_fullrec() returns a reference to the rollrec specified in
242           rollrec_name.
243
244       rollrec_info()
245           rollrec_info() returns a reference to the info rollrec given in the
246           current file.  This interface is the only way for a calling program
247           to retrieve this information.
248
249       rollrec_lock()
250           rollrec_lock() locks the rollrec lockfile.  An exclusive lock is
251           requested, so the execution will suspend until the lock is
252           available.  If the rollrec synchronization file does not exist, it
253           will be created.  If the process can't create the synchronization
254           file, an error will be returned.  Success or failure is returned.
255
256       rollrec_merge(target_rollrec_file, rollrec_file1, ... rollrec_fileN)
257           This interface merges the specified rollrec files.  It reads each
258           file and parses them into a rollrec hash table and a file-contents
259           array.  The resulting merge is written to the file named by
260           target_rollrec_file.  If another rollrec is already open, it is
261           saved and closed prior to opening the new rollrec.
262
263           If target_rollrec_file is an existing rollrec file, its contents
264           will be merged with the other files passed to rollrec_merge().  If
265           the file does not exist, rollrec_merge() will create it and merge
266           the remaining files into it.
267
268           The info rollrec can affect how the merging will work.  If the
269           target_rollrec_file is doesn't exist or is empty, then a simple
270           info rollrec will be added to the file.  No part of the info
271           rollrecs will be merged into that of the target_rollrec_file.
272
273           If the file does exist but doesn't have an info rollrec rollrec,
274           then then the source's info rollrec is copied to the target.  The
275           files' info rollrecs must either have the same version or the
276           versions must all be less than the version of the
277           target_rollrec_file.
278
279           Upon success, rollrec_merge() returns the number of rollrecs read
280           from the file.
281
282           Failure return values:
283
284               -1 no rollrec files were given to rollrec_merge
285               -2 unable to create target rollrec file
286               -3 unable to read first rollrec file
287               -4 an error occurred while reading the rollrec names
288               -5 rollrec files were duplicated in the list of rollrec files
289
290       rollrec_names()
291           This routine returns a list of the rollrec names from the file.
292           The name of the info rollrec is not included in this list.
293
294       rollrec_read(rollrec_file)
295           This interface reads the specified rollrec file and parses it into
296           a rollrec hash table and a file-contents array.  rollrec_read()
297           must be called prior to any of the other rollrec.pm calls.  If
298           another rollrec is already open, it is saved and closed prior to
299           opening the new rollrec.
300
301           rollrec_read() attempts to open the rollrec file for reading and
302           writing.  If this fails, then it attempts to open the file for
303           reading only.
304
305           rollrec_read() is a front-end for rollrec_readfile().  It sets up
306           the module's saved data in preparation for reading a new rollrec
307           file.  These house-keeping actions are not performed by
308           rollrec_readfile().
309
310           Upon success, rollrec_read() returns the number of rollrecs read
311           from the file.
312
313           Failure return values:
314
315               -1 specified rollrec file doesn't exit
316               -2 unable to open rollrec file
317               -3 duplicate rollrec names in file
318
319       rollrec_readfile(rollrec_file_handle,mergeflag)
320           This interface reads the specified file handle to a rollrec file
321           and parses the file contents into a rollrec hash table and a file-
322           contents array.  The hash table and file-contents array are not
323           cleared prior to adding data to them.
324
325           The mergeflag argument indicates whether the call will be merging a
326           rollrec file with a previously read rollrec or if it will be
327           reading a fresh rollrec file.
328
329           Upon success, rollrec_read() returns zero.
330
331           Failure return values:
332
333               -1 duplicate rollrec names in file
334
335       rollrec_rectype(rollrec_name,rectype)
336           Set the type of the specified rollrec record.  The file is not
337           written after updating the value, but the internal file-modified
338           flag is set.  The value is saved in both %rollrecs and in
339           @rollreclines.
340
341           rollrec_name is the name of the rollrec that will be modified.
342           rectype is the new type of the rollrec, which must be either "roll"
343           or "skip".
344
345           Return values:
346
347               0 - failure (invalid record type or rollrec not found)
348               1 - success
349
350       rollrec_recval(rollrec_name,rollrec_field)
351           This routine returns the value of a specified field in a given
352           rollrec.  rollrec_name is the name of the particular rollrec to
353           consult.  rollrec_field is the field name within that rollrec.
354
355           For example, the current rollrec file contains the following
356           rollrec.
357
358               roll        "example.com"
359                           zonefile        "db.example.com"
360
361           The call:
362
363               rollrec_recval("example.com","zonefile")
364
365           will return the value "db.example.com".
366
367       rollrec_rename(old_rollrec_name,new_rollrec_name)
368           This routine renames the rollrec named by old_rollrec_name to
369           new_rollrec_name.  The actual effect is to change the name in the
370           roll or skip line to new_rollrec_name.  The name is changed in the
371           internal version of the the rollrec file only.  The file itself is
372           not changed, but must be saved by calling either rollrec_write(),
373           rollrec_save(), or rollrec_saveas().
374
375           old_rollrec_name must be the name of an existing rollrec.
376           Conversely, new_rollrec_name must not name an existing rollrec.
377
378           Return values:
379
380                0 - success
381               -1 - old_rollrec_name was null or empty
382               -2 - new_rollrec_name was null or empty
383               -3 - old_rollrec_name is not an existing rollrec
384               -4 - new_rollrec_name is already a rollrec
385               -5 - internal error that should never happen
386
387       rollrec_settime(rollrec_name,val)
388           Set the phase-start timestamp in the rollrec specified by
389           rollrec_name to the current time.  If the optional val parameter is
390           given and it is zero, then the phase-start timestamp is set to a
391           null value.
392
393           The file is not written after updating the value.
394
395       rollrec_setval(rollrec_name,field,value)
396           Set the value of a name/field pair in a specified rollrec.  The
397           file is not written after updating the value, but the internal
398           file-modified flag is set.  The value is saved in both %rollrecs
399           and in @rollreclines.
400
401           rollrec_name is the name of the rollrec that will be modified.  If
402           the named rollrec does not exist, it will be created as a
403           "roll"-type rollrec.  field is the rollrec field which will be
404           modified.  value is the new value for the field.
405
406       rollrec_split(new_rollrec_file,rollrec_names)
407           Move a set of rollrec entries from the current rollrec file to a
408           new file.  The moved rollrec entries are removed both from the
409           current file and from the internal module data representing that
410           file.
411
412           The new_rollrec_file parameter holds the name of the new rollrec
413           file.  If this file doesn't exist, it will be created.  If it does
414           exist, the rollrec entries will be appended to that file.
415
416           rollrec_names is a list of rollrec entries that will be moved from
417           the current file to the file named in new_rollrec_file.  If some of
418           the given rollrec names are invalid, the valid names will be moved
419           to the new file and the invalid names will be returned in a list to
420           the caller.
421
422           Only the rollrec entries themselves will be moved to the new
423           rollrec file.  Any associated comments will be left in the current
424           rollrec file.
425
426           rollrec-splitting gets interesting with the addition of the info
427           rollrec.  If the new_rollrec_file file doesn't exist, the source
428           rollrec file's info rollrec is copied to the target file.  If the
429           file does exist but doesn't have an info rollrec, then then the
430           source's info rollrec is copied to the target.  If the target file
431           exists and has an info rollrec, then the two files must have
432           matching version numbers.
433
434           On success, the count of moved rollrec entries is returned.  Error
435           returns are given below.
436
437           Failure return values:
438               -1 - no target rollrec file given in new_rollrec_file
439               -2 - no rollrec names given in rollrec_names
440               -3 - none of the rollrec names given are existing rollrecs
441               -4 - unable to open new_rollrec_file
442               -5 - invalid rollrec names were specified in rollrec_names,
443                    followed by the list of bad names
444               -6 - target's info rollrec has previous version than current
445               -7 - target's info rollrec has (undefined) later version
446                    than current
447               -8 - target's info rollrec exists without version number
448
449       rollrec_unlock()
450           rollrec_unlock() unlocks the rollrec synchronization file.
451
452       rollrec_write()
453           This interface saves the internal version of the rollrec file
454           (opened with rollrec_read()).  It does not close the file handle.
455           As an efficiency measure, an internal modification flag is checked
456           prior to writing the file.  If the program has not modified the
457           contents of the rollrec file, it is not rewritten.
458
459           rollrec_write() gets an exclusive lock on the rollrec file while
460           writing.
461
462       rollrec_zonegroup($zonegroupname)
463           This interface returns a list of the zones in the zonegroup (named
464           by $zonegroupname) defined in the current rollrec file.  Null is
465           returned if there are no zones in the zonegroup.
466
467           While this is using the term "zone", it is actually referring to
468           the name of the rollrec entries.  For a particular rollrec entry,
469           the rollrec name is usually the same as the zone name, but this is
470           not a requirement.
471
472       rollrec_zonegroup_cmds()
473           This interface returns a list of the rollctl commands whose
474           behavior changes when they are used with the -group option.
475
476       rollrec_zonegroups()
477           This interface returns a hash table of the zonegroups defined in
478           the current rollrec file.  The hash key is the name of the
479           zonegroup; the hash value is the number of zones in the zonegroup.
480           Null is returned if there are no zonegroups in the rollrec file.
481
482           While this is using the term "zone", it is actually referring to
483           the name of the rollrec entries.  For a particular rollrec entry,
484           the rollrec name is usually the same as the zone name, but this is
485           not a requirement.
486

ROLLREC INTERNAL INTERFACES

488       The interfaces described in this section are intended for internal use
489       by the rollrec.pm module.  However, there are situations where external
490       entities may have need of them.  Use with caution, as misuse may result
491       in damaged or lost rollrec files.
492
493       rollrec_init()
494           This routine initializes the internal rollrec data.  Pending
495           changes will be lost.  An open rollrec file handle will remain
496           open, though the data are no longer held internally.  A new rollrec
497           file must be read in order to use the rollrec.pm interfaces again.
498
499       rollrec_default()
500           This routine returns the name of the default rollrec file.
501

ROLLREC DEBUGGING INTERFACES

503       The following interfaces display information about the currently parsed
504       rollrec file.  They are intended to be used for debugging and testing,
505       but may be useful at other times.
506
507       rollrec_dump_hash()
508           This routine prints the rollrec file as it is stored internally in
509           a hash table.  The rollrecs are printed in alphabetical order, with
510           the fields alphabetized for each rollrec.  New rollrecs and rollrec
511           fields are alphabetized along with current rollrecs and fields.
512           Comments from the rollrec file are not included with the hash
513           table.
514
515       rollrec_dump_array()
516           This routine prints the rollrec file as it is stored internally in
517           an array.  The rollrecs are printed in the order given in the file,
518           with the fields ordered in the same manner.  New rollrecs are
519           appended to the end of the array.  rollrec fields added to existing
520           rollrecs are added at the beginning of the rollrec entry.  Comments
521           and vertical whitespace are preserved as given in the rollrec file.
522
524       Copyright 2006-2014 SPARTA, Inc.  All rights reserved.  See the COPYING
525       file included with the DNSSEC-Tools package for details.
526

AUTHOR

528       Wayne Morrison, tewok@tislabs.com
529

SEE ALSO

531       lsroll(1), rollchk(8), rollinit(8)
532
533       Net::DNS::SEC::Tools::keyrec(3), Net::DNS::SEC::Tools::keyrec(5)
534
535
536
537perl v5.34.0                      2022-01-20                        rollrec(3)
Impressum