#!/usr/bin/perl
#
# Copyright 2012-2013 SPARTA, Inc.  All rights reserved.  See the COPYING
# file distributed with this software for details.
#
# owl-config.pod					Owl Monitoring System
#
#       This module contains contains the pod describing the configuration
#	file used by the Owl scripts.
#
# Revision History:
#	1.0	Initial version.				121201
#
#	2.0	Released as part of DNSSEC-Tools 2.0.		131301
#	2.0.1	Modified to allow multiple types of queries.	131319
#

1;

=pod

=head1 NAME

owl-config - Configuration file for Owl sensor programs

=head1 DESCRIPTION

The Owl configuration file contains values that control the various Owl
programs.  These values include such things as the details of DNS queries to
perform, where data files are to be stored, and the location of the log files.
Some of the entries are intended for specific programs, while others are more
widely used.

If a particular line is not included, then its values will be taken from the
command-line options or the defaults.  These configuration values may be
overridden by the command-line options.  Precedence, from highest to lowest,
is command-line options, configuration file values, default values.

Each non-comment line in the configuration file has (roughly) the same format:

	<type> <specifier> <arguments> 

where:

	type - the type of the line; e.g., query, data, sensor

	specifier - a specific instance of the type (optional)

	arguments - data specific to the the type/specifier pair

=head1 CONFIGURATION TYPES

There are five types of configuration I<type> lines.  These are:

    data           log             remote
    host           query

The format and purpose of these lines are defined below.

=head2 Data Configuration Lines

The B<data> line defines the specifics on how the Owl scripts store data
files.

The B<data> lines have the following format:

    data <keyword> <value>

The I<keyword> may be one of the following:

    archive        interval
    dir            sensors

The I<archive> field specifies the archive directory that contains old
Owl sensor data.

The I<dir> field specifies the data directory that contains Owl sensor data.

The I<interval> field specifies the frequency with which sensor data is
transferred from sensor to the manager.  This is given in seconds.

The I<sensors> field specifies the location of the sensors' data directories.
This is used by B<owl-transfer-mgr> to specify the top-level directory that
holds each sensor's data subdirectory.  It is only used on the Owl manager.

=head2 Host Configuration Line

The B<host> line defines properties relating to the specific host and the Owl
programs it will run.  These properties include the name of the Owl host, a
list of administrator email addresses,  and how the host's programs will be run.

The B<host> lines have the following format:

    host <keyword> <value>

The I<keyword> may be one of the following:

    name              name of the host (all)

    admin              email addresses of administrative contacts (all)

    transfer-mgr-args  arguments to pass to owl-transfer-mgr (manager)

    dnstimer-args      arguments to pass to owl-dnstimer (sensor)

    transfer-args      arguments to pass to owl-transfer (sensor)

    hesitation         sleep time in seconds between executions of
		       owl-dnstimer or owl-transfer (sensor)

    hibernation        sleep time if owl-dnstimer or owl-transfer is
		       executing too frequently (sensor)

    quickcount         number of consecutive fast executions of 
		       owl-dnstimer or owl-transfer before a
		       hibernation occurs
                       (sensor)

    quickseconds       number of seconds that define a fast execution
                       (sensor)

The I<name> is intended to be used in communications with the Owl manager.

The last six keywords are used by B<owl-sensord> when starting the
B<owl-dnstimer> and B<owl-transfer> programs.  I<dnstimer-args>,
I<transfer-args>, and I<transfer-mgr-args> may contain spaces, but
the other four all must be positive numbers.

=head2 Log Configuration Lines

The B<log> line defines the specifics on how the Owl host handles logging.

The B<log> line has the following format:

    log <keyword> <value>

Currently, the only I<keyword> is "dir", which defines where the log files
will be stored.

=head2 Query Configuration Lines

The B<query> configuration lines define the DNS queries that will be performed.
These are used by the B<owl-dnstimer> program to determine the target host,
nameserver, and query type groupings that will have timing data collected.
The configuration file must contain at least one B<query> line.

The B<query> lines have the following format:

        query <type> <target> <server> <arg> <interval> <timeout> <rollover>

