BUILDREALMS(1)

📦 version 2.2.3, in arch rolling

💅 buildrealms(1) — or, how to build your DNSSEC-Tools realms environment without losing your mind

okay so real quick, bestie: this is the manual page for buildrealms, and it lives in the User Contributed Perl Documentation section, so you already know it's giving perl-core energy. it's a whole helper tool for DNSSEC-Tools, and it's honestly iconic once you get what it's doing. let's go 🎀

✨ NAME ✨

buildrealms — literally here to assist you in building a DNSSEC-Tools realms environment. that's the whole job. 🫶

🌸 SYNOPSIS 🌸

buildrealms [options] <realmsfile> <command> <command-args>

that's it. that's the shape of it. <realmsfile> goes in, a <command> goes in, the <command-args> follow along, and options sprinkle on top like glitter. ✨

💖 DESCRIPTION 💖

so. buildrealms is your bestie for setting up a realms environment that dtrealms can actually use. no cap, it does a lot:

it creates the required file hierarchies for each realm
it moves a realm's files to their appropriate place in the hierarchy
it updates several files for the final destination

the realm hierarchies get built in a staging area, and that staging area is gonna hold the files for all the realms. we're talking rollrec files, keyrec files, key files, configuration files, log files, and anything else DNSSEC-Tools needs to manage key rollover. 🗂️

⚠️ after buildrealms creates these files, you (yes, you, main character) should check the files to make sure they're correct. the files and directories in the staging then must be manually moved to the final directory. that final directory is where dtrealms will manage the various realms from. if the final directory isn't specified (via an option), then the directory in which buildrealms was executed becomes the final directory. periodt.

buildrealms uses a realms file to control how it builds the realms environment. the realm entries in this file have a hoard field, and that field is only used by buildrealms. for each realm, this field's value is a directory holding the files needed by that particular realm. after building that realm, buildrealms removes the hoard entry from that realm record. and after all the realms have been built, a copy of this realms file gets moved into the staging area. cute, right? 🦋

there are two operations buildrealms currently provides. both are in support of creating and maintaining a DNSSEC-Tools realms environment. this documentation describes the operations individually. 👑

🌈 Realms Environment Creation

the create command builds the whole realms environment. the realm file hierarchies are built in the staging area. after buildrealms creates these files, the user should check the files to ensure that they are correct. the files and directories in the staging then must be manually moved to the final directory. if the final directory isn't specified (via an option), then the directory in which buildrealms was executed will be the final directory.

buildrealms takes the following actions when given the create command:

A file hierarchy is created for each realm. 🌳
A DNSSEC-Tools configuration file is put in each realm's hierarchy. if the -config option is given, then the specified configuration file will be copied to each realm. if it isn't given, then each realm's hoard will be searched for a file whose name ends with .conf. the first such file found will be used for that realm only. if such a file is not found, then the system-wide DNSSEC-Tools configuration file will be used for that realm. 🎀
The realm's rollrec, keyrec, zone, and key files are moved into the hierarchy. the rollrec file is named in the realms file. the keyrec and signed zone files are listed in the rollrec file. the unsigned zone files and key files are listed in the keyrec file.
A key archive is created for each realm's existing, expired keys. the key archive is placed in the realm's state directory in the staging area. archived keys, as listed in the keyrec files, are moved to this key archive. 📦
Paths in several files are adjusted for the new hierarchy and the realm's final destination. these paths include archived keys in the realm's keyrec files, the key archive and rollerd log files in the realm's DNSSEC-Tools configuration file, and key directories in the keyrec files. 🔥

🦋 Realms Hierarchy Creation

the trees command builds the basic directory hierarchy for each realm in the staging area. however — and this is important — no other files or directories are copied or moved in to the staging area. (yes, the original really does end that sentence with two periods. we stan a quirky queen. 💀)

the following directories are created for each realm:

