.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "conf 3pm"
.TH conf 3pm "2012-06-28" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::DNS::SEC::Tools::conf \- DNSSEC\-Tools configuration routines.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::DNS::SEC::Tools::conf;
\&
\&  %dtconf = parseconfig();
\&
\&  %dtconf = parseconfig("localzone.keyrec");
\&
\&  cmdcheck(\e%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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The routines in this module perform configuration operations.  Some routines
access the DNSSEC-Tools configuration file, while others validate the
execution environment.
.PP
The \s-1DNSSEC\s0 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 \fBNet::DNS::SEC::Tools::conf\fR module provides
methods for accessing the configuration data in this file.
.PP
\&\fBdnssec\-tools.conf\fR is the filename for the \s-1DNSSEC\s0 tools configuration file.
The full path depends on how DNSSEC-Tools was configured; see the \s-1DIRECTORIES\s0
section for the complete path.  The paths required by \fBconf.pm\fR are set at
DNSSEC-Tools configuration time.
.PP
The \s-1DNSSEC\s0 tools configuration file consists of a set of configuration value
entries, with only one entry per line.  Each entry has the \*(L"keyword value\*(R"
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.
.PP
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.
.PP
An example configuration file follows:
.PP
.Vb 1
\&    # Sample configuration entries.
\&
\&    algorithm       rsasha1     # Encryption algorithm.
\&    ksk_length      2048        ; KSK key length.
.Ve
.PP
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 \s-1STDERR\s0, or print an
error message and exit.  The \fI\fIerraction()\fI\fR and \fI\fIerr()\fI\fR interfaces are used
for these operations.
.SH "INTERFACES"
.IX Header "INTERFACES"
.IP "\fIdt_confcheck(errflag)\fR" 4
.IX Item "dt_confcheck(errflag)"
This routine performs a number of configuration checks to ensure the
environment is sufficient to support the DNSSEC-Tools configuration.
If \fIerrflag\fR is 0, then the checks are performed quietly; otherwise,
error messages will be printed.
.Sp
The checks are:
.Sp
.Vb 10
\&        * 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\*(Aqt empty.
\&        * The local state directory name isn\*(Aqt 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\*(Aqs dnssec\-tools subdirectory
\&          can be created if necessary, or is writable if it
\&          already exists.
\&        * The local state directory\*(Aqs run subdirectory
\&          can be created if necessary, or is writable if it
\&          already exists.
.Ve
.Sp
Return Values:
.Sp
.Vb 2
\&        0       no errors were found
\&        >0      some number of configuration checks failed
.Ve
.IP "\fI\fIparseconfig()\fI\fR" 4
.IX Item "parseconfig()"
This routine reads and parses the system's \s-1DNSSEC\s0 tools configuration file.
The parsed contents are put into a hash table, which is returned to the caller.
.IP "\fIparseconfig(conffile)\fR" 4
.IX Item "parseconfig(conffile)"
This routine reads and parses a caller-specified \s-1DNSSEC\s0 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.
.IP "\fIcmdcheck(\e%options_hashref)\fR" 4
.IX Item "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.
.Sp
The commands keys currently checked are \fIzonecheck\fR, \fIkeygen\fR, and
\&\fIzonesign\fR.  The pathnames for these commands are found in the given options
hash referenced by \fI\f(CI%options_hashref\fI\fR.  If the hash doesn't contain an entry
for one of those commands, it is not checked.
.Sp
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 \s-1PAR\s0 appears to ignore file modes when packaging programs.
.IP "\fI\fIgetconfdir()\fI\fR" 4
.IX Item "getconfdir()"
This routine returns the name of the DNSSEC-Tools configuration directory.
.IP "\fI\fIgetconffile()\fI\fR" 4
.IX Item "getconffile()"
This routine returns the name of the DNSSEC-Tools configuration file.
.IP "\fI\fIsetconffile()\fI\fR" 4
.IX Item "setconffile()"
This routine sets the name of the DNSSEC-Tools configuration file.
.Sp
Return values:
    1	returned on success
    0	returned if the specified configuration file does not
          exist or is not a regular file
.IP "\fI\fIgetprefixdir()\fI\fR" 4
.IX Item "getprefixdir()"
This routine returns the name of the DNSSEC-Tools prefix directory.
.IP "\fI\fIgetlocalstatedir()\fI\fR" 4
.IX Item "getlocalstatedir()"
This routine returns the name of the local state directory.
.IP "\fI\fIrunpacked()\fI\fR" 4
.IX Item "runpacked()"
This routine returns a boolean indicating if the executing command is running
from a PAR-packed script.
.IP "\fImakelocalstatedir(subdir)\fR" 4
.IX Item "makelocalstatedir(subdir)"
This routine makes the local state directory and returns its name.  The
directory is created only if it doesn't exist already.
.Sp
If the optional \fIsubdir\fR subdirectory is specified, then that directory is
created within the local state directory.  In this case, the path of \fIsubdir\fR
is returned.  \fIsubdir\fR may consist of several intermediate directories, as
well as the terminal directory.  For example,
\&\fImakelocalstatedir(\*(L"logs/zones/errors\*(R")\fR will create the \fBlogs/zones/errors\fR
hierarchy within the local state directory.
.Sp
\&\fImakelocalstatedir(subdir)\fR uses the \fIFile::Path\fR module, which is available
on all modern Perl versions.
.Sp
An empty string is returned if there are any errors.  The following errors may
be encountered:
.Sp
.Vb 5
\&    * 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
.Ve
.IP "\fIboolconvert(config\-value)\fR" 4
.IX Item "boolconvert(config-value)"
This routine converts configuration values into appropriate boolean values.
The following text conversions are made:
.Sp
.Vb 2
\&    1 \- \*(Aqtrue\*(Aq, \*(Aqt\*(Aq, \*(Aqyes\*(Aq, \*(Aqy\*(Aq
\&    0 \- \*(Aqfalse\*(Aq, \*(Aqf\*(Aq, \*(Aqno\*(Aq, \*(Aqn\*(Aq
.Ve
.Sp
All other text values are converted to 0.
.Sp
Positive values are converted to 1.  Negative values are converted to 0.
.IP "\fIerraction(error_action)\fR" 4
.IX Item "erraction(error_action)"
This interface sets the error action for DNSSEC-Tools Perl modules.
The valid actions are:
.Sp
.Vb 3
\&    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.
.Ve
.Sp
\&\s-1ERR_SILENT\s0 is the default action.
.Sp
The previously set error action is returned.
.ie n .IP "\fIerr(""error message"",exit_code)\fR" 4
.el .IP "\fIerr(``error message'',exit_code)\fR" 4
.IX Item "err(error message,exit_code)"
The \fI\fIerr()\fI\fR interface is used by the DNSSEC-Tools Perl modules to report
an error and exit, depending on the error action.
.Sp
The first argument is an error message to print \*(-- if the error action allows
error messages to be printed.
.Sp
The second argument is an exit code \*(-- if the error action requires that the
process exit.
.SH "DIRECTORIES"
.IX Header "DIRECTORIES"
The default directories for this installation are:
.PP
.Vb 3
\&  prefix                         : /usr
\&  sysconf                        : /etc
\&  localstatedir                  : /var
\&
\&  DNSSEC\-Tools configuration file: /etc/dnssec\-tools
.Ve
.PP
These can be overridden using the following environmental variables:
.PP
.Vb 3
\&  prefix                         : DT_PREFIX
\&  sysconf                        : DT_SYSCONFDIR
\&  localstatedir                  : DT_STATEDIR
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004\-2012 \s-1SPARTA\s0, Inc.  All rights reserved.
See the \s-1COPYING\s0 file included with the DNSSEC-Tools package for details.
.SH "AUTHOR"
.IX Header "AUTHOR"
Wayne Morrison, tewok@tislabs.com
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fB\f(BIdnssec\-tools.conf\fB\|(5)\fR