#!/usr/bin/perl
#
# Copyright 2005-2013 SPARTA, Inc.  All rights reserved.  See the COPYING
# file distributed with this software for details
#
#
# dnssec-tools.conf.pm
#
#	This script does nothing but provide a container for documentation
#	on the dnssec-tools.conf file.
#

1;

##############################################################################
#

=pod

=head1 NAME

    dnssec-tools.conf - Configuration file for the DNSSEC-Tools programs.

=head1 DESCRIPTION

This file contains configuration information for the DNSSEC-Tools programs.
These configuration data are used if nothing else has been specified for a
particular program.  The B<conf.pm> module is used to parse this configuration
file.

The recognized configuration fields are described in the Configuration Records
section below.  Some configuration entries are optional and a configuration
file need not contain a complete list of entries.

A line in the configuration file contains either a comment or a configuration
entry.  Comment lines start with either a '#' character or a ';' character.
Comment lines and blank lines are ignored by the DNSSEC-Tools programs.

Configuration entries are in a I<keyword/value> format.  The keyword is a
character string that contains no whitespace.  The value is a tokenized list
of the remaining character groups, with each token separated by a single space.

True/false flags must be given a B<1> (true) or B<0> (false) value.

=head1 Configuration Records

The following records are recognized by the DNSSEC-Tools programs.
Not every DNSSEC-Tools program requires each of these records.

=over 4

=item admin-email

The email address for the DNSSEC-Tools administrator.

=item algorithm

The default encryption algorithm to be passed to B<dnssec-keygen>.

=item archivedir

The pathname to the archived-key directory.

=item autosign

A true/false flag indicating if B<rollerd> should automatically sign
zonefiles that have been modified more recently than their signed versions.

=item default_keyrec

The default I<keyrec> filename to be used by the B<keyrec.pm> module.

=item endtime

The zone default expiration time to be passed to B<dnssec-signzone>.

=item entropy_msg

A true/false flag indicating if the B<zonesigner> command should display
a message about entropy generation.  This is primarily dependent on the
implementation of a system's random number generation.

=item genkrf

The path to the DNSSEC-Tools B<genkrf> command.

=item keyarch

The path to the DNSSEC-Tools B<keyarch> command.

=item keygen

The path to the B<dnssec-keygen> command.

=item keygen-opts

Options to pass to the B<dnssec-keygen> command.

=item kskcount

The default number of KSK keys that will be generated for each zone.

=item ksklength

The default KSK key length to be passed to B<dnssec-keygen>.

=item ksklife

The default length of time between KSK roll-overs.  This is measured in
seconds.

This value is B<only> used for key roll-over.  Keys do not have a life-time
in any other sense.

=item lifespan-max

The maximum length of time a key should be in use before it is rolled over.
This is measured in seconds.

=item lifespan-min

The minimum length of time a key should be in use before it is rolled over.
This is measured in seconds.

=item log_tz

The timezone to be used in log messages.  The value may be either 'gmt' (for
Greenwich Mean Time) or 'local' (for the host's local time.)

=item mailer-server

The mail server that will be contacted by I<dt_adminmail()>.  This is
passed to I<Mail::Send>.  The default value is B<localhost>.

=item mailer-type

The type of mailer that will be contacted by I<dt_adminmail()>.  This is
passed to I<Mail::Mailer> (by way of I<Mail::Send>.)  Any values recognized
by I<Mail::Mailer> may be used here.  The default value is B<stmp>.

=item prog-ksk1 ... prog-ksk7

A bang-separated list commands to run when a zone enters a particular KSK
rollover phase.  The programs can replace default rollover actions or be
executed in addition to the default actions.  The I<default> keyword must be
included if the default action should be taken.  Options and arguments may be
passed to non-default commands.

The default rollover action and requirements for user-written phase commands
are described in the documentation for B<rollerd>.

=item prog-normal

A bang-separated list commands to run when a zone enters the normal,
non-rollover phase.  The programs can replace default actions or be executed
in addition to the default actions.  The I<default> keyword must be included
if the default action should be taken.  Options and arguments may be passed to
non-default commands.

The default rollover action and requirements for user-written phase commands
are described in the documentation for B<rollerd>.

=item prog-zsk1 ... prog-zsk7

A bang-separated list commands to run when a zone enters a particular ZSK
rollover phase.  The programs can replace default rollover actions or be
executed in addition to the default actions.  The I<default> keyword must be
included if the default action should be taken.  Options and arguments may be
passed to non-default commands.

The default rollover action and requirements for user-written phase commands
are described in the documentation for B<rollerd>.

=item random

The random device generator to be passed to B<dnssec-keygen>.

=item rndc

The path to the B<rndc> command.

=item rndc-opts

Options to pass to the B<rndc> command.

=item roll_loadzone

A flag indicating if B<rollerd> should have the DNS daemon reload zones.

=item roll_logfile

The log file used by B<rollerd>.

=item roll_loglevel

The default logging level used by B<rollerd>.  The valid levels are defined
and described in I<rollmgr.pm>.


=item roll_phasemsg

The default length of phase-related log messages used by B<rollerd>.  The
valid levels are "long" and "short", with "long" being the default value.

The long message length means that a phase description will be included with
some log messages.  For example, the long form of a message about ZSK rollover
phase 3 will look like this:  "ZSK phase 3 (Waiting for old zone data to
expire from caches)".

