.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "SMOKEPING_MASTER_SLAVE 7"
.TH SMOKEPING_MASTER_SLAVE 7 "2008-06-30" "2.4.2" "SmokePing"
.SH "NAME"
smokeping_master_slave \- How run multiple distributed instances of SmokePing
.SH "OVERVIEW"
.IX Header "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. 
.PP
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 \s-1DNS\s0 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.
.PP
All monitoring data is stored and presented on the server, but collected 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.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Sh "Architecture"
.IX Subsection "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 assignments. When the slave has done a round
of probing it connects to the master again to deliver the results.
.PP
If the assignment for a slave changes, the master will tell the slave after
the slave has delivered its results.
.PP
The master and the slaves sign their messages by supplying an \s-1HMAC\-MD5\s0
code (\s-1RFC\s0 2104) of the message and a shared secret. Optionally the whole
communication can run over ssl.
.PP
.Vb 8
\&    [slave 1]     [slave 2]      [slave 3]
\&        |             |              |
\&        +\-\-\-\-\-\-\-+     |     +\-\-\-\-\-\-\-\-+
\&                |     |     |
\&                v     v     v
\&              +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&              |    master     |
\&              +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
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.
.Sh "Master Configuration"
.IX Subsection "Master Configuration"
To configure a master/slave setup, add a slaves section to your smokeping
configuration file. Each slave has a section in the slaves part of the
master configuration file. The section name must match the hostname of the
slave. If some configuration parameter must be set to a special value for
the slave, use an override section to configure this.
.PP
The slave names must be the names the hosts think they have not their
outside hostnames or ip addresses or anything like that. When the slave
calls the master to get its config or report its measurements it will tell
the master its 'hostname'. This together with the shared secret is used to
authenticate and identify who is who.
.PP
.Vb 2
\& *** Slaves ***
\& secrets=/etc/smokeping/slavesecrets.conf
.Ve
.PP
.Vb 4
\& +slave1
\& display_name=erul22
\& location=India
\& color=ff0000
.Ve
.PP
.Vb 3
\& ++override
\& Probes.FPing.binary = /usr/bin/fping
\& ...
.Ve
.PP
Then in the targets section you can define slaves at every level. Again the
settings get inherited by lower order targets and can be overwritten
anywhere in the tree.
.PP
A slave will then get the appropriate configuration assigned by the server.
.PP
.Vb 11
\& *** Targets ***
\& slaves = slave1 slave2
\& ...
\& +dest1
\& slaves =
\& ...
\& +dest2
\& slaves = slave1
\& ...
\& +dest3
\& ...
.Ve
.PP
The data from the slaves will be stored in \fITargetName~SlaveName.rrd\fR. So the example above would
create the following files:
.PP
.Vb 6
\& dest1.rrd
\& dest2.rrd
\& dest2~slave1.rrd
\& dest3.rrd
\& dest3~slave1.rrd
\& dest3~slave2.rrd
.Ve
.PP
The \fIslavesecrets.conf\fR file contains a colon separated list of hostnames
and secrets.
.PP
.Vb 2
\& host1:secret1
\& host2:secret2
.Ve
.Sh "Slave Configuration"
.IX Subsection "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 secret is stored in a file for
optimal protection. By default the persistent data cache will be located in
\&\fI/tmp/smokeping.$USER.cache\fR.
.PP
.Vb 3
\& ./smokeping \-\-master\-url=http://smokeping/smokeping.cgi \e
\&             \-\-cache\-dir=/var/smokeping/ \e
\&             \-\-shared\-secret=/var/smokeping/secret.txt
.Ve
.PP
The \fIsecret.txt\fR file contains a single word, the secret of this slave. It
is \s-1NOT\s0 the same as the \fIslavesecrets.conf\fR file the master uses.
.SH "SECURITY CONSIDERATIONS"
.IX Header "SECURITY CONSIDERATIONS"
The master effectively has full access to slave hosts as the user the
slave smokeping instance is run as. The configuration is transferred as
Perl code that is evaluated on the slave. While this is done inside a
restricted \f(CW\*(C`Safe\*(C'\fR compartment, there are various ways that a malicious
master could use to embed arbitrary commands in the configuration and
get them to run when the slave probes its targets.
.PP
The strength of the shared secret is thus of paramount importance. Brute
forcing the secret would enable a man-in-the-middle to inject a malicious
new configuration and compromise the slave.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2007 by Tobias Oetiker, \s-1OETIKER+PARTNER\s0 \s-1AG\s0. All right reserved.
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it
and/or modify it under the terms of the \s-1GNU\s0 General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.
.PP
This program is distributed in the hope that it will be
useful, but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied
warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0
\&\s-1PURPOSE\s0.  See the \s-1GNU\s0 General Public License for more
details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0
02139, \s-1USA\s0.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tobias Oetiker <tobi@oetiker.ch>