realm(3)

📦

version 2.2.3 · 3 versions

2.2.3 · arch rolling (latest)
2.2.3 · fedora 43
2.2.3 · fedora 44

💖 NAME 💖

realm(3) is the manual page for Net::DNS::SEC::Tools::realm — from the User Contributed Perl Documentation corner, no cap. its whole job is to manipulate a DNSSEC-Tools realm file. that's the name-line info folded in cute instead of copy-pasted, periodt 💅

✨ SYNOPSIS ✨

okay bestie, here's the entire API mood board, verbatim — do not come for me about the semicolons, they're iconic:

use Net::DNS::SEC::Tools::realm;

realm_lock();
realm_read("localhost.realm");

@rlmnames = realm_names();

$flag = realm_exists("example");

$rrec = realm_fullrec("example");
%rrhash = %$rrec;
$zname = $rrhash{"maxttl"};

$val = realm_recval("example","state");

realm_add("realm","example",\%realmfields);

realm_del("example");

realm_rename("example","test-realm");

realm_setval("example","rollrec","example.rrf");

realm_delfield("example","user");

@realmfields = realm_fields();

$count = realmrec_merge("primary.realm", "new0.realm", "new1.realm");
@retvals = realmrec_split("new-realm.rrf", @list_of_realms);

$default_file = realm_default();

realm_write();
realm_close();
realm_discard();

realm_unlock();

🦋 DESCRIPTION 🦋

so the way that Net::DNS::SEC::Tools::realm works is: it manipulates the contents of a DNSSEC-Tools realm file. realm files describe the status of a zone rollover environment, as managed by the DNSSEC-Tools programs. module interfaces exist for looking up realm records, creating new records, and modifying existing records — all the main-character energy ✨

a realm file is organized in sets of realm records. realms describe the state of a rollover environment. a realm consists of a set of keyword/value entries. here's the example, bestie, exactly as it appears:

realm "production"
        state           "active"
        realmdir        "/usr/etc/dnssec-tools/realms/production"
        configdir       "/usr/etc/dnssec-tools/configs/production"
        rollrec         "production.rollrec"
        administrator   "sysfolks@example.com"
        display         "1"
        args            "-loglevel phase -logfile log.prod -display"
        user            "prodmgr"

the first step in using this module must be to read the realm file. realm_read() reads the file and parses it into an internal format. the file's records are copied into a hash table (for easy reference by the realm.pm routines) and into an array (for preserving formatting and comments). lowkey organized, highkey useful 🫶

after the file has been read, the contents are referenced using realm_fullrec() and realm_recval(). the realm_add() and realm_setval() interfaces are used to modify the contents of a realm record. slay 💅

if the realm file has been modified, it must be explicitly written or the changes will not be saved. realm_write() saves the new contents to disk. realm_close() saves the file and closes the Perl file handle to the realm file. if a realm file is no longer wanted to be open, yet the contents should not be saved, realm_discard() gets rid of the data, closes the file handle, and does not save any modified data.

⚠️ if you modify the realm file and don't explicitly write it with realm_write() or realm_close(), the changes will not be saved. that's not a vibe, bestie.

on reading a realm file, consecutive blank lines are collapsed into a single blank line. as realm entries are added and deleted, files are merged, and files are split, it is possible for blocks of consecutive blank lines to grow. this prevents those blocks from growing excessively. we love a little tidiness enforcement 🎀

🔒 REALM LOCKING 🔒

this module includes interfaces for synchronizing access to the realm files. this synchronization is very simple and relies upon locking and unlocking a single lock file for all realm files. simple, iconic, one lockfile to rule them all 🔥

realm locking is not required before using this module, but it is recommended. the expected use of these facilities follows:

realm_lock() || die "unable to lock realm file\n";
realm_read();
... perform other realm operations ...
realm_close();
realm_unlock();

synchronization is performed in this manner due to the way the module's functionality is implemented, as well as providing flexibility to users of the module. it also provides a clear delineation in callers' code as to where and when realm locking is performed. iykyk ✨

