From 02ea9b1fa581f890c9401fe23b75852541578d59 Mon Sep 17 00:00:00 2001 From: Niko Tyni Date: Mon, 14 Feb 2005 22:26:25 +0000 Subject: * 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 --- Makefile | 34 +++++++++++++++------- README | 10 ++++--- doc/smokeping_extend.pod | 16 +++++------ doc/smokeping_install.pod | 67 ++++++++++++++++++++++++++++++++----------- doc/smokeping_upgrade.pod | 22 +++++++-------- htdocs/smokeping.cgi.dist | 72 +++++++++++++++++++++++++++++++++++++++++++++++ lib/Smokeping.pm | 2 +- lib/Smokeping/Examples.pm | 13 +++++---- 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 and C. The former is intended for probes +L and L. 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 module is a non-functional probe that is intended +The L module is a non-functional probe that is intended to make a good basis for a new probe module. Copy the file, C, 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 arguments C<--man> or C<--makepod>. The embedded +L arguments C<--man> or C<--makepod>. The embedded POD documentation should point to this real documentation, so that curious users of the C 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 method for probe-specific variables and a C method for target-specific variables. If you don't know the difference -between these yet, see the L document. +between these yet, see L. (The probes that are derived from C don't support target-specific variables, so they only use the C 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. Each variable +for parsing the configuration file, L. Each variable should be a hash that uses the "special variable keys" documented in -the C manual. See the C and the other +the C manual. See C 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 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. 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 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 -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 + +You need this to run the EchoPing probes + +=item Curl (Optional) + +L -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://www.cpan.org/modules/by-module/Socket6/ +You need this for the DNS probe. + +=item SSH (Optional) + +L + +You need this for the SSH probe. + +=item Various Perl modules (Optional) + +You can get these from L. + +=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 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 allow to run cgi scripts under proper user accounts. =item Perl 5.6.1 -http://www.perl.com +L 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 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 The C 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 This probe is also now derived from FPing and supports all the variables FPing does. -=item Curl +=item L The URL that will be used is now specified with the variable C instead of C. 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 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 variable.) -=item EchoPingIcp +=item L The C variable is now mandatory, as the old default "/" didn't make sense because it's relative rather than absolute. -=item LDAP +=item L The C 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 The C variable was changed to C and its semantics were changed accordingly. See the LDAP explanation above. -=item AnotherDNS +=item L The C variable was changed to C 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 The C variable was changed to C 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 The C variable was removed. The target should now be specified in the C variable, like it is with all the other probes. @@ -146,7 +146,7 @@ in the C variable, like it is with all the other probes. =over -=item The RemoteFPing probe +=item The L 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 =head1 SEE ALSO -The other Smokeping documents, especially smokeping_config. +The other Smokeping documents, especially L. 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 going, you need a webserver which allows you to run +cgi scripts. The system must be setup so that the B is +allowed to write to the image caching area as defined in the config file. + +This script runs with normal perl. B 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 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 Etobi@oetiker.chE + +=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 Etobi\@oetiker.chE +Tobias Oetiker Etobi@oetiker.chE Niko Tyni Entyni@iki.fiE 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 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 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. It's a +This module uses more or less internal functions from L. 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 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 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 module. ${e}head1 DESCRIPTION @@ -150,7 +151,7 @@ Niko Tyni ${e}head1 SEE ALSO -The other Smokeping documents, especially smokeping_config. +The other Smokeping documents, especially L. DOC } -- cgit v1.2.3-24-g4f1b