From b9ddd9310ea896a5e644f784013a386d9e7212a9 Mon Sep 17 00:00:00 2001
From: Tobi Oetiker <tobi@oetiker.ch>
Date: Fri, 11 Feb 2005 20:48:36 +0000
Subject: niko has revamped smokeping to parse configuration much more
 strictly. It is all documented in software/doc/smokeping_upgrade.pod

---
 doc/smokeping_extend.pod  | 241 ++++++++++++++++++++++++++++++++++++++++++++++
 doc/smokeping_upgrade.pod | 199 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 440 insertions(+)
 create mode 100644 doc/smokeping_extend.pod
 create mode 100644 doc/smokeping_upgrade.pod

(limited to 'doc')

diff --git a/doc/smokeping_extend.pod b/doc/smokeping_extend.pod
new file mode 100644
index 0000000..6ee0133
--- /dev/null
+++ b/doc/smokeping_extend.pod
@@ -0,0 +1,241 @@
+=head1 NAME
+
+smokeping_extend - Notes on extending Smokeping
+
+=head1 OVERVIEW
+
+This document is intended to guide prospective authors in writing new
+Smokeping probes.  It mostly describes the interface between Smokeping
+and its probe modules. If it seems too complicated to understand, look
+at the existing modules for examples.
+
+Comments and proposed changes or additions are welcome.  Please send
+them to the smokeping-users mailing list. Patches against this file
+are most appreciated.
+
+=head1 CHOOSING A BASE CLASS
+
+The first thing you should decide is which base class you should
+use for your probe. For most (if not all) uses it's a choice between
+C<probes::base> and C<probes::basefork>. The former is intended for probes
+that can measure their targets all in one go, while the latter is for
+probing them one at a time, possibly in several concurrent subprocesses.
+
+At the moment, the only probes that use C<probes::base> are the FPing
+derivatives. All the others use C<probes::basefork>, and chances are
+you should too. This document will thus concentrate on the latter case.
+
+=head1 SKELETON FILE
+
+The C<probes::skel> module is a non-functional probe that is intended
+to make a good basis for a new probe module. Copy the file, 
+C<lib/probes/skel.pm>, to a new name and just fill out the blanks :)
+Note that real probe modules must have at least one capital letter
+in their name.
+
+=head1 PROBE DOCUMENTATION
+
+The probe documentation is generated from the source code with the
+C<smokeping> arguments C<--man> or C<--makepod>. The embedded
+POD documentation should point to this real documentation, so
+that curious users of the C<perldoc> command see what's going on.
+All the current probes do this.
+
+You should provide the method C<pod_hash> that returns a reference to
+a hash with keys corresponding to the section names you want in the
+manpage. The supported section names are
+C<name>, C<overview>, C<description>, C<authors>, C<notes>, C<bugs>, and
+C<see_also>. If you don't need a particular section, just leave it out.
+
+The special sections C<synopsys> and C<variables> are automatically
+generated from the description of your variables. See below.
+
+=head1 PROBE DESCRIPTION
+
+The probe should offer the C<ProbeDesc> method that returns a short
+description of what it does. This will be used in the graphs produced
+by the web frontend.
+
+=head1 VARIABLES
+
+All Smokeping probes must define their variables by implementing a
+C<probevars> method for probe-specific variables and a C<targetvars>
+method for target-specific variables. If you don't know the difference
+between these yet, see the L<smokeping_examples> document.
+
+(The probes that are derived from C<probes::base> don't support
+target-specific variables, so they only use the C<probevars> method.)
+
+The base classes offer these methods too to provide the variables that
+are common to all the probes (eg. the probe-specific C<step> variable
+and the target-specific C<pings> variable. If you don't want to add
+anything to the base class variables (perhaps because all your variables
+are of a target-specific nature, so you don't need new probe-specific
+variables at all), you can leave the corresponding method out and it
+will be inherited from the base class.
+
+When you do supply your own C<probevars> or C<targetvars> method, you should
+combine your variables with those coming from the superclass. There is a
+convenience method called C<_makevars> that does this, and the common idiom is
+
+ sub probevars {
+        my $class = shift;
+        return $class->_makevars($class->SUPER::probevars, {
+		# your variables go here
+	}
+ }
+
+The variables are declared in a syntax that comes from the module used
+for parsing the configuration file, C<ISG::ParseConfig>. Each variable
+should be a hash that uses the "special variable keys" documented in
+the C<ISG::ParseConfig> manual. See the C<probes::skel> and the other
+probes for examples. 
+
+For reference, here are the keys the hash should have. Much of this
+is taken straight from the C<ISG::ParseConfig> manual.
+
+=over
+
+=item Keys you B<must> provide
+
+=over
+
+=item _doc
+
+Description of the variable.
+
+=item _example
+
+An example value. This will be used in the SYNOPSYS section in the
+probe manual.
+
+=back
+
+=item Optional keys
+
+=over
+
+=item _default
+
+A default value that will be assigned to the variable if none is specified or inherited.
+
+=item _re
+
+Regular expression upon which the value will be checked.
+
+=item _re_error
+
+String containing the returned error in case the regular expression
+doesn't match (if not specified, a generic 'syntax error' message will
+be returned).
+
+=item _sub        
+
+A function pointer. It called for every value, with the value passed
+as its first argument. If the function returns a defined value it is
+assumed that the test was not successful and an error is generated with
+the returned string as content.
+
+=back
+
+=back
+
+The C<probevars> and C<targetvars> methods should return hash references
+that contain the variable names as keys and the hashes described above
+as values. In addition the C<ISG::ParseConfig> special section key
+C<_mandatory> is supported and should contain a reference to a list of
+mandatory variables. The C<_makevars> method is available of this special
+key and merges the mandatory lists in its arguments. Note that no other
+C<ISG::ParseConfig> special section keys are supported.
+
+=head1 INITIALIZATION
+
+If you must do something at probe initialization time, like check that
+the external program you're going to use behaves as you expect, you should
+do it in the C<new> method. You should probably also take care that
+you don't run the tests needlessly while in CGI mode. The usual way to 
+do this is to test for $ENV{SERVER_SOFTWARE}. See the C<probes::skel>
+module for an example.
+
+=head1 PINGING
+
+All the real action happens in the C<pingone> method (or, for
+C<probes::base>-derived probes, in the C<ping> method.) The arguments
+for C<pingone> are C<$self>, the module instance (since this is a method)
+and C<$target>, the target to be probed.
+
+You can access the probe-specific variables here via the
+C<$self-E<gt>{properties}> hash and the target-specific ones via the
+C<$target-E<gt>{vars}> hash. You get the number of pings needed for
+the target via the C<pings> method: C<my $count = $self-E<gt>pings($target)>.
+
+You should return a sorted array of the latency times measured. If a ping
+fails, don't put anything in the array.
+
+That's it, you're done!
+
+=head1 TIMEOUT HANDLING
+
+If you deal with timeouts (for example because your program offers a parameter
+for specifying the timeout for the pings), you should know a few things.
+
+First, there's timeout logic in C<probes::basefork> that kills the probe
+when the timeout is reached. By default the timeout is (# of pings *
+5 seconds) + 1 second. If you expect that your pings can take longer,
+you should modify the default value of the probe-specific variable C<timeout>.
+This would be done like this:
+
+ sub probevars {
+        my $class = shift;
+	my $h = $class->SUPER::probevars;
+	$h->{timeout}{_default} = 10; # override the superclass default
+        return $class->_makevars($h, {
+		# your variables go here
+	}
+ }
+
+If you want to provide a target-specific C<timeout> setting, you should
+delete the probe-specific variable and be sure to provide a default for
+your target-specific one. See eg. C<probes::AnotherDNS> for an example of
+how this is done. 
+
+Providing a target-specific C<timeout> will make the timeout in
+C<probes::basefork> be (# of pings * the maximum timeout of all targets)
++ 1 second. The 1 second is added so that the own timeout logic of the
+probe has time to kick in even in the worst case (ie. all pings are lost)
+before C<probes::basefork> starts killing the processes.
+
+=head1 COPYRIGHT
+
+Copyright 2005 by Niko Tyni.
+
+=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
+
+Niko Tyni <ntyni@iki.fi>
+
+=head1 BUGS
+
+This document makes writing new probes look much harder than it really is.
+
+=head1 SEE ALSO
+
+The other Smokeping documents, especially smokeping_config.
diff --git a/doc/smokeping_upgrade.pod b/doc/smokeping_upgrade.pod
new file mode 100644
index 0000000..edb1d6c
--- /dev/null
+++ b/doc/smokeping_upgrade.pod
@@ -0,0 +1,199 @@
+=head1 NAME
+
+smokeping_upgrade - Notes on upgrading Smokeping
+
+=head1 OVERVIEW
+
+This document tries to list incompatible or otherwise user-visible changes
+in Smokeping versions, with instructions on how to fix any possible
+problems. It also sporadically mentions new features and the like.
+
+The document currently starts with changes from 1.34 to 1.37. If you
+run into problems with upgrading from earlier versions, please send
+a description of the problems, preferably with notes on how to fix
+them, to the C<smokeping-users> mailing list, so they can be added to
+this document.  The same applies to any problems you find with current
+versions that are not documented here, of course. Patch submissions
+against this file are most appreciated.
+
+If a version is not listed, there are no known problems in upgrading
+to it from the previous release.
+
+An official list of changes with each release can be found in the CHANGES
+file in the Smokeping distribution. This document tries to complement
+that with upgrading instructions etc.
+
+=head1 1.38 to 2.0
+
+The biggest change with the 2.0 release is that the configuration file
+is now parsed much more strictly. This should result in (hopefully
+understandable) error messages making the configuration less of the
+trial-and-error variety than it used to be. It also automates the
+generation of the configuration documentation from the source code,
+so the docs are now more accurate.
+
+The configuration syntax has stayed mostly the same, except for the
+issues below.
+
+=over
+
+=item PROBE_CONF
+
+The PROBE_CONF subsections have been deprecated. All the target-specific
+variables are now configured in the same section as the target is. Just
+deleting the
+
+++ PROBE_CONF
+
+lines should fix this (for any number of '+', obviously.)
+
+The existence of a PROBE_CONF section makes smokeping exit with an error
+message at parse time.
+
+Note for distributors: these lines could easily be removed automatically
+during upgrade.
+
+=item Variable order
+
+The C<probe> variable must now be set before any variables that depend on
+the selected probe. This is because setting C<probe> modifies the grammar
+of the rest of the section dynamically at parse time.
+
+Additionally, C<probe> must now precede C<host>, for reasons that have
+to do with the current implementation of mandatory variable checking.
+
+Both of these errors are recognized at parse time and produce error messages
+accordingly.
+
+Note for distributors: the C<smokeping> command now has a new '--check'
+option that can be used to verify the syntax of the configuration
+file. It might be a good idea to do this on upgrade and give the user
+an explanatory note if the verification fails.
+
+=item Target-specific variables in the Probes section
+
+This is not an incompatible change, but it is mentioned here nevertheless.
+Target-specific variables can now be specified in the Probes section as well,
+and the values given become defaults for all the targets.
+
+=back
+
+In addition to this, some probes have had minor incompatible changes to
+their configuration.
+
+=over
+
+=item RemoteFPing
+
+The C<rbinary> variable is now mandatory. This is a side effect from a bigger change:
+the probe is now derived from the FPing probe and supports all the variables
+FPing does.
+
+=item FPing6
+
+This probe is also now derived from FPing and supports all the variables FPing does.
+
+=item Curl
+
+The URL that will be used is now specified with the variable C<urlformat> instead
+of C<url>. The new variable can (and usually should) include a placeholder
+for the C<host> variable of each target as C<%host%>, eg. C<urlformat = http://%host%/>.
+The new variable is mandatory. 
+
+The change was made to fix the confusing situation where the C<host> variable
+was required for each actual target, but it didn't actually have any effect
+(as the server to be probed came from the C<url> variable.)
+
+=item EchoPingIcp
+
+The C<url> variable is now mandatory, as the old default "/" didn't make
+sense because it's relative rather than absolute.
+
+=item LDAP
+
+The C<filter> variable is now mandatory, as Net::LDAP bails out without it.
+
+The C<sleeptime> variable was changed to C<mininterval> and its semantics
+were changed accordingly (it's now the minimum time between two queries
+rather than the time slept between the end of one and the start of the
+another.)
+
+=item Radius
+
+The C<sleeptime> variable was changed to C<mininterval> and its semantics
+were changed accordingly. See the LDAP explanation above.
+
+=item AnotherDNS
+
+The C<sleeptime> variable was changed to C<mininterval> and its semantics
+were changed accordingly. See the LDAP explanation above. Additionally,
+the time is now specified in seconds rather than microseconds.
+
+=item AnotherSSH
+
+The C<sleeptime> variable was changed to C<mininterval> and its semantics
+were changed accordingly. See the LDAP explanation above. Additionally,
+the time is now specified in seconds rather than microseconds.
+
+=item telnetIOSPing
+
+The C<target> variable was removed. The target should now be specified
+in the C<host> variable, like it is with all the other probes.
+
+=back
+
+=head1 1.34 to 1.37
+
+=over
+
+=item The RemoteFPing probe
+
+The configuration of this probe was moved from the Targets section to the
+Probes section, as all the variables are really probe-specific. The moved
+variables were C<rhost>, C<rbinary> and C<rhost>.
+
+=item Logging changes
+
+The C<smokeping> daemon now warns at startup if syslog support is not turned on
+in the config file. This is because many diagnostic messages will otherwise
+get lost.
+
+=item Concurrent probes
+
+Each probe now runs in its own process, instead of them all running
+sequentially in one process. This makes it possible to specify different
+step lengths for different probes. You can get the old behaviour back
+by setting 'concurrentprobes = no'.
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2005 by Niko Tyni.
+
+=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
+
+Niko Tyni <ntyni@iki.fi>
+
+=head1 SEE ALSO
+
+The other Smokeping documents, especially smokeping_config.
-- 
cgit v1.2.3-24-g4f1b