prepare for master/slave implementation

3 files changed, 203 insertions, 8 deletions

diff --git a/CHANGES b/CHANGES
index 9fc15b9..dcce65b 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,6 @@
+* added description of the master/slave mode I am implementing
+  for dyndns -- tobi
+
 * fixed smoke when there is a lot of 'loss' -- tobi
 
 * do not use 127.0.0.1 when testing echoping and curl functionality. There may be someone
diff --git a/doc/smokeping_master_slave.pod b/doc/smokeping_master_slave.pod
new file mode 100644
index 0000000..ac2e00f
--- /dev/null
+++ b/doc/smokeping_master_slave.pod
@@ -0,0 +1,138 @@
+=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, that you use somokeping to measure the overall
+connectivity of your network. If you are interested in seeing if you 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 master smokeping server communicates with it's slave servers through a
+polling protocol. Whenever it assumes the slave should have new data ready
+it will poll the slave. If the slave or the network is down, it will skip
+the particular slave and move on to the next one.
+
+When it polls a slave it will also tell the slave about any pending configuration
+changes.
+
+The communication between master and slave is digest authenticated. And
+optionally runns over https.
+
+              +---------------+
+              |    master     |
+              +---------------+
+                |     |     |
+        +-------+     |     +--------+
+        v             v              v
+    [slave 1]     [slave 2]      [slave 3]
+
+The slave is a normal smokeping setup where the configuration comes from the
+master instead of a local configuration file. The slave can run in two
+modes. In standalone mode it will fork off a service process that listens
+for incoming connections from the master. In cgi-mode the master connections
+will be served by a cgi script. The connection part will communicate with
+the local smokeping demon through a a perl storable file. The reason for
+using a storable is that it will survive smokeping restartes and even
+reboots if it is located on non-volatile storage.
+
+=head2 Master Configuration
+
+To configure a master/slave setup, add a slaves section to your smokeping
+configuration file. The secret and timeout parameters will be inherited
+by the slave config sections and can be overwritten if required.
+
+ *** slaves ****
+ secrets=/etc/smokeping/slavesecrets.conf 
+ timeout=30
+ +slave1
+ url=http://....
+ timeout=60
+ ...
+
+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 a few configuration parameters depending on
+your setup.
+
+When running in B<cgi-mode>, the only configuration option is to specify the
+location of communication cache file. By default this will be located in
+F</tmp/smokeping.$USER.cache>. Authentication and access restrictions can be
+configured using your webservers facilities.
+
+ ./smokeping --slavemode=cgi --cache=/var/smokeping/cache.file
+
+When running in standalone mode, the authentication parameters must be
+configured in the smokeping daemon.
+
+ ./smokeping --slavemode=standalone  --cache=/var/smokeping/cache.file \
+             --auth-file=/etc/smokeping/digest.conf \
+             --listen=ip:port \
+             --ssl_listen=ip:port \
+             --master-allow=128.223.22.2
+
+=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
diff --git a/lib/Smokeping.pm b/lib/Smokeping.pm
index 36e97d6..7c65a17 100644
--- a/lib/Smokeping.pm
+++ b/lib/Smokeping.pm
@@ -1573,11 +1573,11 @@ sub get_parser () {
     # the part of target section syntax that doesn't depend on the selected probe
     my $TARGETCOMMON; # predeclare self-referencing structures
     # the common variables
-    my $TARGETCOMMONVARS = [ qw (probe menu title alerts note email host remark rawlog alertee) ];
+    my $TARGETCOMMONVARS = [ qw (probe menu title alerts note email host remark rawlog alertee slaves) ];
     $TARGETCOMMON = 
       {
        _vars     => $TARGETCOMMONVARS,
-       _inherited=> [ qw (probe alerts alertee) ],
+       _inherited=> [ qw (probe alerts alertee slaves) ],
        _sections => [ "/$KEYD_RE/" ],
        _recursive=> [ "/$KEYD_RE/" ],
        _sub => sub {
@@ -1687,6 +1687,11 @@ DOC
 If you want to have alerts for this target and all targets below it go to a particular address
 on top of the address already specified in the alert, you can add it here. This can be a comma separated list of items.
 DOC
+	   slaves => { _re => '[-a-z0-9]+(?:\s+[-a-z0-9]+)*',
+			_re_error => 'slave1 [slave2]',
+			_doc => <<DOC },
+The slave names must match the slaves you have setup in the slaves section.
+DOC
 	   probe => {
 			_sub => sub {
 				my $val = shift;
@@ -1904,7 +1909,7 @@ DOC
     my $parser = Config::Grammar->new 
       (
        {
-	_sections  => [ qw(General Database Presentation Probes Alerts Targets) ],
+	_sections  => [ qw(General Database Presentation Probes Targets Alerts Slaves) ],
 	_mandatory => [ qw(General Database Presentation Probes Targets) ],
 	General    => 
 	{
@@ -1978,7 +1983,6 @@ DOC
 Mail address of the person responsible for this smokeping installation.
 DOC
 	 },
-            
 	 
 	 datadir  => 
 	 {
@@ -2144,6 +2148,7 @@ Path to your tSmoke HTML mail template file. See the tSmoke documentation for de
 DOC
       }
 	},
+
 	Database => 
 	{ 
 	 _vars => [ qw(step pings) ],
@@ -2762,12 +2767,61 @@ DOC
 		       },
 	      },
         },
+       Slaves => {_doc         => <<END_DOC,
+Your smokeping can remote control other somkeping instances running in slave
+mode on different hosts. Use this section to tell your master smokeping about the
+slaves you are going to use.
+END_DOC
+          _vars        => [ qw(secrets timeout) ],
+          _mandatory   => [ qw(secrets) ],
+          _sections    => [ "/$KEYD_RE/" ],
+          secrets => {              
+              %$FILECHECK_SUB,
+              _doc => <<END_DOC,
+The slave secrets file contines one line per slave with the name of the slave followed by a colon
+and the secret:
+
+ slave1:secret1
+ slave2:secret2
+ ...
+END_DOC
+
+          },
+          timeout => {
+              %$INTEGER_SUB,
+              _doc => <<END_DOC,
+How long should the master wait for its slave to answer?
+END_DOC
+          },     
+          "/$KEYD_RE/" => {
+              _vars => [ qw(url timeout) ],
+              _mandatory => [ qw(url) ],
+              _inherited => [ qw(timeout) ],
+              _doc => <<END_DOC,
+Define some basic properties for the slave.
+END_DOC
+              timeout => {
+                  %$INTEGER_SUB,
+                  _doc => <<END_DOC,
+How long should the master wait for its slave to answer?
+END_DOC
+              },
+              url => {
+                  _re => 'https?://\S+',
+                  _re_error => 'Use a url of the form http[s]://...',
+                  _doc => <<END_DOC,
+The url where the master can find its slave host.
+END_DOC
+          }          
+       },
        Targets => {_doc        => <<DOC,
-The Target Section defines the actual work of SmokePing. It contains a hierarchical list
-of hosts which mark the endpoints of the network connections the system should monitor.
-Each section can contain one host as well as other sections.
+The Target Section defines the actual work of SmokePing. It contains a
+hierarchical list of hosts which mark the endpoints of the network
+connections the system should monitor. Each section can contain one host as
+well as other sections. By adding slaves you can measure the connectivity of
+an endpoint looking from several sources.
 DOC
-		   _vars       => [ qw(probe menu title remark alerts) ],
+		   _vars       => [ qw(probe menu title remark alerts slaves) ],
 		   _mandatory  => [ qw(probe menu title) ],
                    _order => 1,
 		   _sections   => [ "/$KEYD_RE/" ],