tooloptions(3)

📦
version 2.2.3 · 3 versions
, in arch rolling

💖 NAME 💖

okay so bestie, welcome to tooloptions(3) from the User Contributed Perl Documentation — and it's literally Net::DNS::SEC::Tools::tooloptions, aka the DNSSEC-Tools option routines. slay.

✨ SYNOPSIS ✨

here's the whole vibe in code:

  use Net::DNS::SEC::Tools::tooloptions;

  @specopts = ("propagate+", "waittime=i");

  %opts = opts_cmdline($restoreargv,@calleropts);

  $optsref = opts_cmdopts(@specopts);
  %options = %$optsref;

  $zoneref = opts_zonekr($keyrec_file,$keyrec_name,@specopts);
  %zone_kr = %$zoneref;

  opts_setcsopts(@specopts);

  opts_createkrf();

  opts_suspend();

  opts_restore();

  opts_drop();

  opts_reset();

  opts_gui();

  opts_nogui();

  $oldaction = opts_onerr(1);
  opts_onerr(0);

🌸 DESCRIPTION 🌸

okay so DNSSEC-Tools has a set of options that every tool in the suite shares. bestie, these can come from DNSSEC-Tools defaults, values set in the dnssec-tools.conf configuration file, a keyrec file, command-specific options, command-line options, or literally any combo of those five. and to keep the option interpretation order consistent, every DNSSEC-Tools thing should use the tooloptions.pm routines to init its options. periodt.

the tooloptions.pm routines smash all that data from those option sources into a hash table, and the hash table gets returned to whoever called it, who then uses the options however they need. iconic.

the command-line options are saved between calls, so a command can call the tooloptions.pm routines multiple times and still have the command-line options show up in the final hash table. this is lowkey useful for examining multiple keyrecs in a single command. you can suspend including command-line options and bring them back with the opts_suspend() and opts_restore() calls. and you can discard them entirely with opts_drop() — but bestie, once they're dropped, command-line options may never be restored 😭.

also, suspending, restoring, and dropping command-line options are only effective after the initial tooloptions.pm call. no cap.

the option sources get combined in this exact order, iykyk:

  1. DNSSEC-Tools Defaults — the DNSSEC-Tools defaults, as defined in conf.pm, get put into a hash table, with the option names as the hash key. ✨
  2. DNSSEC-Tools Configuration File — the system-wide DNSSEC-Tools configuration file is read, and these option values get added to the option collection. again, the option names are the hash key.
  3. keyrec File — if a keyrec file was specified, then the keyrec named by keyrec_name gets retrieved. the keyrec's fields are added to the hash table. any field whose keyword matches an existing hash key will override any existing values. slay.
  4. Command-Specific Options — options specific to the invoking commands may be specified in @specopts. this array is parsed by Getoptions() from the Getopt::Long Perl module. these options get folded into the hash table — possibly overriding existing hash values. the options given in @specopts must be in the format required by Getoptions().
  5. Command-Line Options — the command-line options are parsed using Getoptions() from the Getopt::Long Perl module. these options get folded into the hash table; again, possibly overriding existing hash values. the options given in @specopts must be in the format required by Getoptions().

and a reference to the hash table created in these steps is returned to the caller. that's the whole point. 💅

🎀 EXAMPLE 🎀

okay imagine dnssec-tools.conf has these entries:

ksklength      2048
zsklength      1024

and example.keyrec has this entry:

key         "Kexample.com.+005+12345"
        zsklength        "2048"

zonesigner is executed with this command line:

zonesigner -zsklength 4096 -wait 3600 ...  example.com

then opts_zonekr("example.keyrec","Kexample.com.+005+12345",("wait=i")) will read each option source in turn, ending up with:

ksklength          1024
zsklength          4096
wait                600

💅 TOOLOPTIONS INTERFACES 💅

opts_cmdline($restoreargv,@calleropts)

this routine parses a command line looking for the arguments in the standard set of options and an optional set of options specified by the caller. if the first argument is true, the program-wide @ARGV is restored after parsing. if the caller provides other arguments, they're added as additional options. the parsed options are returned to the caller in a hash. cute.

opts_cmdopts(@csopts)

the opts_cmdopts() call builds an option hash from the system configuration file, a keyrec, and a set of command-specific options. a reference to this option hash is returned to the caller.

if $keyrec_file is given as an empty string, then no keyrec file will be consulted. in this case, it's assumed that $keyrec_name will be left out altogether.

if a non-existent $keyrec_file is given and opts_createkrf() has been called, then the named keyrec file will be created. opts_createkrf() must be called for each keyrec file that must be created, because the tooloptions keyrec-creation state is reset after tooloptions() has completed. no skipping. 💅

opts_zonekr($keyrec_file,$keyrec_name,@csopts)

this routine returns a reference to options gathered from the basic option sources and from the zone keyrec named by $keyrec_name, which is found in $keyrec_file. the keyrec fields from the zone's KSK and ZSK are folded in as well, but the key's keyrec_ fields are excluded. this call ensures that the named keyrec is a zone keyrec; if it isn't, undef is returned. periodt.

the keyrec file is read with keyrec_read(). to ensure it is properly read, keyrec_close() is called first.

the $keyrec_file argument specifies a keyrec file that will be consulted. the keyrec named by the $keyrec_name argument will be loaded. if a keyrec file is found and opts_createkrf() has been previously called, then the keyrec file will be created if it doesn't exist.

if $keyrec_file is given as "", then the command-line options are searched for a -krfile option. if $keyrec_name is given as "", then the name is taken from $ARGV[0].

the @specopts array contains command-specific arguments; the arguments must be in the format prescribed by the Getopt::Long Perl module.

if the command line contains the -dtconfig option, then opts_zonekr() sets that option to be the configuration file. it then parses that file and uses it as the source for configuration file data.

opts_setcsopts(@csopts)

this routine saves a copy of the command-specific options given in @csopts. this collection of options is added to the @csopts array that may be passed to tooloptions.pm routines. slay.

opts_createkrf()

force creation of an empty keyrec file if the specified file does not exist. this may happen on calls to opts_zonekr(). 💅

opts_suspend()

suspend inclusion of the command-line options in building the final hash table of responses. bye for now.

opts_restore()

restore inclusion of the command-line options in building the final hash table of responses. welcome back bestie.

opts_drop()

discard the command-line options. they will no longer be available for inclusion in building the final hash table of responses for this execution of the command. and yes, this is the one where they're gone 😭.

opts_reset()

reset an internal flag so that the command-line arguments may be re-examined. this is usually only useful if the arguments have been modified by the calling program itself. iykyk.

opts_gui()

set an internal flag so that command arguments may be specified with a GUI. GUI usage requires that Getopt::GUI::Long is available. if it isn't, then Getopt::Long will be used. no drama.

opts_nogui()

set an internal flag so that the GUI will not be used for specifying command arguments. bye GUI.

opts_onerr(exitflag)

set an internal flag indicating what should happen if an invalid option is specified on the command line. if exitflag is non-zero, then the process will exit on an invalid option; if it is zero, then the process will not exit. the default action is to report an error without exiting.

the old exit action is returned. iconic.

Copyright 2005-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 🌈

mwah 💋 — this page is from perl v5.44.0, dated 2026-10-17, and it's tooloptions(3). periodt. 🫶

📦 where this page comes from