REALMINIT(1)

📦 version 2.2.3, in arch rolling

🦋 REALMINIT(1) — or, how to birth brand-new realms ✨

okay so bestie, this is a page from the User Contributed Perl Documentation section, and it's literally all about realminit. Let's get into it 💅

✨ NAME ✨

realminit — creates new realm records for a DNSSEC-Tools realms file. that's the whole vibe 🎀

🌸 SYNOPSIS 🌸

realminit [options] <realm1> ... <realmN>

💖 DESCRIPTION 💖

So realminit makes brand-new realm entries for a realms file. And what's a realm, you ask? okay so dtrealms is out here managing multiple distinct DNSSEC-Tools rollover environments running at the same time — and each one of those rollover environments is called a realm, and it gets defined in a realms file. dtrealms reads that file to figure out how to run the rollover environment. it's giving very useful, honestly — think managing absolutely massive collections of zones, keeping customer zones segregated, and software tests. iconic use cases fr fr 👑

The newly generated realm entries get written to standard output — unless you hit it with the -out option. noted 📝

A realms file has a bunch of entries, one for each managed realm. each realm entry looks exactly like this:

realm "example"
    state          "active"
    configdir      "/usr/realms/configs/example"
    statedir       "/usr/realms/states/example"
    realmsdir      "/usr/realms/realms-files/example"
    rollrec        "example.rrf"
    administrator  "bob@cat.example.com"
    display        "1"
    manager        "rollerd"
    args           "-display -loglevel phase"

You can create multiple realm entries with a single execution of realminit 🫶. Except for the entry's name field, those entries will be exactly the same — unless you use the '=' metacharacter in the command-line options. Here's the tea: if the values of the configdir, statedir, realmdir, rollrec, administrator, args, or user options contain an '=', then that '=' gets replaced with the realm's name when the entry is built. the EXAMPLES section down below shows exactly how options get used by realminit, so don't worry ✨

💅 OPTIONS 💅

realminit may be given the following options:

  • -active — this says dtrealms should start the realm whenever dtrealms starts. and lowkey realms are active by default, so this is the default vibe already.
  • -administrator — the email address for the realm's administrator 📧
  • -args — a set of command-line arguments that get passed to the realm's rollover manager when the realm is started.
  • -configdir — the realm's configuration directory. this is where stuff like the DNSSEC-Tools configuration file for that realm lives 🌸
  • -display — says whether the realm should be included in grandvizier output.
  • -inactive — this says dtrealms should not start the realm when dtrealms starts.
  • -manager — the rollover manager for the realm. rollerd is the default rollover manager, but other managers may be used.
  • -out output-file — the new realm entries get appended to output-file. the file gets created if it doesn't already exist 🎀
If this option is not given, the new rollrec entries will be written to standard output.
  • -realmdir — the realm's data directory. this directory is expected to contain the rollrec file, zone files, keyrec files, and key files for the zones in that realm.
  • -rollrec — the path to the realm's rollrec file. this is what's used to control rollover actions for the realm. if it's not an absolute path, it will be assumed to be relative to the realmdir field.
  • -statedir — the realm's state directory. this holds stuff like that realm's rollrec lock file and the rollerd communications socket. and if statedir isn't defined for a realm, then the realm's configdir gets used for that value 💜
  • -user — the user that the realm is executed as. (not yet implemented in dtrealms, just so you know 🙈)
  • -help — display a usage message.
  • -Version — display version information for realminit and DNSSEC-Tools.

🌈 EXAMPLES 🌈

these options should make it super clear how realminit deals with options and the new realms. Example 1 shows the complete new realm record. for the sake of brevity, the remaining examples only show the fields relevant to that example. and further examples also use short-hand forms of the option names — iykyk 😌

🍓 Example 1. One realm, with -statedir

this example shows the realm you get by giving realminit a single realm.

$ realminit -active -configdir /realms/confs/example -statedir /realms/states/example -realmdir /realms/realms/example -rollrec example.rrf -admin bob@cat.example.com -args "-loglevel phase -logfile logger" example

realm       "example"
    state           "active"
    configdir       "/realms/confs/example"
    statedir        "/realms/states/example"
    realmdir        "/realms/realms/example"
    rollrec         "example.rrf"
    administrator   "bob@cat.example.com"
    display         "1"
    manager         "rollerd"
    args            "-loglevel phase -logfile logger"

🦋 Example 2. One realm, without -statedir

this example shows the realm you get by giving realminit a single realm.

$ realminit -active -configdir /realms/confs/example -realmdir /realms/realms/example -rollrec example.rrf -admin bob@cat.example.com -args "-loglevel phase -logfile logger" example

realm       "example"
    state           "active"
    configdir       "/realms/confs/example"
    statedir        "/realms/confs/example"
    ...

⭐ Example 3. Two realms, without metacharacters

this example shows the realms you get by giving realminit two realms, without using the special "=" metacharacter.

$ realminit -configdir /realms/confs/example -statedir /realms/states/example -realmdir /realms/realms/example -rollrec example.rrf -admin bob@cat.example.com example test

realm       "example"
    configdir       "/realms/confs/example"
    statedir        "/realms/states/example"
    realmdir        "/realms/realms/example"
    rollrec         "example.rrf"
    administrator   "bob@cat.example.com"
    ...

realm       "test"
    configdir       "/realms/confs/example"
    statedir        "/realms/states/example"
    realmdir        "/realms/realms/example"
    rollrec         "example.rrf"
    administrator   "bob@cat.example.com"
    ...

💀 Example 4. Two realms, with metacharacters

this example shows the realms you get by giving realminit two realms, and that uses the special "=" metacharacter. this is where it gets good 🔥

$ realminit -configdir /realms/confs/= -statedir /realms/states/= -realmdir /realms/realms/= -rollrec =.rrf -admin bob@cat.=.com example test

realm       "example"
    configdir       "/realms/confs/example"
    statedir        "/realms/states/example"
    realmdir        "/realms/realms/example"
    rollrec         "example.rrf"
    administrator   "bob@cat.example.com"
    ...

realm       "test"
    configdir       "/realms/confs/test"
    statedir        "/realms/states/test"
    realmdir        "/realms/realms/test"
    rollrec         "test.rrf"
    administrator   "bob@cat.test.com"
    ...

Copyright 2012-2014 SPARTA, Inc. All rights reserved. see the COPYING file included with the DNSSEC-Tools package for details, bestie 📄

🧚 AUTHOR 🧚

Wayne Morrison, tewok@tislabs.com — legend behavior honestly 🫶

🌟 SEE ALSO 🌟

  • lsrealm(1), dtrealms(8), realmchk(8)
  • Net::DNS::SEC::Tools::realm.pm(3)
  • file-realmrec.pm(5)

okay and that's the whole page, mwah 💋 — this lil doc came to you courtesy of perl v5.44.0, dated 2026-10-17, and filed under REALMINIT(1). go forth and make realms, bestie 🌈✨

📦 where this page comes from