* smokeping.cgi documentation resurrected

* L<> links in POD documents
* mess with pod2html in Makefile to get L<> links work
* add smokeping_upgrade and smokeping_examples to the README
* change software requirements in smokeping_install

8 files changed, 179 insertions, 57 deletions

diff --git a/Makefile b/Makefile
index 4bfe381..c4d7f0e 100644
--- a/Makefile
+++ b/Makefile
@@ -6,7 +6,7 @@ GROFF = groff
 .SUFFIXES:
 .SUFFIXES: .pm .pod .txt .html .man .1 .3 .5 .7
 
-DOCS = $(filter-out smokeping_config,$(wildcard doc/*.pod)) # section 7
+DOCS = $(filter-out smokeping_config,$(wildcard doc/*.pod)) doc/smokeping_examples.pod # section 7
 DOCSCONFIG := doc/smokeping_config.pod # section 5
 PM :=  lib/ISG/ParseConfig.pm lib/Smokeping.pm lib/Smokeping/Examples.pm
 PODPROBE :=  $(wildcard lib/Smokeping/probes/*.pm)
@@ -16,7 +16,7 @@ DOCSBASE = $(subst .pod,,$(DOCS))
 MODBASE = $(subst .pm,,$(subst lib/,doc/,$(PM))) \
 	$(subst .pm,,$(subst lib/,doc/,$(PODPROBE))) \
 	$(subst .pm,,$(subst lib/,doc/,$(PODMATCH)))
-PROGBASE = doc/smokeping
+PROGBASE = doc/smokeping doc/smokeping.cgi
 DOCSCONFIGBASE = doc/smokeping_config
 
 BASE = $(DOCSBASE) $(MODBASE) $(PROGBASE) $(DOCSCONFIGBASE)
@@ -27,7 +27,8 @@ HTML= $(addsuffix .html,$(BASE))
 
 POD2MAN = pod2man --release=$(VERSION) --center=SmokePing $<
 MAN2TXT = $(GROFF) -man -Tascii $< > $@
-POD2HTML= cd doc ; pod2html --infile=../$< --outfile=../$@ --noindex --htmlroot=. --podroot=. --podpath=.:../bin --title=$*
+# pod2html apparently needs to be in the target directory to get L<> links right
+POD2HTML= cd $(dir $@); top=$(shell echo $(dir $@)|sed 's,[^/]*/,../,g'); pod2html --infile=$(CURDIR)/$< --outfile=$(notdir $@) --noindex --htmlroot=. --podroot=. --podpath=$${top}doc:$${top}bin --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
@@ -36,27 +37,40 @@ doc/%.7: doc/%.pod
 	$(POD2MAN) --section 7 > $@
 doc/%.5: doc/%.pod
 	$(POD2MAN) --section 5 > $@
-doc/%.3: lib/%.pm
+
+doc/Smokeping.3: lib/Smokeping.pm
+	$(POD2MAN) --section 3 > $@
+doc/Smokeping/Examples.3: lib/Smokeping/Examples.pm
 	$(POD2MAN) --section 3 > $@
-doc/Smokeping/%.pod: lib/Smokeping/%.pm
+
+doc/Smokeping/probes/%.pod: lib/Smokeping/probes/%.pm
 	$(MAKEPOD) Smokeping::probes::$* > $@
-doc/Smokeping/%.3: doc/Smokeping/%.pod
+
+doc/Smokeping/probes/%.3: doc/Smokeping/probes/%.pod
 	$(POD2MAN) --section 3 > $@
-doc/ISG/%.3: lib/Smokeping/ISG/%
+doc/Smokeping/matchers/%.3: lib/Smokeping/matchers/%.pm
+	$(POD2MAN) --section 3 > $@
+doc/ISG/%.3: lib/ISG/%.pm
 	$(POD2MAN) --section 3 > $@
 doc/smokeping.1: bin/smokeping.dist
 	$(POD2MAN) --section 1 > $@
+doc/smokeping.cgi.1: htdocs/smokeping.cgi.dist
+	$(POD2MAN) --section 1 > $@
 
 doc/%.html: doc/%.pod
 	$(POD2HTML)
-doc/%.html: lib/%.pm
+doc/Smokeping.html: lib/Smokeping.pm
 	$(POD2HTML)
-doc/Smokeping/%.html: doc/Smokeping/%.pod
+doc/Smokeping/Examples.html: lib/Smokeping/Examples.pm
 	$(POD2HTML)
-doc/ISG/%.html: lib/Smokeping/ISG/%
+doc/Smokeping/matchers/%.html: lib/Smokeping/matchers/%.pm
+	$(POD2HTML)
+doc/ISG/%.html: lib/ISG/%.pm
 	$(POD2HTML)
 doc/smokeping.html: bin/smokeping.dist
 	$(POD2HTML)
+doc/smokeping.cgi.html: htdocs/smokeping.cgi.dist
+	$(POD2HTML)
 
 doc/%.txt: doc/%.1
 	$(MAN2TXT)
diff --git a/README b/README
index 0fe2182..47a2123 100644
--- a/README
+++ b/README
@@ -37,10 +37,12 @@ install. The following important documentation files are
 included with SmokePing:
 
 
- * doc/smokeping_install.txt -- How to Setup and Install 
- * doc/smokeping_config.txt  -- Description of the Config File
- * doc/smokeping.txt         -- About the SmokePing Daemon   
- * doc/smokeping.cgi.txt     -- About the CGI Module
+ * doc/smokeping_install.txt  -- How to Setup and Install 
+ * doc/smokeping_upgrade.txt  -- Notes on upgrading
+ * doc/smokeping_config.txt   -- Description of the Config File
+ * doc/smokeping_examples.txt -- Examples of the Config File
+ * doc/smokeping.txt          -- About the SmokePing Daemon   
+ * doc/smokeping.cgi.txt      -- About the CGI Module
 
 In the doc directory you can find even more information
 and the above documents in MAN, POD, TXT and HTML format.
diff --git a/doc/smokeping_extend.pod b/doc/smokeping_extend.pod
index 4d3f24d..051051c 100644
--- a/doc/smokeping_extend.pod
+++ b/doc/smokeping_extend.pod
@@ -17,7 +17,7 @@ source of this document are most appreciated.
 
 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<Smokeping::probes::base> and C<Smokeping::probes::basefork>. The former is intended for probes
+L<Smokeping::probes::base|Smokeping::probes::base> and L<Smokeping::probes::basefork|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.
 
@@ -27,7 +27,7 @@ you should too. This document will thus concentrate on the latter case.
 
 =head1 SKELETON FILE
 
-The C<Smokeping::probes::skel> module is a non-functional probe that is intended
+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
@@ -36,7 +36,7 @@ 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
+L<smokeping|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.
@@ -61,7 +61,7 @@ by the web frontend.
 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.
+between these yet, see L<smokeping_examples>.
 
 (The probes that are derived from C<Smokeping::probes::base> don't support
 target-specific variables, so they only use the C<probevars> method.)
@@ -86,9 +86,9 @@ convenience method called C<_makevars> that does this, and the common idiom is
  }
 
 The variables are declared in a syntax that comes from the module used
-for parsing the configuration file, C<ISG::ParseConfig>. Each variable
+for parsing the configuration file, L<ISG::ParseConfig>. Each variable
 should be a hash that uses the "special variable keys" documented in
-the C<ISG::ParseConfig> manual. See the C<Smokeping::probes::skel> and the other
+the C<ISG::ParseConfig> manual. See C<Smokeping::probes::skel> and the other
 probes for examples. 
 
 For reference, here are the keys the hash should have. Much of this
@@ -178,7 +178,7 @@ That's it, you're done!
 
 If you would like to provide a documented example configuration for your
 probe (in addition to the automatically generated SYNOPSYS section in
-the probe manual), you can do so by adding it to the Smokeping::Examples
+the probe manual), you can do so by adding it to the L<Smokeping::Examples|Smokeping::Examples>
 module.  Look for the 'examples' subroutine and add your example there.
 
 Future versions of Smokeping might provide a way to embed examples in