configuration directory — this holds the dnssec-tools directory.
dnssec-tools directory — this will hold the DNSSEC-Tools configuration file.
state directory — this will hold the realm's state information, including the key archive.
realm directory — this will hold the realm's rollrec file, the keyrec files, the zone files (signed and unsigned), and the key files.

🧚 PREPARING FOR EXECUTION 🧚

in preparing a realms file and the realm hoards for buildrealms, there are several things that should be kept in mind. lowkey this is the part you don't wanna skip:

Use relative paths for the rollrec file and three directories in the realms file.
All a realm's files should be stored in its hoard. they do not have to be in a particular place in the directory, as long as the rollrec and keyrec files are accurate. ✨
At the end of the creation process, the realms file will be copied into the top level of the staging area.
After specific files (e.g., rollrecs, keyrecs, etc.) are moved into a realm's part of the staging area, the remaining files in the hoard will be moved into the realm's realmdir part of the staging area. the hierarchical organization of the remaining hoard files will be preserved. 🗂️
The contents of a keyrec's archive directory in the realm's hoard, as defined by the archivedir field, will be moved to <statedir>/key-archive in the staging area.
The configuration file for a realm will be put in <configdir>/dnssec-tools/<conffile> in the staging area. the actual name of the configuration file (given here as <conffile>) will depend on how the configuration file is found. if the system-wide DNSSEC-Tools file is used, then the name will be dnssec-tools.conf. if the -config option is used, then the name used with the option will be used. if a .conf file is found in the realm's hoard, then the full filename will be used. 🎀

💀 WARNINGS 💀

root is not allowed to run buildrealms. some of the actions taken by buildrealms can be devastating if a misconfigured (or maliciously constructed) realm file is used to control construction. like, don't do it. fr fr. 🙈

buildrealms is not clairvoyant. it does the best it can, but it is a general tool. the resulting realms should be checked to ensure they are set up as desired. in particular, you should check the realm file rollrec files, keyrec files, and configuration file. 👀

no reverse functionality has been implemented, so once run, the files are modified, moved, and copied. it might not be a bad idea to back up your files prior to running buildrealms, just in case... 😭

👑 COMMANDS 👑

create — the create command builds the whole realms environment. buildrealms takes the following actions when given this command:
trees — the trees command builds the basic directory hierarchy for each realm. the following directories are created for each realm:

💅 OPTIONS 💅

-actions — display the file actions taken by buildrealms. this includes directory creations, file copies, and file moves. if used in conjunction with the -nobuild option, buildrealms will not perform the actions, but will display the actions that would otherwise have been taken. 👀
-clear — this flag indicates that buildrealms should delete the current staging area and its contents prior to building the realms. 🧹
-config conffile — conffile is the DNSSEC-Tools configuration file to copy for each realm.
-directory target — target is the target directory for the realms to be built by buildrealms. the new realms will not be moved to this directory, but the realms' files will reflect the use of this directory. if this option is not specified, the current directory will be used. 📁 if -directory and -stagedir use the same directory, then the realms environment will be build in the final directory.
-nobuild — this option tells buildrealms to go through the motions of building the new realms, but not to actually build anything. if this is used in conjunctions with the -actions option, buildrealms will show the actions that would have been taken. 🙈
-stagedir directory — this directory in which the new realms hierarchy is built. the default staging area is ./staging-buildrealms if this option is not specified. 🎀 if -directory and -stagedir use the same directory, then the realms environment will be build in the final directory.
-quiet — buildrealms is prevented from printing any non-error output. this option and the -verbose option are mutually exclusive. 🤫
-verbose — buildrealms prints a lot of information about what it is doing. this option and the -quiet option are mutually exclusive. 🗣️
-Version — displays the version number.
-help — displays a help message. 💖

🌸 EXAMPLES 🌸

okay so these examples are gonna make buildrealms click for you, bestie, fr fr 💖 in every example we're rolling with this same realms file right here:

