* announce smokeping version at startup

* add matcher list to smokeping_config
* make matcher names start with a capital letter
* make probe names start with a capital letter
* small doc updates
* one more pod2html makefile fix

10 files changed, 82 insertions, 36 deletions

diff --git a/CHANGES b/CHANGES
index 857053e..40607d1 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,4 @@
+* matchers start with a capital letter now -- niko
 * new probe programming interface -- niko
  - more strict config file checking giving helpful error messages when necessary
  - generate probe documentation automatically from the code
diff --git a/Makefile b/Makefile
index 61b1c01..d0048f4 100644
--- a/Makefile
+++ b/Makefile
@@ -28,7 +28,7 @@ HTML= $(addsuffix .html,$(BASE))
 POD2MAN = pod2man --release=$(VERSION) --center=SmokePing $<
 MAN2TXT = $(GROFF) -man -Tascii $< > $@
 # pod2html apparently needs to be in the target directory to get L<> links right
-POD2HTML= cd $(dir $@); top="$(shell echo $(dir $@)|sed -e 's,doc/,,' -e 's,[^/]*/,../,g')"; top=$${top:-.}; pod2html --infile=$(CURDIR)/$< --outfile=$(notdir $@) --noindex --htmlroot=. --podroot=. --podpath=$${top} --title=$*
+POD2HTML= cd $(dir $@); top="$(shell echo $(dir $@)|sed -e 's,doc/,,' -e 's,[^/]*/,../,g' -e 's,/$$,,')"; top=$${top:-.}; pod2html --infile=$(CURDIR)/$< --outfile=$(notdir $@) --noindex --htmlroot=. --podroot=. --podpath=$${top} --title=$*
 # we go to this trouble to ensure that MAKEPOD only uses modules in the installation directory
 MAKEPOD= perl -Ilib -I/usr/pack/rrdtool-1.0.47-to/lib/perl -mSmokeping -e 'Smokeping::main()' -- --makepod
 GENEX= perl -Ilib -I/usr/pack/rrdtool-1.0.47-to/lib/perl -mSmokeping -e 'Smokeping::main()' -- --gen-examples
diff --git a/doc/smokeping_extend.pod b/doc/smokeping_extend.pod
index 831a3d1..eef0bf6 100644
--- a/doc/smokeping_extend.pod
+++ b/doc/smokeping_extend.pod
@@ -30,8 +30,7 @@ you should too. This document will thus concentrate on the latter case.
 The L<Smokeping::probes::skel|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, 
 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.
+Note that the names of real probe modules must start with a capital letter.
 
 =head1 PROBE DOCUMENTATION
 
@@ -50,6 +49,15 @@ 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.
 
+Note that if you use 'here documents' ('<<') that have POD markup inside,
+you should escape the markup so that it doesn't show up in the embedded
+POD documentation. Most probes do it like this:
+
+ my $e = "=";
+ my $doc = <<DOC;
+ ${e}head1 SECTION TITLE
+ DOC
+
 =head1 PROBE DESCRIPTION
 
 The probe should offer the C<ProbeDesc> method that returns a short
diff --git a/doc/smokeping_install.pod b/doc/smokeping_install.pod
index 0d97053..7bb8a6b 100644
--- a/doc/smokeping_install.pod
+++ b/doc/smokeping_install.pod
@@ -77,7 +77,7 @@ address, you need to install it.
 
 =item Net::Telnet 
 
-You need this for the telnetIOSPing probe.
+You need this for the TelnetIOSPing probe.
 
 =item Net::DNS
 
diff --git a/doc/smokeping_upgrade.pod b/doc/smokeping_upgrade.pod
index a5e7f67..6c5fbc3 100644
--- a/doc/smokeping_upgrade.pod
+++ b/doc/smokeping_upgrade.pod
@@ -76,6 +76,12 @@ 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.
 
+=item Matchers
+
+The matcher modules have been renamed to start with a capital letter,
+to differentiate the actual modules from the base classes. You have to
+capitalize the matcher name in the pattern definition accordingly.
+
 =back
 
 In addition to this, some probes have had minor incompatible changes to
