.\" 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_EXTEND 7"
.TH SMOKEPING_EXTEND 7 "2005-09-14" "2.4.2" "SmokePing"
.SH "NAME"
smokeping_extend \- Notes on extending Smokeping
.SH "OVERVIEW"
.IX Header "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.
.PP
Comments and proposed changes or additions are welcome.  Please send
them to the smokeping-users mailing list. Patches against the \s-1POD\s0
source of this document are most appreciated.
.SH "CHOOSING A BASE CLASS"
.IX Header "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
Smokeping::probes::base and Smokeping::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.
.PP
At the moment, the only probes that use \f(CW\*(C`Smokeping::probes::base\*(C'\fR are the FPing
derivatives. All the others use \f(CW\*(C`Smokeping::probes::basefork\*(C'\fR, and chances are
you should too. This document will thus concentrate on the latter case.
.SH "SKELETON FILE"
.IX Header "SKELETON FILE"
The Smokeping::probes::skel module is a non-functional probe that is intended
to make a good basis for a new probe module. Copy the file, 
\&\f(CW\*(C`lib/probes/skel.pm\*(C'\fR, to a new name and just fill out the blanks :)
Note that the names of real probe modules must start with a capital letter.
.SH "PROBE DOCUMENTATION"
.IX Header "PROBE DOCUMENTATION"
The probe documentation is generated from the source code with the
smokeping arguments \f(CW\*(C`\-\-man\*(C'\fR or \f(CW\*(C`\-\-makepod\*(C'\fR. The embedded
\&\s-1POD\s0 documentation should point to this real documentation, so
that curious users of the \f(CW\*(C`perldoc\*(C'\fR command see what's going on.
All the current probes do this.
.PP
You should provide the method \f(CW\*(C`pod_hash\*(C'\fR that returns a reference to
a hash with keys corresponding to the section names you want in the
manpage. The supported section names are
\&\f(CW\*(C`name\*(C'\fR, \f(CW\*(C`overview\*(C'\fR, \f(CW\*(C`description\*(C'\fR, \f(CW\*(C`authors\*(C'\fR, \f(CW\*(C`notes\*(C'\fR, \f(CW\*(C`bugs\*(C'\fR, and
\&\f(CW\*(C`see_also\*(C'\fR. If you don't need a particular section, just leave it out.
.PP
The special sections \f(CW\*(C`synopsis\*(C'\fR and \f(CW\*(C`variables\*(C'\fR are automatically
generated from the description of your variables. See below.
.PP
Note that if you use 'here documents' ('<<') that have \s-1POD\s0 markup inside,
you should escape the markup so that it doesn't show up in the embedded
\&\s-1POD\s0 documentation. Most probes do it like this:
.PP
.Vb 4
\& my $e = "=";
\& my $doc = <<DOC;
\& ${e}head1 SECTION TITLE
\& DOC
.Ve
.SH "PROBE DESCRIPTION"
.IX Header "PROBE DESCRIPTION"
The probe should offer the \f(CW\*(C`ProbeDesc\*(C'\fR method that returns a short
description of what it does. This will be used in the graphs produced
by the web frontend.
.SH "VARIABLES"
.IX Header "VARIABLES"
All Smokeping probes must define their variables by implementing a
\&\f(CW\*(C`probevars\*(C'\fR method for probe-specific variables and a \f(CW\*(C`targetvars\*(C'\fR
method for target-specific variables. If you don't know the difference
between these yet, see smokeping_examples.
.PP
(The probes that are derived from \f(CW\*(C`Smokeping::probes::base\*(C'\fR don't support
target-specific variables, so they only use the \f(CW\*(C`probevars\*(C'\fR method.)
.PP
The base classes offer these methods too to provide the variables that
are common to all the probes (eg. the probe-specific \f(CW\*(C`step\*(C'\fR variable
and the target-specific \f(CW\*(C`pings\*(C'\fR 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.
.PP
When you do supply your own \f(CW\*(C`probevars\*(C'\fR or \f(CW\*(C`targetvars\*(C'\fR method, you should
combine your variables with those coming from the superclass. There is a
convenience method called \f(CW\*(C`_makevars\*(C'\fR that does this, and the common idiom is
.PP
.Vb 6
\& sub probevars {
\&        my $class = shift;
\&        return $class\->_makevars($class\->SUPER::probevars, {
\&                # your variables go here
\&        }
\& }
.Ve
.PP
The variables are declared in a syntax that comes from the module used
for parsing the configuration file, \f(CW\*(C`Config::Grammar\*(C'\fR. Each variable
should be a hash that uses the \*(L"special variable keys\*(R" documented in
Config::Grammar. See \f(CW\*(C`Smokeping::probes::skel\*(C'\fR and the other
probes for examples. 
.PP
For reference, here are the keys the hash should have. Much of this
is taken straight from the \f(CW\*(C`Config::Grammar\*(C'\fR manual.
.IP "Keys you \fBmust\fR provide" 4
.IX Item "Keys you must provide"
.RS 4
.PD 0
.IP "_doc" 4
.IX Item "_doc"
.PD
Description of the variable.
.IP "_example" 4
.IX Item "_example"
An example value. This will be used in the \s-1SYNOPSIS\s0 section in the
probe manual.
.RE
.RS 4
.RE
.IP "Optional keys" 4
.IX Item "Optional keys"
.RS 4
.PD 0
.IP "_default" 4
.IX Item "_default"
.PD
A default value that will be assigned to the variable if none is specified or inherited.
.IP "_re" 4
.IX Item "_re"
Regular expression upon which the value will be checked.
.IP "_re_error" 4
.IX 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).
.IP "_sub" 4
.IX Item "_sub"
A function pointer. It is 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.
.RE
.RS 4
.RE
.PP
The \f(CW\*(C`probevars\*(C'\fR and \f(CW\*(C`targetvars\*(C'\fR methods should return hash references
that contain the variable names as keys and the hashes described above
as values. In addition the \f(CW\*(C`Config::Grammar\*(C'\fR special section key
\&\f(CW\*(C`_mandatory\*(C'\fR is supported and should contain a reference to a list of
mandatory variables. The \f(CW\*(C`_makevars\*(C'\fR method is aware of this special
key and merges the mandatory lists in its arguments. Note that no other
\&\f(CW\*(C`Config::Grammar\*(C'\fR special section keys are supported.
.SH "INITIALIZATION"
.IX Header "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 \f(CW\*(C`new\*(C'\fR method. You should probably also take care that
you don't run the tests needlessly while in \s-1CGI\s0 mode. The usual way to 
do this is to test for \f(CW$ENV\fR{\s-1SERVER_SOFTWARE\s0}. See the \f(CW\*(C`Smokeping::probes::skel\*(C'\fR
module for an example.
.SH "PINGING"
.IX Header "PINGING"
All the real action happens in the \f(CW\*(C`pingone\*(C'\fR method (or, for
\&\f(CW\*(C`Smokeping::probes::base\*(C'\fR\-derived probes, in the \f(CW\*(C`ping\*(C'\fR method.) The arguments
for \f(CW\*(C`pingone\*(C'\fR are \f(CW$self\fR, the module instance (since this is a method)
and \f(CW$target\fR, the target to be probed.
.PP
You can access the probe-specific variables here via the
\&\f(CW\*(C`$self\->{properties}\*(C'\fR hash and the target-specific ones via the
\&\f(CW\*(C`$target\->{vars}\*(C'\fR hash. You get the number of pings needed for
the target via the \f(CW\*(C`pings\*(C'\fR method: \f(CW\*(C`my $count = $self\->pings($target)\*(C'\fR.
.PP
You should return a sorted array of the latency times measured. If a ping
fails, don't put anything in the array.
.PP
That's it, you're done!
.SH "EXAMPLE CONFIGURATIONS"
.IX Header "EXAMPLE CONFIGURATIONS"
If you would like to provide a documented example configuration for your
probe (in addition to the automatically generated \s-1SYNOPSIS\s0 section in
the probe manual), you can do so by adding it to the Smokeping::Examples
module.  Look for the 'examples' subroutine and add your example there.
.PP
Future versions of Smokeping might provide a way to embed examples in
the probe modules too. The author's motivation for implementing this
would be greatly increased by even a single demand for it, so please
speak up if you think you'd use it.
.SH "TIMEOUT HANDLING"
.IX Header "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.
.PP
First, there's timeout logic in \f(CW\*(C`Smokeping::probes::basefork\*(C'\fR 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 \f(CW\*(C`timeout\*(C'\fR.
This would be done like this:
.PP
.Vb 8
\& 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
\&        }
\& }
.Ve
.PP
If you want to provide a target-specific \f(CW\*(C`timeout\*(C'\fR setting, you should
delete the probe-specific variable and be sure to provide a default for
your target-specific one. See eg. \f(CW\*(C`Smokeping::probes::AnotherDNS\*(C'\fR for an example of
how this is done. 
.PP
Providing a target-specific \f(CW\*(C`timeout\*(C'\fR will make the timeout in
\&\f(CW\*(C`Smokeping::probes::basefork\*(C'\fR 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 \f(CW\*(C`Smokeping::probes::basefork\*(C'\fR starts killing the processes.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2005 by Niko Tyni.
.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"
Niko Tyni <ntyni@iki.fi>
.SH "BUGS"
.IX Header "BUGS"
This document makes writing new probes look much harder than it really is.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The other Smokeping documents, especially smokeping_config.