this synchronization method has the disadvantage of having a single lockfile as a bottleneck to all realm file access. however, it reduces complexity in the locking interfaces and cuts back on the potential number of required lockfiles. trade-offs, bestie, trade-offs 💀

using a single synchronization file may not be practical in large installations. if that is found to be the case, then this will be reworked.

🫶 REALM INTERFACES 🫶

okay so here’s the full menu of realm.pm interfaces, bestie — every single one listed below, no skips, no crumbs, no “you’ll figure it out” energy. ✨

`realm_add(realm_type,realm_name,fields)`

This adds a brand-new realm to the realm file and to the internal representation of the file contents. It goes into both the %realms hash table and the @realmlines array. Entries only get added if they’re defined for realms — no phantom entries, periodt.

realm_type is the type of the realm. It must be "realm".
realm_name is the name of the realm.
fields is a reference to a hash table holding the name/value realm fields.

The hash table’s keys are always converted to lowercase, but the entry values are left exactly as given. 💅

A blank line gets added after the final line of the new realm. The realm file is not written after realm_add(), though it is internally marked as having been modified.

`realm_del(realm_name)`

This deletes a realm from the realm file and from the internal representation of the file contents. The realm is removed from both %realms and @realmlines. 🧹

Only the realm itself is deleted from the file. Any associated comments and blank lines surrounding it are left intact. The realm file is not written after realm_del(), though it is internally marked as having been modified.

Return values are:

0 — successful realm deletion
-1 — unknown name

`realm_close()`

This interface saves the internal version of the realm file — the one opened with realm_read() — and closes the file handle. 🎀

`realm_delfield(realm_name,field)`

Deletes the given field from the specified realm. The file is not written after updating the value, but the internal file-modified flag is set. The value is saved in both %realms and in @realmlines.

Return values:

0 — failure (realm not found, or realm does not contain the field)
1 — success

`realm_discard()`

This routine removes a realm file from use by a program. The internally stored data are deleted and the realm file handle is closed.

🚨 But bestie, listen: modified data are not saved prior to closing the file handle. So modified and new data will be lost. That’s the whole warning. Do not skip it.

`realm_exists(realm_name)`

Returns a boolean flag indicating whether the realm named in realm_name exists. Simple vibe check: exists or not. ✅

`realm_fullrec(realm_name)`

realm_fullrec() returns a reference to the realm specified in realm_name. 🫶

`realm_lock()`

realm_lock() locks the realm lockfile. It requests an exclusive lock, so execution will suspend until the lock is available. If the realm synchronization file does not exist, it will be created. If the process can’t create the synchronization file, an error will be returned.

Success or failure is returned.

`realm_merge(target_realm_file, realm_file1, ... realm_fileN)`

This interface merges the specified realm files. It reads each file and parses them into a realm hash table and a file-contents array. The resulting merge is written to the file named by target_realm_file. If another realm is already open, it is saved and closed prior to opening the new realm. 🔥

If target_realm_file is an existing realm file, its contents will be merged with the other files passed to realm_merge(). If the file does not exist, realm_merge() will create it and merge the remaining files into it.

Upon success, realm_read() returns the number of realms read from the file.

Failure return values:

-1 — no realm files were given to realm_merge
-2 — unable to create target realm file
-3 — unable to read first realm file
-4 — an error occurred while reading the realm names
-5 — realm files were duplicated in the list of realm files

`realm_names()`

Returns a list of the realm names from the file. Name drop, but make it data. 📛

`realm_read(realm_file)`

This interface reads the specified realm file and parses it into a realm hash table and a file-contents array. realm_read() must be called prior to any of the other realm.pm calls. If another realm is already open, it is saved and closed prior to opening the new realm.

realm_read() attempts to open the realm file for reading and writing. If that fails, it then attempts to open the file for reading only.

realm_read() is a front-end for realm_readfile(). It sets up the module’s saved data in preparation for reading a new realm file. These house-keeping actions are not performed by realm_readfile().