@@ -250,4 +250,4 @@ This document makes writing new probes look much harder than it really is.
 
 =head1 SEE ALSO
 
-The other Smokeping documents, especially smokeping_config.
+The other Smokeping documents, especially L<smokeping_config>.
diff --git a/doc/smokeping_install.pod b/doc/smokeping_install.pod
index 0c9f803..a791c56 100644
--- a/doc/smokeping_install.pod
+++ b/doc/smokeping_install.pod
@@ -20,33 +20,54 @@ downloading the tool.
 
 =item RRDtool 1.0.x
 
-http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/pub/rrdtool-1.0.33.tar.gz
+L<http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/>
 
 Just follow the installation instructions. We need this package todo all the
 logging and graphing in SmokePing.
 
-=item FPing 2.4b2
+=item FPing 
 
-http://people.ee.ethz.ch/~oetiker/webtools/smokeping/pub/fping-2.4b2_to.tar.gz 
+L<http://www.fping.com/>
 
-This is a special version of fping which actually builds. I have not
-modified the code in any way, I just fixed the autoconf setup. The original
-can be found on http://www.fping.com/download/fping-2.4b2.tar.gz
+You should grab the newest version, 2.4b2_to-ipv6, as it has IPv6 support
+and actually builds, unlike the older ones.
 
 Note that fping must be installed setuid root. It seems that older versions
 of fping report round trip times in 0.1 milliseconds instead of 1 milliseconds
 as advertised ... SmokePing tries to figure this out. It tells
 you when it starts ... let me know it it gets it wrong.
 
