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

NAME

6       Net::DNS::SEC::Tools::conf - DNSSEC-Tools configuration routines.
7

SYNOPSIS

9         use Net::DNS::SEC::Tools::conf;
10
11         %dtconf = parseconfig();
12
13         %dtconf = parseconfig("localzone.keyrec");
14
15         cmdcheck(\%options_hashref);
16
17         $conferrs = dt_confcheck();
18
19         $prefixdir = getprefixdir();
20
21         $confdir = getconfdir();
22
23         $conffile = getconffile();
24
25         setconffile("dt-local.conf");
26
27         $statedir = getlocalstatedir();
28
29         $statedir = makelocalstatedir();
30         $statesub = makelocalstatedir("logs/zones");
31
32
33         $packed = runpacked();
34
35         erraction(ERR_MSG);
36         err("unable to open keyrec file",1);
37

DESCRIPTION

39       The routines in this module perform configuration operations.  Some
40       routines access the DNSSEC-Tools configuration file, while others
41       validate the execution environment.
42
43       The DNSSEC tools have a configuration file for commonly used values.
44       These values are the defaults for a variety of things, such as
45       encryption algorithm and encryption key length.  The
46       Net::DNS::SEC::Tools::conf module provides methods for accessing the
47       configuration data in this file.
48
49       dnssec-tools.conf is the filename for the DNSSEC tools configuration
50       file.  The full path depends on how DNSSEC-Tools was configured; see
51       the DIRECTORIES section for the complete path.  The paths required by
52       conf.pm are set at DNSSEC-Tools configuration time.
53
54       The DNSSEC tools configuration file consists of a set of configuration
55       value entries, with only one entry per line.  Each entry has the
56       "keyword value" format.  During parsing, the line is broken into
57       tokens, with tokens being separated by spaces and tabs.  The first
58       token in a line is taken to be the keyword.  All other tokens in that
59       line are concatenated into a single string, with a space separating
60       each token.  The untokenized string is added to a hash table, with the
61       keyword as the value's key.
62
63       Comments may be included by prefacing them with the '#' or ';' comment
64       characters.  These comments can encompass an entire line or may follow
65       a configuration entry.  If a comment shares a line with an entry, value
66       tokenization stops just prior to the comment character.
67
68       An example configuration file follows:
69
70           # Sample configuration entries.
71
72           algorithm       rsasha1     # Encryption algorithm.
73           ksk_length      2048        ; KSK key length.
74
75       Another aspect of DNSSEC-Tools configuration is the error action used
76       by the DNSSEC-Tools Perl modules.  The action dictates whether an error
77       condition will only give an error return, print an error message to
78       STDERR, or print an error message and exit.  The erraction() and err()
79       interfaces are used for these operations.
80

INTERFACES