Upon success, realm_read() returns the number of realms read from the file.

Failure return values:

-1 specified realm file doesn't exit
-2 unable to open realm file
-3 duplicate realm names in file

`realm_readfile(realm_file_handle)`

This interface reads the specified file handle to a realm file and parses the file contents into a realm hash table and a file-contents array. The hash table and file-contents array are not cleared prior to adding data to them. 🙈

Upon success, realm_read() returns zero.

Failure return values:

-1 duplicate realm names in file

`realm_rectype(realm_name,rectype)`

Sets the type of the specified realm record. The file is not written after updating the value, but the internal file-modified flag is set. The value is saved in both %realms and in @realmlines.

realm_name is the name of the realm that will be modified.
rectype is the new type of the realm, which must be "realm".

Return values:

0 — failure (invalid record type, or realm not found)
1 — success

`realm_recval(realm_name,realm_field)`

This routine returns the value of a specified field in a given realm. realm_name is the name of the particular realm to consult. realm_field is the field name within that realm.

For example, the current realm file contains the following realm:

realm       "example"
            rollrec        "example.rrf"

The call:

realm_recval("example","rollrec")

will return the value "example.rrf". Look at that — icon behavior. 👑

`realm_rename(old_realm_name,new_realm_name)`

This routine renames the realm named by old_realm_name to new_realm_name. The actual effect is to change the name in the realm line to new_realm_name. The name is changed in the internal version of the realm file only. The file itself is not changed, but must be saved by calling either realm_write(), realm_save(), or realm_saveas().

old_realm_name must be the name of an existing realm. Conversely, new_realm_name must not name an existing realm.

Return values:

0 — success
-1 — old_realm_name was null or empty
-2 — new_realm_name was null or empty
-3 — old_realm_name is not an existing realm
-4 — new_realm_name is already a realm
-5 — internal error that should never happen

`realm_setval(realm_name,field,value)`

Sets the value of a name/field pair in a specified realm. The file is not written after updating the value, but the internal file-modified flag is set. The value is saved in both %realms and in @realmlines. ✨

realm_name is the name of the realm that will be modified. If the named realm does not exist, it will be created as a "realm"-type realm.
field is the realm field which will be modified.
value is the new value for the field.

`realm_split(new_realm_file,realm_names)`

Moves a set of realm entries from the current realm file to a new file. The moved realm entries are removed both from the current file and from the internal module data representing that file. 🚚

The new_realm_file parameter holds the name of the new realm file. If this file doesn’t exist, it will be created. If it does exist, the realm entries will be appended to that file.

realm_names is a list of realm entries that will be moved from the current file to the file named in new_realm_file. If some of the given realm names are invalid, the valid names will be moved to the new file and the invalid names will be returned in a list to the caller.

Only the realm entries themselves will be moved to the new realm file. Any associated comments will be left in the current realm file.

On success, the count of moved realm entries is returned. Error returns are given below.

Failure return values:

-1 — no target realm file given in new_realm_file
-2 — no realm names given in realm_names
-3 — none of the realm names given are existing realms
-4 — unable to open new_realm_file
-5 — invalid realm names were specified in realm_names, followed by the list of bad names

`realm_unlock()`

realm_unlock() unlocks the realm synchronization file. Unlock it, bestie. 🔓

`realm_write()`

This interface saves the internal version of the realm file — the one opened with realm_read(). It does not close the file handle. As an efficiency measure, an internal modification flag is checked prior to writing the file. If the program has not modified the contents of the realm file, it is not rewritten. 💾

realm_write() gets an exclusive lock on the realm file while writing.

🔒 REALM INTERNAL INTERFACES 🔒

The interfaces described in this section are intended for internal use by the realm.pm module. However, there are situations where external entities may have need of them.

⚠️ Use with caution, because misuse may result in damaged or lost realm files. This is not the cute kind of risky. This is the “why is my file gone” kind of risky. 💀