The I<type> field specifies the type of query which will be performed.
If I<dnstimer> is given, then a DNS timing query will be done.  If I<rrdata>
is given, then a DNS resource record will be displayed.

The I<target> field specifies the target host for which a nameserver will
be queried.

The I<server> field specifies the nameserver that will be queried.  If
this is a single letter from 'a' to 'm', then it will be appended with
'.root-servers.net'.  At present, this field is not used for I<rrdata>
I<type> queries.

The I<arg> field specifies an argument to the query.  For I<dnstimer>,
I<rrdata> and I<rrsec> query types, this is the DNS resource record that the nameserver
will be queried for.  If this is not included or is given as '-', then an
'A' query will be performed.

The I<interval> field specifies the interval between nameserver queries, in
seconds.  If this is not included or is given as '-', then the interval will
be 60 seconds.

The I<timeout> field specifies the maximum length of time for each nameserver
query, in seconds.  If this is not included or is given as '-', then half the
I<interval> value will be used.

The I<rollover> field specifies the interval between data file rollovers, in
minutes.  If this is not included or is given as '-', then the data file
rollover time will be 30 minutes.

=head2 Remote Configuration Line

The B<remote> line defines several ways the host will communicate with
either the Owl manager or an Owl sensor.

The B<remote> lines have the following format:

    remote <keyword> <value>

The I<keyword> may be one of the following:

    heartbeat
    ssh-user

The I<heartbeat> field specifies the URLs which B<owl-heartbeat> will use
to contact a remote Owl host.  Multiple hosts may be contacted by specifying
multiple instances of this line.

The I<ssh-user> field specifies the user on a remote host that B<owl-transfer>
or B<owl-transfer-mgr> will use when moving data to/from the remote host.  The
user running B<owl-transfer> or B<owl-transfer-mgr> must have B<ssh> access to
the remote host.  B<ssh> on both hosts must be configured so a password will
not be required to be entered.

The data for this field is divided into the following subfields:

    user@host	  This is the user and host field given to ssh.
    ssh args	  These are arguments passed to the ssh command.
    sensor name	  The name of the sensor associated with this line.

The subfields are separated by semicolons.  The first subfield is required;
the second subfield is optional; and the third subfield is only required on
the Owl manager.  B<owl-transfer-mgr> will ignore any I<ssh-user> line that
does not contain the third subfield.

Multiple I<ssh-user> lines may be given in the B<owl.conf> file, and data will
be transferred to/from each I<ssh-user> field specified.  This will allow
disparate remote Owl hosts to require different connection characteristics.

=head1 EXAMPLE CONFIGURATION

The following is an example configuration file:

    #
    # Owl sensor configuration file.
    #

    host    name       svalbard-owl
    host    admin      bob@example.com
    host    dnstimer-args  -config /owl/conf/owl.conf
    host    transfer-args  -config /owl/conf/owl.conf

    query    dnstimer .                d
    query    dnstimer example.com      d   AAAA  -  42
    query    dnstimer www.example.com  d   -  -  -  60

    query    dnstimer .                ns1.local
    query    dnstimer example.com      ns1.local   AAAA  -  42

    query    rrdata example.com      dummy.field   NS  -  30
    query    rrsec  example.com      dummy.field   NS  -  30

    data   archive    /owl/archived-data
    data   dir        /owl/data-files
    data   sensors    /owl/sensor-data

    log    dir    /owl/log-files

    remote    ssh-user    sensor1@xyzzy.example.com;-p 6543;sensor-1
    remote    ssh-user    svalbard@owl.dnssec-tools.org;svalbard

    remote    heartbeat   http://owl-mgr.local/cgi-bin/owl-sensor-heartbeat.cgi

=head1 SEE ALSO

B<owl-dnstimer(1)>,
B<owl-heartbeat(1)>,
B<owl-sensord(1)>,
B<owl-status(1)>,
B<owl-transfer(1)>,
B<owl-transfer-mgr(1)>

=head1 COPYRIGHT

Copyright 2012-2013 SPARTA, Inc.  All rights reserved.

=head1 AUTHOR

Wayne Morrison, tewok@tislabs.com

=cut

