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         $optsref = opts_cmdopts(@specopts);
14         %options = %$optsref;
15
16         $zoneref = opts_zonekr($keyrec_file,$keyrec_name,@specopts);
17         %zone_kr = %$zoneref;
18
19         opts_setcsopts(@specopts);
20
21         opts_createkrf();
22
23         opts_suspend();
24
25         opts_restore();
26
27         opts_drop();
28
29         opts_reset();
30
31         opts_gui();
32
33         opts_nogui();
34
35         $oldaction = opts_onerr(1);
36         opts_onerr(0);
37

DESCRIPTION

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

EXAMPLE

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

TOOLOPTIONS INTERFACES

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

COPYRIGHT

209       Copyright 2005-2011 SPARTA, Inc.  All rights reserved.  See the COPYING
210       file included with the DNSSEC-Tools package for details.
211

AUTHOR

213       Wayne Morrison, tewok@users.sourceforge.net
214