1realm(3) User Contributed Perl Documentation realm(3)
2
6 Net::DNS::SEC::Tools::realm - Manipulate a DNSSEC-Tools realm file.
7
9 use Net::DNS::SEC::Tools::realm;
10 realm_lock();
12 realm_read("localhost.realm");
13 @rlmnames = realm_names();
15 $flag = realm_exists("example");
17 $rrec = realm_fullrec("example");
19 %rrhash = %$rrec;
20 $zname = $rrhash{"maxttl"};
21 $val = realm_recval("example","state");
23 realm_add("realm","example",\%realmfields);
25 realm_del("example");
27 realm_rename("example","test-realm");
29 realm_setval("example","rollrec","example.rrf");
31 realm_delfield("example","user");
33 @realmfields = realm_fields();
35 $count = realmrec_merge("primary.realm", "new0.realm", "new1.realm");
37 @retvals = realmrec_split("new-realm.rrf", @list_of_realms);
38 $default_file = realm_default();
41 realm_write();
43 realm_close();
44 realm_discard();
45 realm_unlock();
47
49 The Net::DNS::SEC::Tools::realm module manipulates the contents of a
50 DNSSEC-Tools realm file. realm files describe the status of a zone
51 rollover environment, as managed by the DNSSEC-Tools programs. Module
52 interfaces exist for looking up realm records, creating new records,
53 and modifying existing records.
54 A realm file is organized in sets of realm records. realms describe
56 the state of a rollover environment. A realm consists of a set of
57 keyword/value entries. The following is an example of a realm:
58 realm "production"
60 state "active"
61 realmdir "/usr/etc/dnssec-tools/realms/production"
62 configdir "/usr/etc/dnssec-tools/configs/production"
63 rollrec "production.rollrec"
64 administrator "sysfolks@example.com"
65 display "1"
66 args "-loglevel phase -logfile log.prod -display"
67 user "prodmgr"
68 The first step in using this module must be to read the realm file.
70 The realm_read() interface reads the file and parses it into an
71 internal format. The file's records are copied into a hash table (for
72 easy reference by the realm.pm routines) and in an array (for
73 preserving formatting and comments.)
74 After the file has been read, the contents are referenced using
76 realm_fullrec() and realm_recval(). The realm_add() and realm_setval()
77 interfaces are used to modify the contents of a realm record.
78 If the realm file has been modified, it must be explicitly written or
80 the changes will not saved. realm_write() saves the new contents to
81 disk. realm_close() saves the file and close the Perl file handle to
82 the realm file. If a realm file is no longer wanted to be open, yet
83 the contents should not be saved, realm_discard() gets rid of the data
84 closes and the file handle without saving any modified data.
85 On reading a realm file, consecutive blank lines are collapsed into a
87 single blank line. As realm entries are added and deleted, files
88 merged and files split, it is possible for blocks of consecutive blanks
89 lines to grow. This will prevent these blocks from growing
90 excessively.
91
93 This module includes interfaces for synchronizing access to the realm
94 files. This synchronization is very simple and relies upon locking and
95 unlocking a single lock file for all realm files.
96 realm locking is not required before using this module, but it is
98 recommended. The expected use of these facilities follows:
99 realm_lock() || die "unable to lock realm file\n";
101 realm_read();
102 ... perform other realm operations ...
103 realm_close();
104 realm_unlock();
105 Synchronization is performed in this manner due to the way the module's
107 functionality is implemented, as well as providing flexibility to users
108 of the module. It also provides a clear delineation in callers' code
109 as to where and when realm locking is performed.
110 This synchronization method has the disadvantage of having a single
112 lockfile as a bottleneck to all realm file access. However, it reduces
113 complexity in the locking interfaces and cuts back on the potential
114 number of required lockfiles.
115 Using a single synchronization file may not be practical in large
117 installations. If that is found to be the case, then this will be
118 reworked.
119
121 The interfaces to the realm.pm module are given below.
122 realm_add(realm_type,realm_name,fields)
124 This routine adds a new realm to the realm file and the internal
125 representation of the file contents. The realm is added to both
126 the %realms hash table and the @realmlines array. Entries are only
127 added if they are defined for realms.
128 realm_type is the type of the realm. This must be "realm".
130 realm_name is the name of the realm. fields is a reference to a
131 hash table that contains the name/value realm fields. The keys of
132 the hash table are always converted to lowercase, but the entry
133 values are left as given.
134 A blank line is added after the final line of the new realm. The
136 realm file is not written after realm_add(), though it is
137 internally marked as having been modified.
138 realm_del(realm_name)
140 This routine deletes a realm from the realm file and the internal
141 representation of the file contents. The realm is deleted from
142 both the %realms hash table and the @realmlines array.
143 Only the realm itself is deleted from the file. Any associated
145 comments and blank lines surrounding it are left intact. The realm
146 file is not written after realm_del(), though it is internally
147 marked as having been modified.
148 Return values are:
150 0 successful realm deletion
152 -1 unknown name
153 realm_close()
155 This interface saves the internal version of the realm file (opened
156 with realm_read()) and closes the file handle.
157 realm_delfield(realm_name,field)
159 Deletes the given field from the specified realm. The file is not
160 written after updating the value, but the internal file-modified
161 flag is set. The value is saved in both %realms and in
162 @realmlines.
163 Return values:
165 0 - failure (realm not found or realm does not
167 contain the field)
168 1 - success
169 realm_discard()
171 This routine removes a realm file from use by a program. The
172 internally stored data are deleted and the realm file handle is
173 closed. However, modified data are not saved prior to closing the
174 file handle. Thus, modified and new data will be lost.
175 realm_exists(realm_name)
177 This routine returns a boolean flag indicating if the realm named
178 in realm_name exists.
179 realm_fullrec(realm_name)
181 realm_fullrec() returns a reference to the realm specified in
182 realm_name.
183 realm_lock()
185 realm_lock() locks the realm lockfile. An exclusive lock is
186 requested, so the execution will suspend until the lock is
187 available. If the realm synchronization file does not exist, it
188 will be created. If the process can't create the synchronization
189 file, an error will be returned.
190 Success or failure is returned.
192 realm_merge(target_realm_file, realm_file1, ... realm_fileN)
194 This interface merges the specified realm files. It reads each
195 file and parses them into a realm hash table and a file-contents
196 array. The resulting merge is written to the file named by
197 target_realm_file. If another realm is already open, it is saved
198 and closed prior to opening the new realm.
199 If target_realm_file is an existing realm file, its contents will
201 be merged with the other files passed to realm_merge(). If the
202 file does not exist, realm_merge() will create it and merge the
203 remaining files into it.
204 Upon success, realm_read() returns the number of realms read from
206 the file.
207 Failure return values:
209 -1 no realm files were given to realm_merge
211 -2 unable to create target realm file
212 -3 unable to read first realm file
213 -4 an error occurred while reading the realm names
214 -5 realm files were duplicated in the list of realm files
215 realm_names()
217 This routine returns a list of the realm names from the file.
218 realm_read(realm_file)
220 This interface reads the specified realm file and parses it into a
221 realm hash table and a file-contents array. realm_read() must be
222 called prior to any of the other realm.pm calls. If another realm
223 is already open, it is saved and closed prior to opening the new
224 realm.
225 realm_read() attempts to open the realm file for reading and
227 writing. If this fails, then it attempts to open the file for
228 reading only.
229 realm_read() is a front-end for realm_readfile(). It sets up the
231 module's saved data in preparation for reading a new realm file.
232 These house-keeping actions are not performed by realm_readfile().
233 Upon success, realm_read() returns the number of realms read from
235 the file.
236 Failure return values:
238 -1 specified realm file doesn't exit
240 -2 unable to open realm file
241 -3 duplicate realm names in file
242 realm_readfile(realm_file_handle)
244 This interface reads the specified file handle to a realm file and
245 parses the file contents into a realm hash table and a file-
246 contents array. The hash table and file-contents array are not
247 cleared prior to adding data to them.
248 Upon success, realm_read() returns zero.
250 Failure return values:
252 -1 duplicate realm names in file
254 realm_rectype(realm_name,rectype)
256 Set the type of the specified realm record. The file is not
257 written after updating the value, but the internal file-modified
258 flag is set. The value is saved in both %realms and in
259 @realmlines.
260 realm_name is the name of the realm that will be modified. rectype
262 is the new type of the realm, which must be "realm".
263 Return values:
265 0 - failure (invalid record type or realm not found)
267 1 - success
268 realm_recval(realm_name,realm_field)
270 This routine returns the value of a specified field in a given
271 realm. realm_name is the name of the particular realm to consult.
272 realm_field is the field name within that realm.
273 For example, the current realm file contains the following realm.
275 realm "example"
277 rollrec "example.rrf"
278 The call:
280 realm_recval("example","rollrec")
282 will return the value "example.rrf".
284 realm_rename(old_realm_name,new_realm_name)
286 This routine renames the realm named by old_realm_name to
287 new_realm_name. The actual effect is to change the name in the
288 realm line to new_realm_name. The name is changed in the internal
289 version of the the realm file only. The file itself is not
290 changed, but must be saved by calling either realm_write(),
291 realm_save(), or realm_saveas().
292 old_realm_name must be the name of an existing realm. Conversely,
294 new_realm_name must not name an existing realm.
295 Return values:
297 0 - success
299 -1 - old_realm_name was null or empty
300 -2 - new_realm_name was null or empty
301 -3 - old_realm_name is not an existing realm
302 -4 - new_realm_name is already a realm
303 -5 - internal error that should never happen
304 realm_setval(realm_name,field,value)
306 Set the value of a name/field pair in a specified realm. The file
307 is not written after updating the value, but the internal file-
308 modified flag is set. The value is saved in both %realms and in
309 @realmlines.
310 realm_name is the name of the realm that will be modified. If the
312 named realm does not exist, it will be created as a "realm"-type
313 realm. field is the realm field which will be modified. value is
314 the new value for the field.
315 realm_split(new_realm_file,realm_names)
317 Move a set of realm entries from the current realm file to a new
318 file. The moved realm entries are removed both from the current
319 file and from the internal module data representing that file.
320 The new_realm_file parameter holds the name of the new realm file.
322 If this file doesn't exist, it will be created. If it does exist,
323 the realm entries will be appended to that file.
324 realm_names is a list of realm entries that will be moved from the
326 current file to the file named in new_realm_file. If some of the
327 given realm names are invalid, the valid names will be moved to the
328 new file and the invalid names will be returned in a list to the
329 caller.
330 Only the realm entries themselves will be moved to the new realm
332 file. Any associated comments will be left in the current realm
333 file.
334 On success, the count of moved realm entries is returned. Error
336 returns are given below.
337 Failure return values:
339 -1 - no target realm file given in new_realm_file
340 -2 - no realm names given in realm_names
341 -3 - none of the realm names given are existing realms
342 -4 - unable to open new_realm_file
343 -5 - invalid realm names were specified in realm_names,
344 followed by the list of bad names.
345 realm_unlock()
347 realm_unlock() unlocks the realm synchronization file.
348 realm_write()
350 This interface saves the internal version of the realm file (opened
351 with realm_read()). It does not close the file handle. As an
352 efficiency measure, an internal modification flag is checked prior
353 to writing the file. If the program has not modified the contents
354 of the realm file, it is not rewritten.
355 realm_write() gets an exclusive lock on the realm file while
357 writing.
358
360 The interfaces described in this section are intended for internal use
361 by the realm.pm module. However, there are situations where external
362 entities may have need of them. Use with caution, as misuse may result
363 in damaged or lost realm files.
364 realm_init()
366 This routine initializes the internal realm data. Pending changes
367 will be lost. A new realm file must be read in order to use the
368 realm.pm interfaces again.
369 realm_default()
371 This routine returns the name of the default realm file.
372
374 The following interfaces display information about the currently parsed
375 realm file. They are intended to be used for debugging and testing,
376 but may be useful at other times.
377 realm_dump_hash()
379 This routine prints the realm file as it is stored internally in a
380 hash table. The realms are printed in alphabetical order, with the
381 fields alphabetized for each realm. New realms and realm fields
382 are alphabetized along with current realms and fields. Comments
383 from the realm file are not included with the hash table.
384 realm_dump_array()
386 This routine prints the realm file as it is stored internally in an
387 array. The realms are printed in the order given in the file, with
388 the fields ordered in the same manner. New realms are appended to
389 the end of the array. realm fields added to existing realms are
390 added at the beginning of the realm entry. Comments and vertical
391 whitespace are preserved as given in the realm file.
392
394 Copyright 2012-2014 SPARTA, Inc. All rights reserved. See the COPYING
395 file included with the DNSSEC-Tools package for details.
396
398 Wayne Morrison, tewok@tislabs.com
399
401 lsrealm(1), realmchk(8), realminit(8)
402 Net::DNS::SEC::Tools::realm(3),
404perl v5.32.1 2021-01-26 realm(3)