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

NAME

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

SYNOPSIS

9         use Net::DNS::SEC::Tools::realm;
10
11         realm_lock();
12         realm_read("localhost.realm");
13
14         @rlmnames = realm_names();
15
16         $flag = realm_exists("example");
17
18         $rrec = realm_fullrec("example");
19         %rrhash = %$rrec;
20         $zname = $rrhash{"maxttl"};
21
22         $val = realm_recval("example","state");
23
24         realm_add("realm","example",\%realmfields);
25
26         realm_del("example");
27
28         realm_rename("example","test-realm");
29
30         realm_setval("example","rollrec","example.rrf");
31
32         realm_delfield("example","user");
33
34         @realmfields = realm_fields();
35
36         $count = realmrec_merge("primary.realm", "new0.realm", "new1.realm");
37         @retvals = realmrec_split("new-realm.rrf", @list_of_realms);
38
39
40         $default_file = realm_default();
41
42         realm_write();
43         realm_close();
44         realm_discard();
45
46         realm_unlock();
47

DESCRIPTION

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
55       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
59               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
69       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
75       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
79       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
86       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

REALM LOCKING

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
97       realm locking is not required before using this module, but it is
98       recommended.  The expected use of these facilities follows:
99
100           realm_lock() || die "unable to lock realm file\n";
101           realm_read();
102           ... perform other realm operations ...
103           realm_close();
104           realm_unlock();
105
106       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
111       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
116       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

REALM INTERFACES

121       The interfaces to the realm.pm module are given below.
122
123       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
129           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
135           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
139       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
144           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
149           Return values are:
150
151                0 successful realm deletion
152               -1 unknown name
153
154       realm_close()
155           This interface saves the internal version of the realm file (opened
156           with realm_read()) and closes the file handle.
157
158       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
164           Return values:
165
166               0 - failure (realm not found or realm does not
167                   contain the field)
168               1 - success
169
170       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
176       realm_exists(realm_name)
177           This routine returns a boolean flag indicating if the realm named
178           in realm_name exists.
179
180       realm_fullrec(realm_name)
181           realm_fullrec() returns a reference to the realm specified in
182           realm_name.
183
184       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
191           Success or failure is returned.
192
193       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
200           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
205           Upon success, realm_read() returns the number of realms read from
206           the file.
207
208           Failure return values:
209
210               -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
216       realm_names()
217           This routine returns a list of the realm names from the file.
218
219       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
226           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
230           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
234           Upon success, realm_read() returns the number of realms read from
235           the file.
236
237           Failure return values:
238
239               -1 specified realm file doesn't exit
240               -2 unable to open realm file
241               -3 duplicate realm names in file
242
243       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
249           Upon success, realm_read() returns zero.
250
251           Failure return values:
252
253               -1 duplicate realm names in file
254
255       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
261           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
264           Return values:
265
266               0 - failure (invalid record type or realm not found)
267               1 - success
268
269       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
274           For example, the current realm file contains the following realm.
275
276               realm       "example"
277                           rollrec        "example.rrf"
278
279           The call:
280
281               realm_recval("example","rollrec")
282
283           will return the value "example.rrf".
284
285       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
293           old_realm_name must be the name of an existing realm.  Conversely,
294           new_realm_name must not name an existing realm.
295
296           Return values:
297
298                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
305       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
311           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
316       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
321           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
325           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
331           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
335           On success, the count of moved realm entries is returned.  Error
336           returns are given below.
337
338           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
346       realm_unlock()
347           realm_unlock() unlocks the realm synchronization file.
348
349       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
356           realm_write() gets an exclusive lock on the realm file while
357           writing.
358

REALM INTERNAL INTERFACES

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
365       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
370       realm_default()
371           This routine returns the name of the default realm file.
372

REALM DEBUGGING INTERFACES

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
378       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
385       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

AUTHOR

398       Wayne Morrison, tewok@tislabs.com
399

SEE ALSO

401       lsrealm(1), realmchk(8), realminit(8)
402
403       Net::DNS::SEC::Tools::realm(3),
404
405
406
407perl v5.36.0                      2023-01-19                          realm(3)
Impressum