Provided by: dnssec-tools_2.0-1_all bug

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-2013 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)