NAME¶
Net::DNS::SEC::Tools::conf - DNSSEC-Tools configuration routines.
SYNOPSIS¶
use Net::DNS::SEC::Tools::conf;
%dtconf = parseconfig();
%dtconf = parseconfig("localzone.keyrec");
cmdcheck(\%options_hashref);
$conferrs = dt_confcheck();
$prefixdir = getprefixdir();
$confdir = getconfdir();
$conffile = getconffile();
setconffile("dt-local.conf");
$statedir = getlocalstatedir();
$statedir = makelocalstatedir();
$statesub = makelocalstatedir("logs/zones");
$packed = runpacked();
erraction(ERR_MSG);
err("unable to open keyrec file",1);
DESCRIPTION¶
The routines in this module perform configuration operations. Some routines
access the DNSSEC-Tools configuration file, while others validate the
execution environment.
The DNSSEC tools have a configuration file for commonly used values. These
values are the defaults for a variety of things, such as encryption algorithm
and encryption key length. The
Net::DNS::SEC::Tools::conf module
provides methods for accessing the configuration data in this file.
dnssec-tools.conf is the filename for the DNSSEC tools configuration
file. The full path depends on how DNSSEC-Tools was configured; see the
DIRECTORIES section for the complete path. The paths required by
conf.pm are set at DNSSEC-Tools configuration time.
The DNSSEC tools configuration file consists of a set of configuration value
entries, with only one entry per line. Each entry has the "keyword
value" format. During parsing, the line is broken into tokens, with
tokens being separated by spaces and tabs. The first token in a line is taken
to be the keyword. All other tokens in that line are concatenated into a
single string, with a space separating each token. The untokenized string is
added to a hash table, with the keyword as the value's key.
Comments may be included by prefacing them with the '#' or ';' comment
characters. These comments can encompass an entire line or may follow a
configuration entry. If a comment shares a line with an entry, value
tokenization stops just prior to the comment character.
An example configuration file follows:
# Sample configuration entries.
algorithm rsasha1 # Encryption algorithm.
ksk_length 2048 ; KSK key length.
Another aspect of DNSSEC-Tools configuration is the error action used by the
DNSSEC-Tools Perl modules. The action dictates whether an error condition will
only give an error return, print an error message to STDERR, or print an error
message and exit. The
erraction() and
err() interfaces are used for these operations.
INTERFACES¶
- dt_confcheck(errflag)
- This routine performs a number of configuration checks to
ensure the environment is sufficient to support the DNSSEC-Tools
configuration. If errflag is 0, then the checks are performed
quietly; otherwise, error messages will be printed.
The checks are:
* The dnssec-tools sysconf directory exists.
* The dnssec-tools sysconf directory is a directory.
* The dnssec-tools directory exists.
* The dnssec-tools directory is a directory.
* The dnssec-tools config file exists.
* The dnssec-tools config file is a regular file.
* The dnssec-tools config file isn't empty.
* The local state directory name isn't longer than 75
characters (to allow for the rollmgr command socket.)
* The local state directory is a directory.
* The local state directory can be created if necessary.
* The local state directory's dnssec-tools subdirectory
can be created if necessary, or is writable if it
already exists.
* The local state directory's run subdirectory
can be created if necessary, or is writable if it
already exists.
Return Values:
0 no errors were found
>0 some number of configuration checks failed
- parseconfig()
- This routine reads and parses the system's DNSSEC tools
configuration file. The parsed contents are put into a hash table, which
is returned to the caller.
- parseconfig(conffile)
- This routine reads and parses a caller-specified DNSSEC
tools configuration file. The parsed contents are put into a hash table,
which is returned to the caller. The routine quietly returns if the
configuration file does not exist.
- cmdcheck(\%options_hashref)
- This routine ensures that the needed commands are available
and executable. If any of the commands either don't exist or aren't
executable, then an error message will be given and the process will exit.
If all is well, everything will proceed quietly onwards.
The commands keys currently checked are zonecheck, keygen, and
zonesign. The pathnames for these commands are found in the given
options hash referenced by %options_hashref. If the
hash doesn't contain an entry for one of those commands, it is not
checked.
If this routine is called from a PAR-packed script, then it will look in the
package directory for the commands. It will also set their file modes to
0755, as PAR appears to ignore file modes when packaging programs.
- getconfdir()
- This routine returns the name of the DNSSEC-Tools
configuration directory.
- getconffile()
- This routine returns the name of the DNSSEC-Tools
configuration file.
- setconffile()
- This routine sets the name of the DNSSEC-Tools
configuration file.
Return values:
1 returned on success
0 returned if the specified configuration file does not
exist or is not a regular file
- getprefixdir()
- This routine returns the name of the DNSSEC-Tools prefix
directory.
- getlocalstatedir()
- This routine returns the name of the local state
directory.
- runpacked()
- This routine returns a boolean indicating if the executing
command is running from a PAR-packed script.
- makelocalstatedir(subdir)
- This routine makes the local state directory and returns
its name. The directory is created only if it doesn't exist already.
If the optional subdir subdirectory is specified, then that directory
is created within the local state directory. In this case, the path of
subdir is returned. subdir may consist of several
intermediate directories, as well as the terminal directory. For example,
makelocalstatedir("logs/zones/errors") will create the
logs/zones/errors hierarchy within the local state directory.
makelocalstatedir(subdir) uses the File::Path module, which
is available on all modern Perl versions.
An empty string is returned if there are any errors. The following errors
may be encountered:
* I<File::Path> could not be loaded
* Unable to create the local state directory
* Unable to create a component of I<subdir>
* Full path (local state directory and I<subdir>) already
exists and is not a directory
- boolconvert(config-value)
- This routine converts configuration values into appropriate
boolean values. The following text conversions are made:
1 - 'true', 't', 'yes', 'y'
0 - 'false', 'f', 'no', 'n'
All other text values are converted to 0.
Positive values are converted to 1. Negative values are converted to 0.
- erraction(error_action)
- This interface sets the error action for DNSSEC-Tools Perl
modules. The valid actions are:
ERR_SILENT Do not print an error message, do not exit.
ERR_MSG Print an error message, do not exit.
ERR_EXIT Print an error message, exit.
ERR_SILENT is the default action.
The previously set error action is returned.
- err("error message",exit_code)
- The err() interface is used by the
DNSSEC-Tools Perl modules to report an error and exit, depending on the
error action.
The first argument is an error message to print -- if the error action
allows error messages to be printed.
The second argument is an exit code -- if the error action requires that the
process exit.
DIRECTORIES¶
The default directories for this installation are:
prefix : /usr
sysconf : /etc
localstatedir : /var
DNSSEC-Tools configuration file: /etc/dnssec-tools
These can be overridden using the following environmental variables:
prefix : DT_PREFIX
sysconf : DT_SYSCONFDIR
localstatedir : DT_STATEDIR
COPYRIGHT¶
Copyright 2004-2012 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¶
dnssec-tools.conf(5)