@@ -135,7 +141,10 @@ 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 L<telnetIOSPing|Smokeping::probes::telnetIOSPing>
+=item L<TelnetIOSPing|Smokeping::probes::TelnetIOSPing>
+
+The name of this probe was changed: it now starts with a capital letter
+like all the others do.
 
 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.
diff --git a/lib/Smokeping.pm b/lib/Smokeping.pm
index 16654f1..8afa5ee 100644
--- a/lib/Smokeping.pm
+++ b/lib/Smokeping.pm
@@ -34,14 +34,14 @@ my $DEFAULTPRIORITY = 'info'; # default syslog priority
 
 my $logging = 0; # keeps track of whether we have a logging method enabled
 
-sub find_probedir {
-	# find the directory where the probe modules are located
+sub find_libdir {
+	# find the directory where the probe and matcher modules are located
 	# by looking for 'Smokeping/probes/FPing.pm' in @INC
 	# 
 	# yes, this is ugly. Suggestions welcome.
 	for (@INC) {
 		-f "$_/Smokeping/probes/FPing.pm" or next;
-		return "$_/Smokeping/probes";
+		return $_;
 	}
 	return undef;
 }
@@ -184,6 +184,8 @@ sub init_alerts ($){
 		or die "ERROR: Alert $al pattern entry '$_' is invalid\n";
 	    my $matcher = $1;
 	    my $arg = $2;
+	    die "ERROR: matcher $matcher: all matchers start with a capital letter since version 2.0\n"
+	    	unless $matcher =~ /^[A-Z]/;
 	    eval 'require Smokeping::matchers::'.$matcher;
 	    die "Matcher '$matcher' could not be loaded: $@\n" if $@;
 	    my $hand;
@@ -1068,12 +1070,17 @@ sub get_parser () {
 
     my $KEY_RE = '[-_0-9a-zA-Z]+';
     my $KEYD_RE = '[-_0-9a-zA-Z.]+';
-    my $PROBE_RE = '[a-z]*[A-Z][a-zA-Z]+';
+    my $PROBE_RE = '[A-Z][a-zA-Z]+';
     my %knownprobes; # the probes encountered so far
 
     # get a list of available probes for _dyndoc sections
-    my $probedir = find_probedir();
+    my $libdir = find_libdir();
+    my $probedir = $libdir . "/Smokeping/probes";
+    my $matcherdir = $libdir . "/Smokeping/matchers";
+
     my $probelist;
+    my @matcherlist;
+
     die("Can't find probe module directory") unless defined $probedir;
     opendir(D, $probedir) or die("opendir $probedir: $!");
     for (readdir D) {
@@ -1083,6 +1090,14 @@ sub get_parser () {
     }
     closedir D;
 
+    die("Can't find matcher module directory") unless defined $matcherdir;
+    opendir(D, $matcherdir) or die("opendir $matcherdir: $!");
+    for (sort readdir D) {
+    	next unless /[A-Z]/;
+    	next unless s/\.pm$//;
+	push @matcherlist, $_;
+    }
+
     # The target-specific vars of each probe
     # We need to store them to relay information from Probes section to Target section
     # see 1.2 above
@@ -2064,9 +2079,19 @@ DOC
 		          },
 		  
 		  type => {
-		     _doc => 'Currently the pattern types B<rtt> and B<loss> and B<matcher> are known',
+		     _doc => <<DOC,
+Currently the pattern types B<rtt> and B<loss> and B<matcher> are known. 
+
+Matchers are plugin modules that extend the alert conditions.  Known
+matchers are @{[join (", ", map { "L<$_|Smokeping::matchers::$_>" }
+@matcherlist)]}.
+
+See the documentation of the corresponding matcher module
+(eg. L<Smokeping::matchers::$matcherlist[0]>) for instructions on
+configuring it.
+DOC
 		     _re => '(rtt|loss|matcher)',
-                     _re_error => 'Use loss or rtt'
+                     _re_error => 'Use loss, rtt or matcher'
 			  },
    	 	  pattern => {
  		     _doc => "a comma separated list of comparison operators and numbers. rtt patterns are in milliseconds, loss patterns are in percents",
@@ -2564,7 +2589,7 @@ sub main (;$) {
 	}
     	daemonize_me $cfg->{General}{piddir}."/smokeping.pid";
     }
-    do_log "Launched successfully";
+    do_log "Smokeping version $VERSION successfully launched.";
 
     my $myprobe;
     my $forkprobes = $cfg->{General}{concurrentprobes} || 'yes';
@@ -2593,7 +2618,7 @@ sub main (;$) {
 		$probepids{$pid} = $myprobe;
 	}
 	# parent
-	do_log("All probe processes started succesfully.");
+	do_log("All probe processes started successfully.");
 	my $exiting = 0;
 	for my $sig (qw(INT TERM)) {
 		$SIG{$sig} = sub {
@@ -2608,7 +2633,7 @@ sub main (;$) {
 				}
 				sleep 1;
 			}
-			do_log("All child processes succesfully terminated, exiting.");
+			do_log("All child processes successfully terminated, exiting.");
 			exit 0;
 		}
 	};
diff --git a/lib/Smokeping/matchers/avgratio.pm b/lib/Smokeping/matchers/Avgratio.pm
index fab0164..8679fe9 100644
--- a/lib/Smokeping/matchers/avgratio.pm
+++ b/lib/Smokeping/matchers/Avgratio.pm
@@ -1,21 +1,21 @@
-package Smokeping::matchers::avgratio;
+package Smokeping::matchers::Avgratio;
 
 =head1 NAME
 
-Smokeping::matchers::avgratio - detect changes in average median latency
+Smokeping::matchers::Avgratio - detect changes in average median latency
 
 =head1 OVERVIEW
  
-The avgratio matcher establishes a historic average median latency over
+The Avgratio matcher establishes a historic average median latency over
 several measurement rounds. It compares this average, against a second
-average latency value again build over several rounds of measurment.
+average latency value again build over several rounds of measurement.
 
 =head1 DESCRIPTION
 
 Call the matcher with the following sequence:
 
  type = matcher
- pattern =  avgratio(historic=>a,current=>b,comparator=>o,percentage=>p)
+ pattern =  Avgratio(historic=>a,current=>b,comparator=>o,percentage=>p)
 
 =over
 
@@ -41,15 +41,15 @@ Right hand side of the comparison.
 
 =head1 EXAMPLE
 
-Take build the average median latency over 10 samples, use this to divid the
+Take build the average median latency over 10 samples, use this to divide the
 current average latency built over 2 samples and check if it is bigger than
 150%.
 
- avgratio(historic=>10,current=>2,comparator=>'>',percentage=>150);
+ Avgratio(historic=>10,current=>2,comparator=>'>',percentage=>150);
 
  avg(current)/avg(historic) > 150/100
 
-This means the matcher will activate when the current latency average if
+This means the matcher will activate when the current latency average is
 more than 1.5 times the historic latency average established over the last
 10 rounds of measurement.
 
@@ -59,7 +59,7 @@ Copyright (c) 2004 by OETIKER+PARTNER AG. All rights reserved.
 
 =head1 SPONSORSHIP
 
-The development of this matcher has been sponsored by Virtela Communications www.virtela.net.
+The development of this matcher has been sponsored by Virtela Communications, L<http://www.virtela.net/>.
 
 =head1 LICENSE
 
diff --git a/lib/Smokeping/matchers/median.pm b/lib/Smokeping/matchers/Median.pm
index e8d43cf..3c8560a 100644
--- a/lib/Smokeping/matchers/median.pm
+++ b/lib/Smokeping/matchers/Median.pm
@@ -1,8 +1,8 @@
-package Smokeping::matchers::median;
+package Smokeping::matchers::Median;
 
 =head1 NAME
 
-Smokeping::matchers::median - Find persistant change in latency
+Smokeping::matchers::Median - Find persistant changes in latency
 
 =head1 OVERVIEW
 
@@ -18,7 +18,7 @@ give a match.
 Call the matcher with the following sequence:
 
  type = matcher
- pattern =  median(old=>x,new=>y,diff=>z)
+ pattern =  Median(old=>x,new=>y,diff=>z)
 
 This will create a matcher which consumes x+y latency-datapoints, builds the
 two medians and the matches if the difference between the median latency is
@@ -64,7 +64,7 @@ sub Length($)
 }
 
 sub Desc ($) {
-    croak "Finde changes in median latency";
+    croak "Find changes in median latency";
 }    
 
 sub Test($$)
diff --git a/lib/Smokeping/matchers/base.pm b/lib/Smokeping/matchers/base.pm
index cd69871..130634f 100644
--- a/lib/Smokeping/matchers/base.pm
+++ b/lib/Smokeping/matchers/base.pm
@@ -7,9 +7,12 @@ Smokeping::matchers::base - Base Class for implementing SmokePing Matchers
 =head1 OVERVIEW
  
 This is the base class for writing SmokePing matchers. Every matcher must
-inherit from the base class and provide it's own methods for the 'buisness'
+inherit from the base class and provide it's own methods for the 'business'
 logic.
 
+Note that the actual matchers must have at least one capital letter in their
+name, to differentiate them from the base class(es).
+
 =head1 DESCRIPTION
 
 Every matcher must provide the following methods:
@@ -29,7 +32,7 @@ The new method expects hash elements as an argument
 eg new({x=>'\d+',y=>'\d+'},x=>1,y=>2). The first part is
 a syntax rule for the arguments it should expect and the second part
 are the arguments itself. The first part will be supplied
-by the child class as it calls the partent method.
+by the child class as it calls the parent method.
 
 =cut
 
@@ -41,7 +44,7 @@ sub new(@)
     my $self = { param => { @_ } };
     foreach my $key (keys %{$self->{param}}){
 	my $regex = $rules->{$key};
-	croak "key '$key' is not known byt this matcher" unless defined $rules->{$key};	
+	croak "key '$key' is not known by this matcher" unless defined $rules->{$key};	
 	croak "key '$key' contains invalid data: '$self->{param}{$key}'" unless $self->{param}{$key} =~ m/^$regex$/;
     }    
     bless $self, $class;
@@ -77,7 +80,7 @@ sub Desc ($) {
 =head2 Test
 
 Run the matcher and return true or false. The Test method is called
-with a hash of two arrays giving it access to both rtt and loss values
+with a hash of two arrays giving it access to both rtt and loss values.
 
   my $data=shift;
   my @rtt = @{$data->{rtt}};
diff --git a/lib/Smokeping/probes/telnetIOSPing.pm b/lib/Smokeping/probes/TelnetIOSPing.pm
index 260cec7..5f68877 100644
--- a/lib/Smokeping/probes/telnetIOSPing.pm
+++ b/lib/Smokeping/probes/TelnetIOSPing.pm
@@ -1,14 +1,14 @@
-package Smokeping::probes::telnetIOSPing;
+package Smokeping::probes::TelnetIOSPing;
 
 =head1 301 Moved Permanently
 
 This is a Smokeping probe module. Please use the command 
 
-C<smokeping -man Smokeping::probes::telnetIOSPing>
+C<smokeping -man Smokeping::probes::TelnetIOSPing>
 
 to view the documentation or the command
 
-C<smokeping -makepod Smokeping::probes::telnetIOSPing>
+C<smokeping -makepod Smokeping::probes::TelnetIOSPing>
 
 to generate the POD document.
 
@@ -24,7 +24,7 @@ my $e = "=";
 sub pod_hash {
 	return {
 		name => <<DOC,
-Smokeping::probes::telnetIOSPing - Cisco IOS Probe for SmokePing
+Smokeping::probes::TelnetIOSPing - Cisco IOS Probe for SmokePing
 DOC
 		description => <<DOC,
 Integrates Cisco IOS as a probe into smokeping.  Uses the telnet protocol