REALMCTL(1)

📦
version 2.2.3 · 2 versions
, in fedora 43

💖 realmctl(1) — the DNSSEC-Tools realms daemon whisperer 💖

okay so bestie, welcome to realmctl, a User Contributed Perl Documentation classic. she's a little command-line girly whose whole job is sliding into the DMs of dtrealms, the DNSSEC-Tools realms daemon. no cap.

✨ SYNOPSIS ✨

realmctl [options]

🌸 DESCRIPTION 🌸

so basically, realmctl sends commands to dtrealms, the DNSSEC-Tools realms daemon. in most cases, dtrealms will clap back with a response to realmctl. realmctl then prints a success or failure message, as appropriate, like the good little messenger she is. 💅

bestie, listen: only one option may be specified on a command line. one. that's the vibe check. don't be greedy. 🙈

🎀 OPTIONS 🎀

the following options are handled by realmctl. she's got range.

  • -allstart — starts all the suspended realms. wakey wakey, everyone up. ⭐
  • -allstop — stops all the running realms. nap time for the whole kingdom. 💤
  • -cmd -- realm cmd args — sends a command to the specified realm, iykyk. the command you give as cmd gets sent to the rollerd running inside realm realm.
  • -command -- realm cmd args — same energy as -cmd, just the longer, more dramatic spelling. sends a command to the specified realm, and the command given as cmd is sent to the rollerd running in realm realm.
✋ okay the double-dash shown up there is critical for proper argument parsing of the command line. like, do not skip it. she will simply not understand you without it. 💀

all the command-line arguments — that's the args up there — that come after the realm name and the command name will be sent as the command. whatever output the command gives gets returned to realmctl, who then prints that output. the command's return code will be appended to the command's output. and no attempt is made to analyze the output for success or failure — she's just the messenger, not a detective. 🕵️♀️

for example, this command tells the realm giant-isp to stop rollover of zone bob.example.com:

$ realmctl -command -- giant-isp rollctl -skipzone bob.example.com
Warning: this is an inherently dangerous command. bestie. when you're choosing the user under which the realm and rollover commands will be executed, be aware that this problem exists. realmctl may be modified in the future to restrict the commands that may be executed with this option. so like, be careful, fr fr. 😭
  • -display — starts the realms status GUI. ✨ pretty pixels ✨
  • -halt [now] — cleanly halts dtrealms execution. a graceful exit, the way a main character leaves a party. 👑
  • -logfile logfile — sets the dtrealms log file to logfile. this must be a valid logging file, meaning that if logfile already exists, it must be a regular file. the only exceptions to this are if logfile is /dev/stdout or /dev/tty. those two get a free pass, iconic behavior. 🎫
  • -loglevel loglevel — sets the dtrealms logging level to loglevel. this must be one of the valid logging levels defined in realmmgr.pm(3).

if a logging level is not specified, then the list of valid levels will be printed and realmctl will exit. the list is given in both text and numeric forms — she's thorough like that. 💅

  • -logtz logtz — sets the dtrealms logging timezone to loglevel (yes, that's genuinely what the original page says right here — typo era, but we keep the receipts). this must be either gmt (for Greenwich Mean Time) or local (for the host's local time). 🕐
  • -nodisplay — stops the realms status GUI. bye bye pixels. 🌈
  • -realmstatus — gets the current status of all the realms from dtrealms. for each realm, the name, execution status, and zone counts are printed. the zone counts are, in order: the number of zones in normal state, the number of zones in ZSK rollover, the number of zones in KSK rollover, and the number of zones waiting in KSK phase 6. those zone counts are determined by sending the realm's rollover manager an information request. therefore, if the zone is inactive, the zone counts are not included. no data, no drama. 🙅♀️

example:

dev     active     normal: 18   ZSK: 3   KSK: 1   KSK phase 6: 0
test-r  inactive
money   active     normal: 10   ZSK: 0   KSK: 0   KSK phase 6: 1
  • -shutdown — synonym for -halt. same girl, different name tag. 🫶
  • -startrealm realm — starts the suspended realm named by realm. multiple realms can be specified on the command line. for instance, this command sends the startrealm command to dtrealms for three realms:
$ realmctl -startrealm testing production customers
  • -status — has dtrealms write several of its operational parameters to its log file. the parameters are also reported to realmctl, who prints them to the screen. double the exposure, double the slay. ✨
  • -stoprealm realm — stops the realm named by realm. multiple realms can be specified on the command line. for instance, this command sends the stoprealm command to dtrealms for two realms:
$ realmctl -stoprealm big-isp-3 misc-customers
  • -Version — displays the version information for realmctl and the DNSSEC-Tools package. (capital V bestie, don't fumble it.) 👑
  • -quiet — prevents output from being given. both error and non-error output is stopped. silence, but make it intentional. 🤫
  • -help — displays a usage message. she's happy to explain herself. 💖

💀 EXIT CODES 💀

realmctl may give the following exit codes:

  1. 0 — Successful execution
  2. 1 — Error sending the command to dtrealms.
  3. 2 — Missing realm argument.
  4. 3 — Too many command options specified.
  5. 4 — Missing argument for -cmd or -command.
  6. 5 — No option specified.
  7. 200 — dtrealms is not running.
  8. 201 — Configuration file checks failed.

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

🦋 AUTHOR 🦋

Wayne Morrison, tewok@tislabs.com

🌈 SEE ALSO 🌈

Net::DNS::SEC::Tools::realmmgr.pm(3), Net::DNS::SEC::Tools::realm.pm(3)

dtrealms(8), rollctl(8) rollerd(8)

and that's the whole page, bestie — written by the perl girlies over at perl v5.42.0, dated 2025-07-23, filed under User Contributed Perl Documentation. go forth and command your realms. periodt. 💅✨

📦 where this page comes from