-=item FPing 2.4b2 IPV6 (Optional)
+=item EchoPing  (Optional)
+
+L<http://echoping.sourceforge.net/>
+
+You need this to run the EchoPing probes
+
+=item Curl (Optional)
+
+L<http://curl.haxx.se/>
 
-http://unfix.org/projects/ipv6/fping-2.4b2_to-ipv6.tar.gz
+You need this for the Curl probe.
 
-You need this if you want to use the FPing6 probe
+=item dig (Optional)
 
-=item Socket6 0.11-1 (Optional)
+L<http://http://www.isc.org/sw/bind/>
 
-http://www.cpan.org/modules/by-module/Socket6/
+You need this for the DNS probe.
+
+=item SSH (Optional)
+
+L<http://www.openssh.org/>
+
+You need this for the SSH probe.
+
+=item Various Perl modules (Optional)
+
+You can get these from L<http://www.cpan.org/>.
+
+=over
+
+=item Socket6 0.11-1
 
 Optionally installing the Socket6 module for perl enables
 smokeping to check hostnames that only resolve to an IPv6
@@ -54,15 +75,27 @@ address. If you probe such hosts using ie. the FPing6 probe
 and get warnings that those hosts don't resolve to an IP
 address, you need to install it.
 
-=item EchoPing  (Optional)
+=item Net::Telnet 
 
-http://echoping.sourceforge.net/
+You need this for the telnetIOSPing probe.
 
-You need this to run the EchoPing probes
+=item Net::DNS
+
+You need this for the AnotherDNS probe.
+
+=item Net::LDAP
+
+You need this for the LDAP probe.
+
+=item Authen::Radius
+
+You need this for the Radius probe.
+
+=back
 
 =item Webserver 
 
-http://httpd.apache.org/
+L<http://httpd.apache.org/>
 
 Well I wont get much into this. The important thing is, to have a webserver
 which allows you to run CGI scripts. If you are using Apache I strongly
@@ -72,14 +105,14 @@ Using F<suexec> allow to run cgi scripts under proper user accounts.
 
 =item Perl 5.6.1
 
-http://www.perl.com
+L<http://www.perl.com>
 
 I guess you will get away with older versions of perl. I am using 5.6.1 here
 and it works fine.
 
 =item SpeedyCGI 
 
-http://daemoninc.com/speedycgi/
+L<http://daemoninc.com/speedycgi/>
 
 SpeedyCGI speeds up CGIs written in perl dramatically by making them memory
 resident and handing new request to the script which is already running.
diff --git a/doc/smokeping_upgrade.pod b/doc/smokeping_upgrade.pod
index 75c1076..a5e7f67 100644
--- a/doc/smokeping_upgrade.pod
+++ b/doc/smokeping_upgrade.pod
@@ -83,17 +83,17 @@ their configuration.
 
 =over
 
-=item RemoteFPing
+=item L<RemoteFPing|Smokeping::probes::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
+=item L<FPing6|Smokeping::probes::FPing6>
 
 This probe is also now derived from FPing and supports all the variables FPing does.
 
-=item Curl
+=item L<Curl|Smokeping::probes::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
@@ -104,12 +104,12 @@ 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
+=item L<EchoPingIcp|Smokeping::probes::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
+=item L<LDAP|Smokeping::probes::LDAP>
 
 The C<filter> variable is now mandatory, as Net::LDAP bails out without it.
 
@@ -118,24 +118,24 @@ 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
+=item L<Radius|Smokeping::probes::Radius>
 
 The C<sleeptime> variable was changed to C<mininterval> and its semantics
 were changed accordingly. See the LDAP explanation above.
 
-=item AnotherDNS
+=item L<AnotherDNS|Smokeping::probes::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
+=item L<AnotherSSH|Smokeping::probes::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
+=item L<telnetIOSPing|Smokeping::probes::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.
@@ -146,7 +146,7 @@ in the C<host> variable, like it is with all the other probes.
 
 =over
 
