Net::DNS::SEC::Tools::tooloptions(3pm)

1tooloptions(3)        User Contributed Perl Documentation       tooloptions(3)
2
3
4

NAME

6       Net::DNS::SEC::Tools::tooloptions - DNSSEC-Tools option routines.
7

SYNOPSIS

9         use Net::DNS::SEC::Tools::tooloptions;
10
11         @specopts = ("propagate+", "waittime=i");
12
13         %opts = opts_cmdline($restoreargv,@calleropts);
14
15         $optsref = opts_cmdopts(@specopts);
16         %options = %$optsref;
17
18         $zoneref = opts_zonekr($keyrec_file,$keyrec_name,@specopts);
19         %zone_kr = %$zoneref;
20
21         opts_setcsopts(@specopts);
22
23         opts_createkrf();
24
25         opts_suspend();
26
27         opts_restore();
28
29         opts_drop();
30
31         opts_reset();
32
33         opts_gui();
34
35         opts_nogui();
36
37         $oldaction = opts_onerr(1);
38         opts_onerr(0);
39

DESCRIPTION

41       DNSSEC-Tools supports a set of options common to all the tools in the
42       suite.  These options may be set from DNSSEC-Tools defaults, values set
43       in the dnssec-tools.conf configuration file, in a keyrec file, from
44       command-specific options, from command-line options, or from any
45       combination of the five.  In order to enforce a common sequence of
46       option interpretation, all DNSSEC-Tools should use the tooloptions.pm
47       routines to initialize their options.
48
49       tooloptions.pm routines combine data from the aforementioned option
50       sources into a hash table.  The hash table is returned to the caller,
51       which will then use the options as needed.
52
53       The command-line options are saved between calls, so a command may call
54       tooloptions.pm routines multiple times and still have the command-line
55       options included in the final hash table.  This is useful for examining
56       multiple keyrecs in a single command.  Inclusion of command-line
57       options may be suspended and restored using the opts_suspend() and
58       opts_restore() calls.  Options may be discarded entirely by calling
59       opts_drop(); once dropped, command-line options may never be restored.
60       Suspension, restoration, and dropping of command-line options are only
61       effective after the initial tooloptions.pm call.
62
63       The options sources are combined in this order:
64
65       1.  DNSSEC-Tools Defaults
66           The DNSSEC-Tools defaults, as defined in conf.pm are put into a
67           hash table, with the option names as the hash key.
68
69       2.  DNSSEC-Tools Configuration File
70           The system-wide DNSSEC-Tools configuration file is read and these
71           option values are added to the option collection.  Again, the
72           option names are used as the hash key.
73
74       3. keyrec File
75           If a keyrec file was specified, then the keyrec named by
76           keyrec_name will be retrieved.  The keyrec's fields are added to
77           the hash table.  Any field whose keyword matches an existing hash
78           key will override any existing values.
79
80       4. Command-Specific Options
81           Options specific to the invoking commands may be specified in
82           @specopts.  This array is parsed by Getoptions() from the
83           Getopt::Long Perl module.  These options are folded into the hash
84           table; possibly overriding existing hash values.  The options given
85           in @specopts must be in the format required by Getoptions().
86
87       5. Command-Line Options
88           The command-line options are parsed using Getoptions() from the
89           Getopt::Long Perl module.  These options are folded into the hash
90           table; again, possibly overriding existing hash values.  The
91           options given in @specopts must be in the format required by
92           Getoptions().
93
94       A reference to the hash table created in these steps is returned to the
95       caller.
96

EXAMPLE

98       dnssec-tools.conf has these entries:
99
100           ksklength      2048
101           zsklength      1024
102
103       example.keyrec has this entry:
104
105           key         "Kexample.com.+005+12345"
106                   zsklength        "2048"
107
108       zonesigner is executed with this command line:
109
110           zonesigner -zsklength 4096 -wait 3600 ...  example.com
111
112       opts_zonekr("example.keyrec","Kexample.com.+005+12345",("wait=i")) will
113       read each option source in turn, ending up with:
114           ksklength          1024
115           zsklength          4096
116           wait                600
117

