1rollrec(3) User Contributed Perl Documentation rollrec(3)
2
6 Net::DNS::SEC::Tools::rollrec - Manipulate a DNSSEC-Tools rollrec file.
7
9 use Net::DNS::SEC::Tools::rollrec;
10 rollrec_lock();
12 rollrec_read("localhost.rollrec");
13 $valid = rollrec_current();
15 $rrinfo = rollrec_info();
16 @rrnames = rollrec_names();
18 $flag = rollrec_exists("example.com");
20 $rrec = rollrec_fullrec("example.com");
22 %rrhash = %$rrec;
23 $zname = $rrhash{"maxttl"};
24 $val = rollrec_recval("example.com","zonefile");
26 rollrec_add("roll","example.com",\%rollfields);
28 rollrec_add("skip","example.com",\%rollfields);
29 rollrec_del("example.com");
31 rollrec_rename("example.com","subdom.example.com");
33 rollrec_type("example.com","roll");
35 rollrec_type("example.com","skip");
36 rollrec_setval("example.com","zonefile","db.example.com");
38 rollrec_delfield("example.com","directory");
40 rollrec_settime("example.com");
42 rollrec_settime("example.com",0);
43 @rollrecfields = rollrec_fields();
45 $default_file = rollrec_default();
47 $count = rollrec_merge("primary.rrf", "new0.rrf", "new1.rrf");
49 @retvals = rollrec_split("new-rollrec.rrf", @rollrec_list);
50 %zgroups = rollrec_zonegroups();
52 @zgroup = rollrec_zonegroup($zonegroupname);
53 @zgcmds = rollrec_zonegroup_cmds();
54 rollrec_write();
56 rollrec_close();
57 rollrec_discard();
58 rollrec_unlock();
60
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 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 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 Additionally, commands to be acted upon at start-up can be defined
95 using the "cmd" token as shown in the following example.
96 cmd "rollzsk example.com"
98 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 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 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 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 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 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
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 rollrec locking is not required before using this module, but it is
138 recommended. The expected use of these facilities follows:
139 rollrec_lock() || die "unable to lock rollrec file\n";
141 rollrec_read();
142 ... perform other rollrec operations ...
143 rollrec_close();
144 rollrec_unlock();
145 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 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 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
161 The interfaces to the rollrec.pm module are given below.
162 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 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 Timestamp fields are added at the end of the rollrec. These fields
176 have the key values rollrec_gensecs and rollrec_gendate.
177 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 rollrec_close()
183 This interface saves the internal version of the rollrec file
184 (opened with rollrec_read()) and closes the file handle.
185 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 Return values are:
192 1 rollrec is current
194 0 rollrec is obsolete
195 0 rollrec has an invalid version
196 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 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 The rollrec file is not written after rollrec_del(), though the
207 collection of rollrecs is internally marked as having been
208 modified.
209 Only the rollrec itself is deleted. Any associated comments and
211 blank lines surrounding it are left intact.
212 Return values are:
214 0 successful rollrec deletion
216 -1 unknown name
217 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 Return values:
225 0 - failure (rollrec not found or rollrec does not
227 contain the field)
228 1 - success
229 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 rollrec_exists(rollrec_name)
237 This routine returns a boolean flag indicating if the rollrec named
238 in rollrec_name exists.
239 rollrec_fullrec(rollrec_name)
241 rollrec_fullrec() returns a reference to the rollrec specified in
242 rollrec_name.
243 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 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 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 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 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 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 Upon success, rollrec_merge() returns the number of rollrecs read
280 from the file.
281 Failure return values:
283 -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 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 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 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 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 Upon success, rollrec_read() returns the number of rollrecs read
311 from the file.
312 Failure return values:
314 -1 specified rollrec file doesn't exit
316 -2 unable to open rollrec file
317 -3 duplicate rollrec names in file
318 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 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 Upon success, rollrec_read() returns zero.
330 Failure return values:
332 -1 duplicate rollrec names in file
334 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 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 Return values:
346 0 - failure (invalid record type or rollrec not found)
348 1 - success
349 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 For example, the current rollrec file contains the following
356 rollrec.
357 roll "example.com"
359 zonefile "db.example.com"
360 The call:
362 rollrec_recval("example.com","zonefile")
364 will return the value "db.example.com".
366 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 old_rollrec_name must be the name of an existing rollrec.
376 Conversely, new_rollrec_name must not name an existing rollrec.
377 Return values:
379 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 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 The file is not written after updating the value.
394 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 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 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 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 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 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 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 On success, the count of moved rollrec entries is returned. Error
435 returns are given below.
436 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 rollrec_unlock()
450 rollrec_unlock() unlocks the rollrec synchronization file.
451 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 rollrec_write() gets an exclusive lock on the rollrec file while
460 writing.
461 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 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 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 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 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
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 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 rollrec_default()
500 This routine returns the name of the default rollrec file.
501
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 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 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
528 Wayne Morrison, tewok@tislabs.com
529
531 lsroll(1), rollchk(8), rollinit(8)
532 Net::DNS::SEC::Tools::keyrec(3), Net::DNS::SEC::Tools::keyrec(5)
534perl v5.34.0 2022-01-20 rollrec(3)