82       dt_confcheck(errflag)
83           This routine performs a number of configuration checks to ensure
84           the environment is sufficient to support the DNSSEC-Tools
85           configuration.  If errflag is 0, then the checks are performed
86           quietly; otherwise, error messages will be printed.
87
88           The checks are:
89
90                   * The dnssec-tools sysconf directory exists.
91                   * The dnssec-tools sysconf directory is a directory.
92                   * The dnssec-tools directory exists.
93                   * The dnssec-tools directory is a directory.
94                   * The dnssec-tools config file exists.
95                   * The dnssec-tools config file is a regular file.
96                   * The dnssec-tools config file isn't empty.
97                   * The local state directory name isn't longer than 75
98                     characters (to allow for the rollmgr command socket.)
99                   * The local state directory is a directory.
100                   * The local state directory can be created if necessary.
101                   * The local state directory's dnssec-tools subdirectory
102                     can be created if necessary, or is writable if it
103                     already exists.
104                   * The local state directory's run subdirectory
105                     can be created if necessary, or is writable if it
106                     already exists.
107
108           Return Values:
109
110                   0       no errors were found
111                   >0      some number of configuration checks failed
112
113       parseconfig()
114           This routine reads and parses the system's DNSSEC tools
115           configuration file.  The parsed contents are put into a hash table,
116           which is returned to the caller.
117
118       parseconfig(conffile)
119           This routine reads and parses a caller-specified DNSSEC tools
120           configuration file.  The parsed contents are put into a hash table,
121           which is returned to the caller.  The routine quietly returns if
122           the configuration file does not exist.
123
124       cmdcheck(\%options_hashref)
125           This routine ensures that the needed commands are available and
126           executable.  If any of the commands either don't exist or aren't
127           executable, then an error message will be given and the process
128           will exit.  If all is well, everything will proceed quietly
129           onwards.
130
131           The commands keys currently checked are zonecheck, keygen, and
132           zonesign.  The pathnames for these commands are found in the given
133           options hash referenced by %options_hashref.  If the hash doesn't
134           contain an entry for one of those commands, it is not checked.
135
136           If this routine is called from a PAR-packed script, then it will
137           look in the package directory for the commands.  It will also set
138           their file modes to 0755, as PAR appears to ignore file modes when
139           packaging programs.
140
141       getconfdir()
142           This routine returns the name of the DNSSEC-Tools configuration
143           directory.
144
145       getconffile()
146           This routine returns the name of the DNSSEC-Tools configuration
147           file.
148
149       setconffile()
150           This routine sets the name of the DNSSEC-Tools configuration file.
151
152           Return values:
153               1     returned on success
154               0     returned if the specified configuration file does not
155                     exist or is not a regular file
156
157       getprefixdir()
158           This routine returns the name of the DNSSEC-Tools prefix directory.
159
160       getlocalstatedir()
161           This routine returns the name of the local state directory.
162
163       runpacked()
164           This routine returns a boolean indicating if the executing command
165           is running from a PAR-packed script.
166
167       makelocalstatedir(subdir)
168           This routine makes the local state directory and returns its name.
169           The directory is created only if it doesn't exist already.
170
171           If the optional subdir subdirectory is specified, then that
172           directory is created within the local state directory.  In this
173           case, the path of subdir is returned.  subdir may consist of
174           several intermediate directories, as well as the terminal
175           directory.  For example, makelocalstatedir("logs/zones/errors")
176           will create the logs/zones/errors hierarchy within the local state
177           directory.
178
179           makelocalstatedir(subdir) uses the File::Path module, which is
180           available on all modern Perl versions.
181
182           An empty string is returned if there are any errors.  The following
183           errors may be encountered:
184
185               * I<File::Path> could not be loaded
186               * Unable to create the local state directory
187               * Unable to create a component of I<subdir>
188               * Full path (local state directory and I<subdir>) already
189                 exists and is not a directory
190
191       boolconvert(config-value)
192           This routine converts configuration values into appropriate boolean
193           values.  The following text conversions are made:
194
195               1 - 'true', 't', 'yes', 'y'
196               0 - 'false', 'f', 'no', 'n'
197
198           All other text values are converted to 0.
199
200           Positive values are converted to 1.  Negative values are converted
201           to 0.
202
203       erraction(error_action)
204           This interface sets the error action for DNSSEC-Tools Perl modules.
205           The valid actions are:
206
207               ERR_SILENT          Do not print an error message, do not exit.
208               ERR_MSG             Print an error message, do not exit.
209               ERR_EXIT            Print an error message, exit.
210
211           ERR_SILENT is the default action.
212
213           The previously set error action is returned.
214
215       err("error message",exit_code)
216           The err() interface is used by the DNSSEC-Tools Perl modules to
217           report an error and exit, depending on the error action.
218
219           The first argument is an error message to print -- if the error
220           action allows error messages to be printed.
221
222           The second argument is an exit code -- if the error action requires
223           that the process exit.
224

DIRECTORIES

226       The default directories for this installation are:
227
228         prefix                         : /usr
229         sysconf                        : /etc
230         localstatedir                  : /var
231
232         DNSSEC-Tools configuration file: /etc/dnssec-tools
233
234       These can be overridden using the following environmental variables:
235
236         prefix                         : DT_PREFIX
237         sysconf                        : DT_SYSCONFDIR
238         localstatedir                  : DT_STATEDIR
239
241       Copyright 2004-2014 SPARTA, Inc.  All rights reserved.  See the COPYING
242       file included with the DNSSEC-Tools package for details.
243

AUTHOR

245       Wayne Morrison, tewok@tislabs.com
246

SEE ALSO

248       dnssec-tools.conf(5)
249
250
251
252perl v5.38.0                      2023-07-19                           conf(3)
Impressum