TOOLOPTIONS INTERFACES

119       opts_cmdline($restoreargv,@calleropts)
120           This routine parses a command line looking for the arguments in the
121           standard set of options and an optional set of options specified by
122           the caller.  If the first argument is true, the program-wide @ARGV
123           is restored after parsing.  If the caller provides other arguments,
124           they're added as additional options.  The parsed options are
125           returned to the caller in a hash.
126
127       opts_cmdopts(@csopts)
128           The opts_cmdopts() call builds an option hash from the system
129           configuration file, a keyrec, and a set of command-specific
130           options.  A reference to this option hash is returned to the
131           caller.
132
133           If $keyrec_file is given as an empty string, then no keyrec file
134           will be consulted.  In this case, it is assumed that $keyrec_name
135           will be left out altogether.
136
137           If a non-existent $keyrec_file is given and opts_createkrf() has
138           been called, then the named keyrec file will be created.
139           opts_createkrf() must be called for each keyrec file that must be
140           created, as the tooloptions keyrec-creation state is reset after
141           tooloptions() has completed.
142
143       opts_zonekr($keyrec_file,$keyrec_name,@csopts)
144           This routine returns a reference to options gathered from the basic
145           option sources and from the zone keyrec named by $keyrec_name,
146           which is found in $keyrec_file.  The keyrec fields from the zone's
147           KSK and ZSK are folded in as well, but the key's keyrec_ fields are
148           excluded.  This call ensures that the named keyrec is a zone
149           keyrec; if it isn't, undef is returned.
150
151           The keyrec file is read with keyrec_read().  To ensure it is
152           properly read, keyrec_close() is called first.
153
154           The $keyrec_file argument specifies a keyrec file that will be
155           consulted.  The keyrec named by the $keyrec_name argument will be
156           loaded.  If a keyrec file is found and opts_createkrf() has been
157           previously called, then the keyrec file will be created if it
158           doesn't exist.
159
160           If $keyrec_file is given as "", then the command-line options are
161           searched for a -krfile option.  If $keyrec_name is given as "",
162           then the name is taken from $ARGV[0].
163
164           The @specopts array contains command-specific arguments; the
165           arguments must be in the format prescribed by the Getopt::Long Perl
166           module.
167
168           If the command line contains the -dtconfig option, then
169           opts_zonekr() sets that option to be the configuration file.  It
170           then parses that file and uses it as the source for configuration
171           file data.
172
173       opts_setcsopts(@csopts)
174           This routine saves a copy of the command-specific options given in
175           @csopts.  This collection of options is added to the @csopts array
176           that may be passed to tooloptions.pm routines.
177
178       opts_createkrf()
179           Force creation of an empty keyrec file if the specified file does
180           not exist.  This may happen on calls to opts_zonekr().
181
182       opts_suspend()
183           Suspend inclusion of the command-line options in building the final
184           hash table of responses.
185
186       opts_restore()
187           Restore inclusion of the command-line options in building the final
188           hash table of responses.
189
190       opts_drop()
191           Discard the command-line options.  They will no longer be available
192           for inclusion in building the final hash table of responses for
193           this execution of the command.
194
195       opts_reset()
196           Reset an internal flag so that the command-line arguments may be
197           re-examined.  This is usually only useful if the arguments have
198           been modified by the calling program itself.
199
200       opts_gui()
201           Set an internal flag so that command arguments may be specified
202           with a GUI.  GUI usage requires that Getopt::GUI::Long is
203           available.  If it isn't, then Getopt::Long will be used.
204
205       opts_nogui()
206           Set an internal flag so that the GUI will not be used for
207           specifying command arguments.
208
209       opts_onerr(exitflag)
210           Set an internal flag indicating what should happen if an invalid
211           option is specified on the command line.  If exitflag is non-zero,
212           then the process will exit on an invalid option; if it is zero,
213           then the process will not exit.  The default action is to report an
214           error without exiting.
215
216           The old exit action is returned.
217

COPYRIGHT

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

AUTHOR

223       Wayne Morrison, tewok@tislabs.com
224