=head1 NAME

smokeping_master_slave - How run multiple districuted instances of SmokePing

=head1 OVERVIEW

Normally smokeping probes run their tests from the host where smokeping runs
to some target host and monitor the latency of the connection between the
two. 

The Master/Slave concept enables all smokeping probes to run remotely. The
use case for this is, to measure the overall connectivity in a network. If
you are interested in checking that your central DNS server or your file
server works for everyone, you could setup several smokeping instances
checking up on on the two servers from multiple locations within your
network. With the Master/Slave smokeping configuration this process becomes
much simpler, as one smokeping master server can control multiple slaves.

All monitoring data is stored and presented on the server, but colleted by
the slaves. The slaves will also get their configuration information from
the master, so that you just have to maintain the master server
configuration file and the rest is taken care of automatically.

=head1 DESCRIPTION

=head2 Architecture

The slaves communicate with the master smokeping server via the normal
smokeping web interface. On initial startup each slave connects to the
master server and asks for its assignements. When the slave has done a round
of probing it connects to the master again to deliver the results.

If the assignemt for a slave change, the master will tell the slave after
the slave has delivered its results.

The master and slaves sign their messages by supplying an md5 hash of the
message appended with a shared secret. Optionally the whole communication
can run over ssl.

    [slave 1]     [slave 2]      [slave 3]
        |             |              |
        +-------+     |     +--------+
                |     |     |
                v     v     v
              +---------------+
              |    master     |
              +---------------+

The slave is a normal smokeping instance setup where the configuration comes
from the master instead of a local configuration file. The slave tries to
contact the master server after every round of probing, supplying its
results. If the master server can not be reached, the results will be sent
to the server together with the next round of results. Results will be
stored in a perl storable so that they survive a restart of the smokeping
instance.

=head2 Master Configuration

To configure a master/slave setup, add a slaves section to your smokeping
configuration file. If some configuration parameter must be set to a special
value for the slave, use an override section to configure this.


 *** slaves ****
 secrets=/etc/smokeping/slavesecrets.conf 
 +slave1
 name=Slave 1
 location=India
 ++override
 Probes.FPing.binary = /usr/bin/fping
 ...

Then in the targets section you can define slaves at every lvel. Again the
settings get inherited by lower order targets and can be overwritten
anywhere in the tree.

A slave will then get the appropriate configuration assigned by the server.
 
 *** targets ***
 slaves = slave1 slave2
 ...
 +dest1
 slaves =
 ...
 +dest2
 slaves = slave1
 ...
 +dest3
 ... 

=head2 Slave Configuration

A smokeping slave setup has no configuration file. It just needs to know
that it runs in slave-mode and its secret. The secet is stored in a file for
optimal protection. By default the persitant data cache will be located in
F</tmp/smokeping.$USER.cache>.

 ./smokeping --master-url=http://smokeping/smokeping.cgi \
             --cache-dir=/var/smokeping/cache.file \
             --shared-secret=/var/smokeping/secret.txt

=head1 COPYRIGHT

Copyright (c) 2007 by Tobias Oetiker, OETIKER+PARTNER AG. All right reserved.

=head1 LICENSE

This program is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.  See the GNU General Public License for more
details.

You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
02139, USA.

=head1 AUTHOR

Tobias Oetiker E<lt>tobi@oetiker.chE<gt>

=cut