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 @rrnames = rollrec_names();
15 $flag = rollrec_exists("example.com");
17 $rrec = rollrec_fullrec("example.com");
19 %rrhash = %$rrec;
20 $zname = $rrhash{"maxttl"};
21 $val = rollrec_recval("example.com","zonefile");
23 rollrec_add("roll","example.com",\%rollfields);
25 rollrec_add("skip","example.com",\%rollfields);
26 rollrec_del("example.com");
28 rollrec_rename("example.com","subdom.example.com");
30 rollrec_type("example.com","roll");
32 rollrec_type("example.com","skip");
33 rollrec_setval("example.com","zonefile","db.example.com");
35 rollrec_delfield("example.com","directory");
37 rollrec_settime("example.com");
39 rollrec_settime("example.com",0);
40 @rollrecfields = rollrec_fields();
42 $default_file = rollrec_default();
44 $count = rollrec_merge("primary.rrf", "new0.rrf", "new1".rrf");
46 @retvals = rollrec_split("new-rollrec.rrf", @rollrec_list);
47 rollrec_write();
49 rollrec_close();
50 rollrec_discard();
51 rollrec_unlock();
53
55 The Net::DNS::SEC::Tools::rollrec module manipulates the contents of a
56 DNSSEC-Tools rollrec file. rollrec files describe the status of a zone
57 rollover process, as performed by the DNSSEC-Tools programs. Module
58 interfaces exist for looking up rollrec records, creating new records,
59 and modifying existing records.
60 A rollrec file is organized in sets of rollrec records. rollrecs
62 describe the state of a rollover operation. A rollrec consists of a
63 set of keyword/value entries. The following is an example of a
64 rollrec:
65 roll "example"
67 zonename "example.com"
68 zonefile "/etc/dnssec-tools/zones/db.example.com"
69 keyrec "/etc/dnssec-tools/keyrec/example.keyrec"
70 directory "/etc/dnssec-tools/dir-example.com"
71 kskphase "0"
72 zskphase "2"
73 maxttl "86400"
74 administrator "bob@bobhost.example.com"
75 phasestart "Wed Mar 09 21:49:22 2005"
76 display "0"
77 loglevel "info"
78 rollrec_rollsecs "1115923362"
79 rollrec_rolldate "Tue Mar 09 19:12:54 2005"
80 curerrors 0
81 maxerrors 5
82 # optional records:
83 istrustanchor "yes"
84 holddowntime "8W"
85 Additionally, commands to be acted upon at start-up can be defined
87 using the "cmd" token as shown in the following example.
88 cmd "rollzsk example.com"
90 Use this feature with caution and only if you understand the internals
92 of rollerd and exactly what will be done by the specified command.
93 The first step in using this module must be to read the rollrec file.
95 The rollrec_read() interface reads the file and parses it into an
96 internal format. The file's records are copied into a hash table (for
97 easy reference by the rollrec.pm routines) and in an array (for
98 preserving formatting and comments.)
99 After the file has been read, the contents are referenced using
101 rollrec_fullrec() and rollrec_recval(). The rollrec_add(),
102 rollrec_setval(), and rollrec_settime() interfaces are used to modify
103 the contents of a {\it rollrec} record.
104 If the rollrec file has been modified, it must be explicitly written or
106 the changes will not saved. rollrec_write() saves the new contents to
107 disk. rollrec_close() saves the file and close the Perl file handle to
108 the rollrec file. If a rollrec file is no longer wanted to be open,
109 yet the contents should not be saved, rollrec_discard() gets rid of the
110 data closes and the file handle without saving any modified data.
111
113 This module includes interfaces for synchronizing access to the rollrec
114 files. This synchronization is very simple and relies upon locking and
115 unlocking a single lock file for all rollrec files.
116 rollrec locking is not required before using this module, but it is
118 recommended. The expected use of these facilities follows:
119 rollrec_lock() || die "unable to lock rollrec file\n";
121 rollrec_read();
122 ... perform other rollrec operations ...
123 rollrec_close();
124 rollrec_unlock();
125 Synchronization is performed in this manner due to the way the module's
127 functionality is implemented, as well as providing flexibility to users
128 of the module. It also provides a clear delineation in callers' code
129 as to where and when rollrec locking is performed.
130 This synchronization method has the disadvantage of having a single
132 lockfile as a bottleneck to all rollrec file access. However, it
133 reduces complexity in the locking interfaces and cuts back on the
134 potential number of required lockfiles.
135 Using a single synchronization file may not be practical in large
137 installations. If that is found to be the case, then this will be
138 reworked.
139
141 The interfaces to the rollrec.pm module are given below.
142 rollrec_add(rollrec_type,rollrec_name,fields)
144 This routine adds a new rollrec to the rollrec file and the
145 internal representation of the file contents. The rollrec is added
146 to both the %rollrecs hash table and the @rollreclines array.
147 Entries are only added if they are defined for rollrecs.
148 rollrec_type is the type of the rollrec. This must be either
150 "roll" or "skip". rollrec_name is the name of the rollrec. fields
151 is a reference to a hash table that contains the name/value rollrec
152 fields. The keys of the hash table are always converted to
153 lowercase, but the entry values are left as given.
154 Timestamp fields are added at the end of the rollrec. These fields
156 have the key values rollrec_gensecs and rollrec_gendate.
157 A blank line is added after the final line of the new rollrec. The
159 rollrec file is not written after rollrec_add(), though it is
160 internally marked as having been modified.
161 rollrec_del(rollrec_name)
163 This routine deletes a rollrec from the rollrec file and the
164 internal representation of the file contents. The rollrec is
165 deleted from both the %rollrecs hash table and the @rollreclines
166 array.
167 Only the rollrec itself is deleted from the file. Any associated
169 comments and blank lines surrounding it are left intact. The
170 rollrec file is not written after rollrec_del(), though it is
171 internally marked as having been modified.
172 Return values are:
174 0 successful rollrec deletion
176 -1 unknown name
177 rollrec_close()
179 This interface saves the internal version of the rollrec file
180 (opened with rollrec_read()) and closes the file handle.
181 rollrec_delfield(rollrec_name,field)
183 Deletes the given field from the specified rollrec. The file is
184 not written after updating the value, but the internal file-
185 modified flag is set. The value is saved in both %rollrecs and in
186 @rollreclines.
187 Return values:
189 0 - failure (rollrec not found or rollrec does not
191 contain the field)
192 1 - success
193 rollrec_discard()
195 This routine removes a rollrec file from use by a program. The
196 internally stored data are deleted and the rollrec file handle is
197 closed. However, modified data are not saved prior to closing the
198 file handle. Thus, modified and new data will be lost.
199 rollrec_exists(rollrec_name)
201 This routine returns a boolean flag indicating if the rollrec named
202 in rollrec_name exists.
203 rollrec_fullrec(rollrec_name)
205 rollrec_fullrec() returns a reference to the rollrec specified in
206 rollrec_name.
207 rollrec_lock()
209 rollrec_lock() locks the rollrec lockfile. An exclusive lock is
210 requested, so the execution will suspend until the lock is
211 available. If the rollrec synchronization file does not exist, it
212 will be created. If the process can't create the synchronization
213 file, an error will be returned. Success or failure is returned.
214 rollrec_merge(target_rollrec_file,rollrec_file2, ... rollrec_fileN)
216 This interface merges the specified rollrec files. It reads each
217 file and parses them into a rollrec hash table and a file-contents
218 array. The resulting merge is written to the file named by
219 target_rollrec_file. If another rollrec is already open, it is
220 saved and closed prior to opening the new rollrec.
221 If target_rollrec_file is an existing rollrec file, its contents
223 will be merged with the other files passed to rollrec_merge(). If
224 the file does not exist, rollrec_merge() will create it and merge
225 the remaining files into it.
226 Upon success, rollrec_read() returns the number of rollrecs read
228 from the file.
229 Failure return values:
231 -1 no rollrec files were given to rollrec_merge
233 -2 unable to create target rollrec file
234 -3 unable to read first rollrec file
235 -4 an error occurred while reading the rollrec names
236 -5 rollrec files were duplicated in the list of rollrec files
237 rollrec_names()
239 This routine returns a list of the rollrec names from the file.
240 rollrec_read(rollrec_file)
242 This interface reads the specified rollrec file and parses it into
243 a rollrec hash table and a file-contents array. rollrec_read()
244 must be called prior to any of the other rollrec.pm calls. If
245 another rollrec is already open, it is saved and closed prior to
246 opening the new rollrec.
247 rollrec_read() attempts to open the rollrec file for reading and
249 writing. If this fails, then it attempts to open the file for
250 reading only.
251 rollrec_read() is a front-end for rollrec_readfile(). It sets up
253 the module's saved data in preparation for reading a new rollrec
254 file. These house-keeping actions are not performed by
255 rollrec_readfile().
256 Upon success, rollrec_read() returns the number of rollrecs read
258 from the file.
259 Failure return values:
261 -1 specified rollrec file doesn't exit
263 -2 unable to open rollrec file
264 -3 duplicate rollrec names in file
265 rollrec_readfile(rollrec_file_handle)
267 This interface reads the specified file handle to a rollrec file
268 and parses the file contents into a rollrec hash table and a file-
269 contents array. The hash table and file-contents array are not
270 cleared prior to adding data to them.
271 Upon success, rollrec_read() returns zero.
273 Failure return values:
275 -1 duplicate rollrec names in file
277 rollrec_rectype(rollrec_name,rectype)
279 Set the type of the specified rollrec record. The file is not
280 written after updating the value, but the internal file-modified
281 flag is set. The value is saved in both %rollrecs and in
282 @rollreclines.
283 rollrec_name is the name of the rollrec that will be modified.
285 rectype is the new type of the rollrec, which must be either "roll"
286 or "skip".
287 Return values:
289 0 - failure (invalid record type or rollrec not found)
291 1 - success
292 rollrec_recval(rollrec_name,rollrec_field)
294 This routine returns the value of a specified field in a given
295 rollrec. rollrec_name is the name of the particular rollrec to
296 consult. rollrec_field is the field name within that rollrec.
297 For example, the current rollrec file contains the following
299 rollrec.
300 roll "example.com"
302 zonefile "db.example.com"
303 The call:
305 rollrec_recval("example.com","zonefile")
307 will return the value "db.example.com".
309 rollrec_rename(old_rollrec_name,new_rollrec_name)
311 This routine renames the rollrec named by old_rollrec_name to
312 new_rollrec_name. The actual effect is to change the name in the
313 roll or skip line is changed to new_rollrec_name. The name is
314 changed in the internal version of the the rollrec file only. The
315 file itself is not changed, but must be saved by calling either
316 rollrec_write(), rollrec_save(), or rollrec_saveas().
317 old_rollrec_name must be the name of an existing rollrec.
319 Conversely, new_rollrec_name must not name an existing rollrec.
320 Return values:
322 0 - success
324 -1 - old_rollrec_name was null or empty
325 -2 - new_rollrec_name was null or empty
326 -3 - old_rollrec_name is not an existing rollrec
327 -4 - new_rollrec_name is already a rollrec
328 -5 - internal error that should never happen
329 rollrec_settime(rollrec_name,val)
331 Set the phase-start timestamp in the rollrec specified by
332 rollrec_name to the current time. If the optional val parameter is
333 given and it is zero, then the phase-start timestamp is set to a
334 null value.
335 The file is not written after updating the value.
337 rollrec_setval(rollrec_name,field,value)
339 Set the value of a name/field pair in a specified rollrec. The
340 file is not written after updating the value, but the internal
341 file-modified flag is set. The value is saved in both %rollrecs
342 and in @rollreclines.
343 rollrec_name is the name of the rollrec that will be modified. If
345 the named rollrec does not exist, it will be created as a
346 "roll"-type rollrec. field is the rollrec field which will be
347 modified. value is the new value for the field.
348 rollrec_split(new_rollrec_file,rollrec_names)
350 Move a set of rollrec entries from the current rollrec file to a
351 new file. The moved rollrec entries are removed both from the
352 current file and from the internal module data representing that
353 file.
354 The new_rollrec_file parameter holds the name of the new rollrec
356 file. If this file doesn't exist, it will be created. If it does
357 exist, the rollrec entries will be appended to that file.
358 rollrec_names is a list of rollrec entries that will be moved from
360 the current file to the file named in new_rollrec_file. If some of
361 the given rollrec names are invalid, the valid names will be moved
362 to the new file and the invalid names will be returned in a list to
363 the caller.
364 On success, the count of moved rollrec entries is returned. Error
366 returns are given below.
367 Failure return values:
369 -1 - no target rollrec file given in new_rollrec_file
370 -2 - no rollrec names given in rollrec_names
371 -3 - none of the rollrec names given are existing rollrecs
372 -4 - unable to open new_rollrec_file
373 -5 - invalid rollrec names were specified in rollrec_names,
374 followed by the list of bad names.
375 rollrec_unlock()
377 rollrec_unlock() unlocks the rollrec synchronization file.
378 rollrec_write()
380 This interface saves the internal version of the rollrec file
381 (opened with rollrec_read()). It does not close the file handle.
382 As an efficiency measure, an internal modification flag is checked
383 prior to writing the file. If the program has not modified the
384 contents of the rollrec file, it is not rewritten.
385 rollrec_write() gets an exclusive lock on the rollrec file while
387 writing.
388
390 The interfaces described in this section are intended for internal use
391 by the rollrec.pm module. However, there are situations where external
392 entities may have need of them. Use with caution, as misuse may result
393 in damaged or lost rollrec files.
394 rollrec_init()
396 This routine initializes the internal rollrec data. Pending
397 changes will be lost. An open rollrec file handle will remain
398 open, though the data are no longer held internally. A new rollrec
399 file must be read in order to use the rollrec.pm interfaces again.
400 rollrec_newrec(type,name)
402 This interface creates a new rollrec. The rollrec_name field in
403 the rollrec is set to the values of the name parameter. The type
404 parameter must be either "roll" or "skip".
405 rollrec_default()
407 This routine returns the name of the default rollrec file.
408
410 The following interfaces display information about the currently parsed
411 rollrec file. They are intended to be used for debugging and testing,
412 but may be useful at other times.
413 rollrec_dump_hash()
415 This routine prints the rollrec file as it is stored internally in
416 a hash table. The rollrecs are printed in alphabetical order, with
417 the fields alphabetized for each rollrec. New rollrecs and rollrec
418 fields are alphabetized along with current rollrecs and fields.
419 Comments from the rollrec file are not included with the hash
420 table.
421 rollrec_dump_array()
423 This routine prints the rollrec file as it is stored internally in
424 an array. The rollrecs are printed in the order given in the file,
425 with the fields ordered in the same manner. New rollrecs are
426 appended to the end of the array. rollrec fields added to existing
427 rollrecs are added at the beginning of the rollrec entry. Comments
428 and vertical whitespace are preserved as given in the rollrec file.
429
431 Copyright 2006-2011 SPARTA, Inc. All rights reserved. See the COPYING
432 file included with the DNSSEC-Tools package for details.
433
435 Wayne Morrison, tewok@users.sourceforge.net
436
438 lsroll(1), rollchk(8), rollinit(8)
439 Net::DNS::SEC::Tools::keyrec(3), Net::DNS::SEC::Tools::keyrec(5)
441perl v5.12.4 2011-08-05 rollrec(3)