`realm_init()`

This routine initializes the internal realm data. Pending changes will be lost. A new realm file must be read in order to use the realm.pm interfaces again. 🌀

`realm_default()`

This routine returns the name of the default realm file. The default, the blueprint, the main character file. 🌟

🐛 REALM DEBUGGING INTERFACES 🐛

okay so these next ones are the little detective tools 👀 — they show you what the realm file looks like after it's been parsed. They're literally made for debugging and testing, but ngl they can come in handy other times too. no gatekeeping 💅

🔍 `realm_dump_hash()`

This one prints out the realm file the way it lives inside a hash table internally. So the realms come out in alphabetical order, and the fields inside each realm are alphabetized too — everything's sorted, it's giving organized queen energy ✨ New realms and new realm fields get alphabetized right alongside the current realms and fields, so nothing's off in a corner by itself. One thing though: comments from the realm file are NOT included in the hash table dump. sorry bestie, they don't make the cut 🙈

📋 `realm_dump_array()`

This one prints the realm file as it's stored internally in an array — completely different vibe. Realms come out in the order given in the file, and the fields are ordered the same way too. New realms? They get appended to the end of the array. And realm fields added to existing realms? Those get added at the beginning of the realm entry (yes, the beginning, not the end — that's just how it is 🫶). The best part: comments and vertical whitespace are preserved exactly as given in the realm file, so it's the whole aesthetic, untouched. 💖

📜 COPYRIGHT

✍️ AUTHOR

Wayne Morrison, tewok@tislabs.com

👀 SEE ALSO

lsrealm(1)
realmchk(8)
realminit(8)
Net::DNS::SEC::Tools::realm(3)

and that's the whole page bestie, we ate that 🍓💅 this particular rendering is brought to you by perl v5.44.0, dated 2026-10-17, under the name realm(3) — iconic, no cap 👑🌈

📦 where this page comes from

arch rolling: dnssec-tools 2.2.3-16 · BSD
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

realm(3)

💖 NAME 💖

✨ SYNOPSIS ✨

🦋 DESCRIPTION 🦋

🔒 REALM LOCKING 🔒

🫶 REALM INTERFACES 🫶

realm_add(realm_type,realm_name,fields)

realm_del(realm_name)

realm_close()

realm_delfield(realm_name,field)

realm_discard()

realm_exists(realm_name)

realm_fullrec(realm_name)

realm_lock()

realm_merge(target_realm_file, realm_file1, ... realm_fileN)

realm_names()

realm_read(realm_file)

realm_readfile(realm_file_handle)

realm_rectype(realm_name,rectype)

realm_recval(realm_name,realm_field)

realm_rename(old_realm_name,new_realm_name)

realm_setval(realm_name,field,value)

realm_split(new_realm_file,realm_names)

realm_unlock()

realm_write()

🔒 REALM INTERNAL INTERFACES 🔒

realm_init()

realm_default()

🐛 REALM DEBUGGING INTERFACES 🐛

🔍 realm_dump_hash()

📋 realm_dump_array()

📜 COPYRIGHT

✍️ AUTHOR

👀 SEE ALSO

`realm_add(realm_type,realm_name,fields)`

`realm_del(realm_name)`

`realm_close()`

`realm_delfield(realm_name,field)`

`realm_discard()`

`realm_exists(realm_name)`

`realm_fullrec(realm_name)`

`realm_lock()`

`realm_merge(target_realm_file, realm_file1, ... realm_fileN)`

`realm_names()`

`realm_read(realm_file)`

`realm_readfile(realm_file_handle)`

`realm_rectype(realm_name,rectype)`

`realm_recval(realm_name,realm_field)`

`realm_rename(old_realm_name,new_realm_name)`

`realm_setval(realm_name,field,value)`

`realm_split(new_realm_file,realm_names)`

`realm_unlock()`

`realm_write()`

`realm_init()`

`realm_default()`

🔍 `realm_dump_hash()`

📋 `realm_dump_array()`