realm "example"
    state           "active"
    configdir       "configs/example"
    statedir        "states/example"
    realmdir        "r-example"
    rollrec         "demo-example.rollrec"
    administrator   "zonefolks@example.com"
    display         "1"
    manager         "rollerd"
    args            "-loglevel phase -logfile log.example"
    hoard           "r-example"

realm "test"
    state           "active"
    realmdir        "r-test"
    configdir       "configs/test"
    statedir        "states/test"
    rollrec         "demo-test.rollrec"
    manager         "rollerd"
    args            "-loglevel tmi -logfile log.test"
    display         "1"
    hoard           "r-test"

🎀 CREATE EXAMPLE 🎀

so every realm record has a hoard field, right? and that's literally the thing buildrealms uses to find that realm's files ✨ after you run buildrealms demo.realm create with the realms file above, these directories get created:

staging-buildrealms/
staging-buildrealms/configs/
staging-buildrealms/configs/example/
staging-buildrealms/configs/example/dnssec-tools/
staging-buildrealms/configs/test/
staging-buildrealms/configs/test/dnssec-tools/

staging-buildrealms/r-example/
staging-buildrealms/r-example/dnssec-tools/
staging-buildrealms/r-test/
staging-buildrealms/r-test/dnssec-tools/

staging-buildrealms/states/
staging-buildrealms/states/example/
staging-buildrealms/states/example/key-archive/
staging-buildrealms/states/test/
staging-buildrealms/states/test/key-archive/

and these files get moved into the staging area 👑 ngl, for the sake of brevity this is only a subset of the files moved there — most of the key files aren't even in this list:

staging-buildrealms/demo.realm

staging-buildrealms/configs/example/dnssec-tools/dnssec-tools.conf
staging-buildrealms/configs/test/dnssec-tools/dnssec-tools.conf

staging-buildrealms/r-example/demo-example.rollrec
staging-buildrealms/r-example/demo.com
staging-buildrealms/r-example/demo.com.signed
staging-buildrealms/r-example/dsset-demo.com.
staging-buildrealms/r-example/dsset-example.com.
staging-buildrealms/r-example/dsset-test.com.
staging-buildrealms/r-example/example.com
staging-buildrealms/r-example/example.com.signed
staging-buildrealms/r-example/Kdemo.com.+005+16933.key
staging-buildrealms/r-example/Kdemo.com.+005+16933.private
staging-buildrealms/r-example/test.com
staging-buildrealms/r-example/test.com.signed

staging-buildrealms/r-test/demo-test.rollrec
staging-buildrealms/r-test/dev.com
staging-buildrealms/r-test/dev.com.signed
staging-buildrealms/r-test/dsset-dev.com.
staging-buildrealms/r-test/dsset-test.com.
staging-buildrealms/r-test/Ktest.com.+005+34236.key
staging-buildrealms/r-test/Ktest.com.+005+34236.private
staging-buildrealms/r-test/test.com
staging-buildrealms/r-test/test.com.signed

🦋 TREES EXAMPLE 🦋

now after you run buildrealms demo.realm trees with that same realms file above, these directories get created:

staging-buildrealms/
staging-buildrealms/configs/
staging-buildrealms/configs/example/
staging-buildrealms/configs/example/dnssec-tools/
staging-buildrealms/configs/test/
staging-buildrealms/configs/test/dnssec-tools/

staging-buildrealms/r-example/
staging-buildrealms/r-test/

staging-buildrealms/states/
staging-buildrealms/states/example/
staging-buildrealms/states/test/

and that's it — no additional files or directories are created by this command 💅 clean, minimal, iconic.

📜 COPYRIGHT 📜

✍️ AUTHOR ✍️

Wayne Morrison, tewok@tislabs.com

👀 SEE ALSO 👀

dtrealms(8), realminit(8), realmset(8)
keyrec(5), realm(5), rollrec(5)

okay bestie that's the whole page, you ate that 🫶 this one's from perl v5.44.0, dated 2026-10-17, and it's BUILDREALMS(1) — go build some realms, you've got this 💜✨

📦 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