=head1 NAME

Smokeping::probes::passwordchecker - A Base Class for implementing SmokePing Probes

=head1 OVERVIEW

Like Smokeping::probes::basefork, but supports a probe-specific configuration file
for storing passwords and a method for accessing them.

=head1 SYNOPSIS

 *** Probes ***

 +passwordchecker

 forks = 5
 offset = 50%
 passwordfile = /some/place/secret
 step = 300
 timeout = 15

 # The following variables can be overridden in each target section
 pings = 5

 # [...]

 *** Targets ***

 probe = passwordchecker # if this should be the default probe

 # [...]

 + mytarget
 # probe = passwordchecker # if the default probe is something else
 host = my.host
 pings = 5

=head1 DESCRIPTION

=head2 synopsis with more detail

SmokePing main configuration file:

 *** Probes ***
 + MyPasswordChecker
 # location of the file containing usernames and passwords
 passwordfile = /usr/share/smokeping/etc/passwords

The specified password file:

 # host:username:password
 host1:joe:hardlyasecret
  # comments and whitespace lines are allowed

 host2:sue:notasecreteither

=head2 Actual description

In implementing authentication probes, it might not be desirable to store
the necessary cleartext passwords in the SmokePing main configuration
file, since the latter must be readable both by the SmokePing daemon
performing the probes and the CGI that displays the results. If the
passwords are stored in a different file, this file can be made readable
by only the user the daemon runs as. This way we can be sure that nobody
can trick the CGI into displaying the passwords on the Web.

This module reads the passwords in at startup from the file specified
in the probe-specific variable `passwordfile'. The passwords can later
be accessed and modified by the B<password> method, that needs the corresponding
host and username as arguments.

=head2 Password file format

The password file format is simply one line for each triplet of host,
username and password, separated from each other by colons (:).

Comment lines, starting with the `#' sign, are ignored, as well as
empty lines.

=head1 VARIABLES

Supported probe-specific variables:

=over

=item forks

Run this many concurrent processes at maximum

Example value: 5

Default value: 5

=item offset

If you run many probes concurrently you may want to prevent them from
hitting your network all at the same time. Using the probe-specific
offset parameter you can change the point in time when each probe will
be run. Offset is specified in % of total interval, or alternatively as
'random', and the offset from the 'General' section is used if nothing
is specified here. Note that this does NOT influence the rrds itself,
it is just a matter of when data acqusition is initiated.
(This variable is only applicable if the variable 'concurrentprobes' is set
in the 'General' section.)

Example value: 50%

=item passwordfile

Location of the file containing usernames and passwords.

Example value: /some/place/secret

=item step

Duration of the base interval that this probe should use, if different
from the one specified in the 'Database' section. Note that the step in
the RRD files is fixed when they are originally generated, and if you
change the step parameter afterwards, you'll have to delete the old RRD
files or somehow convert them. (This variable is only applicable if
the variable 'concurrentprobes' is set in the 'General' section.)

Example value: 300

=item timeout

How long a single 'ping' takes at maximum

Example value: 15

Default value: 5

=back

Supported target-specific variables:

=over

=item pings

How many pings should be sent to each target, if different from the global
value specified in the Database section. Note that the number of pings in
the RRD files is fixed when they are originally generated, and if you
change this parameter afterwards, you'll have to delete the old RRD
files or somehow convert them.

Example value: 5

=back


=head1 AUTHORS

Niko Tyni <ntyni@iki.fi>

=head1 BUGS

The need for storing cleartext passwords can be considered a bug in itself.

=head1 SEE ALSO

L<Smokeping::probes::basefork>, L<Smokeping::probes::Radius>, L<Smokeping::probes::LDAP>

=cut