-=item The RemoteFPing probe
+=item The L<RemoteFPing|Smokeping::probes::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
@@ -196,4 +196,4 @@ Niko Tyni <ntyni@iki.fi>
 
 =head1 SEE ALSO
 
-The other Smokeping documents, especially smokeping_config.
+The other Smokeping documents, especially L<smokeping_config>.
diff --git a/htdocs/smokeping.cgi.dist b/htdocs/smokeping.cgi.dist
index e44340b..bce1b5d 100755
--- a/htdocs/smokeping.cgi.dist
+++ b/htdocs/smokeping.cgi.dist
@@ -15,3 +15,75 @@ BEGIN {
         $SIG{__DIE__} = sub { print "Content-Type: text/plain\n\n".(shift)."\n"; exit 1 }
     };
 }
+
+=head1 NAME
+
+smokeping.cgi - SmokePing webfrontend
+
+=head1 OVERVIEW
+
+This script acts as a 'website' for your SmokePing monitoring operation. It
+presents the targets you are looking at in a tree structure and draws graphs
+as they are required by people looking at the pages.
+
+=head1 DESCRIPTION
+
+To get B<smokeping.cgi> going, you need a webserver which allows you to run
+cgi scripts. The system must be setup so that the B<smokeping.cgi> is
+allowed to write to the image caching area as defined in the config file.
+
+This script runs with normal perl. B<BUT> it will appear to be very slow,
+because it does a lot of things when starting up. So if the script has to be
+started a fresh on every click, this is both slow and a tough thing for your
+webserver. I therefore strongly recomment using SpeedyCGI.
+
+Please refer to the installation document for detailed setup instructions.
+
+=head1 SETUP
+
+When installing SmokePing, this file has to be adjusted to fit your
+local system. Three paths have to be entered.
+
+ use lib qw(/usr/pack/rrdtool-1.0.33-to/lib/perl);
+
+One pointing to your B<rrdtool> installation
+
+ use lib qw(/home/oetiker/public_html/smokeping/lib);
+
+One pointing to the place where you have installed the SmokePing libraries
+
+ use Smokeping;
+
+ Smokeping::cgi("/home/oetiker/.smokeping/config");
+
+The third path is the argument to the Smokeping::main command. It points to
+the SmokePing configuration file.
+
+=head1 COPYRIGHT
+
+Copyright (c) 2001 by Tobias Oetiker. 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 7bd0c3c..239cb8d 100644
--- a/lib/Smokeping.pm
+++ b/lib/Smokeping.pm
@@ -2862,7 +2862,7 @@ Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
 
 =head1 AUTHOR
 
-Tobias Oetiker E<lt>tobi\@oetiker.chE<gt>
+Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 
 Niko Tyni E<lt>ntyni@iki.fiE<gt>
 
diff --git a/lib/Smokeping/Examples.pm b/lib/Smokeping/Examples.pm
index 3d30026..fbf95ea 100644
--- a/lib/Smokeping/Examples.pm
+++ b/lib/Smokeping/Examples.pm
@@ -9,7 +9,7 @@ Smokeping::Examples - A module for generating the smokeping_examples document
 
 =head1 OVERVIEW
 
-This module generates the smokeping_examples document and the example
+This module generates L<smokeping_examples> and the example
 configuration files distributed with Smokeping. It is supposed to be
 invoked from the smokeping distribution top directory, as it will need
 the C<etc/config.dist> template configuration file and will create files
@@ -23,7 +23,7 @@ created example configuration files.
 
 =head1 BUGS
 
-This module uses more or less internal functions from C<Smokeping.pm>. It's a 
+This module uses more or less internal functions from L<Smokeping.pm|Smokeping>. It's a 
 separate module only because the latter is much too big already.
 
 It should be possible to include POD markup in the configuration explanations
@@ -97,11 +97,12 @@ All the examples can be found in the C<examples> directory in the
 Smokeping documentation. Note that the DNS names in the examples are
 non-functional.
 
-Details of the syntax and all the variables are found in the
-smokeping_config reference document and in the documentation of the
+Details of the syntax and all the variables are found in 
+L<smokeping_config> and in the documentation of the
 corresponding probe, if applicable.
 
-This manual is automatically generated from the Smokeping source code.
+This manual is automatically generated from the Smokeping source code,
+specifically the L<Smokeping::Examples|Smokeping::Examples> module.
 
 ${e}head1 DESCRIPTION
 
@@ -150,7 +151,7 @@ Niko Tyni <ntyni\@iki.fi>
 
 ${e}head1 SEE ALSO
 
-The other Smokeping documents, especially smokeping_config.
+The other Smokeping documents, especially L<smokeping_config>.
 DOC
 }