The short message length means that a phase description will not be included
with some log messages.  For example, the short form of a message about ZSK
rollover phase 3 will look like this:  "ZSK phase 3".

=item roll_sleeptime

The number of seconds B<rollerd> must wait at the end of each zone-checking
cycle.

=item roll_username

The username that B<rollerd> will be run by.  The name will be converted to
its associated uid, and the effective uid of the B<rollerd> process will be
set to that uid.  This may be given as a user name or a uid.

=item rollctl

The path to the DNSSEC-Tools B<rollctl> command.

=item savekeys

A true/false flag indicating if old keys should be moved to the
archive directory.

=item usegui

Flag to allow/disallow usage of the GUI for specifying command options.

=item zonecheck

The path to the B<named-checkzone> command.

=item zonecheck-opts

Options to pass to the B<named-checkzone> command.

=item zone_errors

The maximum number of consecutive errors a zone may have.  When This is
exceeded, B<rollerd> will mark the zone as a I<skip> zone.  If this value is
zero, or isn't included in the file, then error conditions will not affect a
zone's I<roll/skip> status.  This may be overridden by the I<maxerrors> field
in a zone's entry in a I<rollrec> file.

=item zonefile-parser

The name of the Perl module that will be used to parse zone files.
This should be set without the B<.pm> suffix.
The default parser is B<Net::DNS::ZoneFile.pm>.

Older versions of B<Net::DNS::ZoneFile::Fast.pm> may be used, but more
recent versions have problems with DNSSEC records.

=item zonesign

The path to the B<dnssec-signzone> command.

=item zonesign-opts

Options to pass to the B<dnssec-signzone> command.

=item zonesigner

The path to the DNSSEC-Tools B<zonesigner> command.

=item zskcount

The default number of ZSK keys that will be generated for each zone.

=item zsklength

The default ZSK key length to be passed to B<dnssec-keygen>.

=item zsklife

The default length of time between ZSK roll-overs.  This is measured in
seconds.

This value is B<only> used for key roll-over.  Keys do not have a life-time
in any other sense.

=back

=head1 Sample Times

Several configuration fields measure various times.  This section is a
convenient reference for several common times, as measured in seconds.

    3600	- hour
    86400	- day
    604800	- week
    2592000	- 30-day month
    15768000	- half-year
    31536000	- year

=head1 Example File

The following is an example B<dnssec-tools.conf> configuration file.

    #
    # Settings for DNSSEC-Tools administration.
    #
    admin-email     tewok@squirrelking.net

    #
    # Paths to required programs.  These may need adjusting for
    # individual hosts.
    #
    keygen          /usr/local/sbin/dnssec-keygen
    rndc            /usr/local/sbin/rndc
    rndc-opts       -p 2288
    zonecheck       /usr/local/sbin/named-checkzone
    zonecheck-opts  -i local -k ignore
    zonesign        /usr/local/sbin/dnssec-signzone

    genkrf	    /usr/bin/genkrf
    keyarch	    /usr/bin/keyarch
    rollchk	    /usr/bin/rollchk
    rollctl	    /usr/bin/rollctl
    zonesigner      /usr/bin/zonesigner

    #
    # The name of the Perl module that will be used to parse zone files.
    #
    zonefile-parser	Bobs::Wonderful::DNS::Zone-Parse-Thingum

    #
    # Special processing for a couple of zone phases.
    #
    prog-ksk5       xfer-ds-epp !default ! adminmail mary bob 
    prog-ksk6       check-for-ds

    #
    # Settings for dnssec-keygen.
    #
    algorithm	rsasha1
    ksklength	2048
    zsklength	1024
    random	/dev/urandom
    
    #
    # Settings for dnssec-signzone.
    #
    endtime		+2592000	# RRSIGs good for 30 days.

    #
    # Life-times for keys.  These defaults indicate how long a key has
    # between roll-overs.  The values are measured in seconds.
    # 
    ksklife         15768000		# Half-year.
    zsklife         604800 		# One week.
    lifespan-max    94608000		# Two years.
    lifespan-min    3600		# One hour.

    
    #
    # Settings that will be noticed by zonesigner.
    #
    archivedir          /usr/local/etc/dnssec-tools/KEY-SAFE
    default_keyrec	default.krf
    entropy_msg		0
    savekeys            1
    zskcount            1

    #
    # Settings for rollover-manager.
    #
    roll_logfile    /usr/local/etc/dnssec-tools/log-rollerd
    roll_loglevel   info
    roll_sleeptime  60
    autosign        1
    zone_errors     3

    log_tz		local

    #
    # GUI-usage flag.
    #
    usegui		0

=head1 COPYRIGHT

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

=head1 AUTHOR

Wayne Morrison, tewok@tislabs.com

=head1 SEE ALSO

B<dtinitconf(8)>,
B<dtconfchk(8)>,
B<keyarch(8)>,
B<rollerd(8)>,
B<zonesigner(8)>

B<Net::DNS::SEC::Tools::conf.pm(3)>,
B<Net::DNS::SEC::Tools::keyrec.pm(3)>
B<Net::DNS::SEC::Tools::rollmgr.pm(3)>

=cut
