diff options
Diffstat (limited to 'lib/Smokeping')
| -rw-r--r-- | lib/Smokeping/Examples.pm | 633 |
1 files changed, 633 insertions, 0 deletions
diff --git a/lib/Smokeping/Examples.pm b/lib/Smokeping/Examples.pm new file mode 100644 index 0000000..5adbfff --- /dev/null +++ b/lib/Smokeping/Examples.pm @@ -0,0 +1,633 @@ +# -*- perl -*- +package Smokeping::Examples; +use strict; +use Smokeping; + +=head1 NAME + +Smokeping::Examples - A module for generating the smokeping_examples document + +=head1 OVERVIEW + +This module generates the smokeping_examples document 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 +in the directories C<doc> and C<doc/examples>. + +=head1 DESCRIPTION + +The entry point to the module is the C<make> subroutine. It takes one optional +parameter, C<check>, that makes the module run a syntax check for all the +created example configuration files. + +=head1 BUGS + +This module uses more or less internal functions from C<Smokeping.pm>. 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 +and have this module filter them away for the config files. + +=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> + +=cut + +use strict; + +sub read_config_template { + my $file = "etc/config.dist"; + my $h = { + common => "", # everything up to the Probes section + probes => "", # the Probes section, without the *** Probes *** line + targets => "", # the Targets section, without the *** Targets *** line + }; + open(F, "<$file") or die("open template configuration file $file for reading: $!"); + my %found; + while (<F>) { + /\*\*\*\s*(Probes|Targets)\s*\*\*\*/ and $found{$1} = 1, next; + $h->{common} .= $_ and next unless $found{Probes}; + $h->{probes} .= $_ and next unless $found{Targets}; + $h->{targets} .= $_; + } + close F; + return $h; +} + +sub prologue { + my $e = "="; + return <<DOC; +${e}head1 NAME + +smokeping_examples - Examples of Smokeping configuration + +${e}head1 OVERVIEW + +This document provides some examples of Smokeping configuration files. +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 +corresponding probe, if applicable. + +This manual is automatically generated from the Smokeping source code. + +${e}head1 DESCRIPTION + +Currently the examples differ only in the C<Probes> and C<Targets> +sections. The other sections are taken from the C<etc/config.dist> +configuration template in the Smokeping distribution so that the example +files are complete. + +If you would like to provide more examples, document the other sections +or enhance the existing examples, please do so, preferably by sending +the proposed changes to the smokeping-users mailing list. + +DOC +} + +sub epilogue { + my $e = "="; + return <<DOC; + +${e}head1 COPYRIGHT + +Copyright 2005 by Niko Tyni. + +${e}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. + +${e}head1 AUTHOR + +Niko Tyni <ntyni\@iki.fi> + +${e}head1 SEE ALSO + +The other Smokeping documents, especially smokeping_config. +DOC +} + +sub make { + print "Generating example files...\n"; + my $check = shift; # check the syntax of the generated config files + my $template = read_config_template(); + my $examples = examples($template); + my $manual = prologue(); + for my $ex (sort { $examples->{$a}{order} <=> $examples->{$b}{order} } keys %$examples) { + my $h = $examples->{$ex}; + $manual .= "\n=head2 Example $h->{order}: config.$ex\n\n" + . genpod($h); + my $cfgfile = "doc/examples/config.$ex"; + print "\t$cfgfile ...\n"; + writecfg($cfgfile, $template, $h); + if ($check) { + local $Smokeping::cfg = undef; + eval { + Smokeping::verify_cfg($cfgfile); + }; + die("Syntax check for $cfgfile failed: $@") if $@; + } + } + $manual .= epilogue(); + writemanual($manual); + print "done.\n"; +} + +sub writemanual { + my $text = shift; + my $filename = "doc/smokeping_examples.pod"; + print "\t$filename ...\n"; + open(F, ">$filename") or die("open $filename for writing: $!"); + print F $text; + close F; +} + +sub genpod { + my $h = shift; + my $text = ""; + $text .= "=over\n\n"; + $text .= "=item Probe configuration\n\n"; + $text .= " *** Probes ***\n"; + $text .= join("\n", map { " $_" } split(/\n/, $h->{probes})); + $text .= "\n\n=item Probe explanation\n\n"; + $text .= $h->{probedoc}; + $text .= "\n\n=item Target configuration\n\n"; + $text .= " *** Targets ***\n"; + $text .= join("\n", map { " $_" } split(/\n/, $h->{targets})); + $text .= "\n\n=item Target explanation\n\n"; + $text .= $h->{targetdoc}; + $text .= "\n\n=back\n\n"; + return $text; +} + +sub writecfg { + my $file = shift; + my $template = shift; + my $h = shift; + open(F, ">$file") or die("open $file for writing: $!"); + print F <<DOC; +# This Smokeping example configuration file was automatically generated. +# +# Everything up to the Probes section is derived from a common template file. +# See the Probes and Targets sections for the actual example. +# +# This example is included in the smokeping_examples document. + +DOC + print F $template->{common}; + print F "# (The actual example starts here.)\n"; + print F "\n *** Probes ***\n\n"; + print F join("\n", map { "# $_" } split(/\n/, $h->{probedoc})); + print F "\n\n"; + print F $h->{probes}; + print F "\n *** Targets ***\n\n"; + print F join("\n", map { "# $_" } split(/\n/, $h->{targetdoc})); + print F "\n\n"; + print F $h->{targets}; + close F; +} + +sub examples { + my $template = shift; + return { + simple => { + order => 1, + probes => <<DOC, ++FPing +binary = /usr/bin/fping +DOC + targets => <<DOC, +probe = FPing + +menu = Top +title = Network Latency Grapher +remark = Welcome to this SmokePing website. + ++ mysite1 +menu = Site 1 +title = Hosts in Site 1 + +++ myhost1 +host = myhost1.mysite1.example +++ myhost2 +host = myhost2.mysite1.example + ++ mysite2 +menu = Site 2 +title = Hosts in Site 2 + +++ myhost3 +host = myhost3.mysite2.example +++ myhost4 +host = myhost4.mysite2.example +DOC + probedoc => <<DOC, +Here we have just one probe, fping, pinging four hosts. + +The fping probe is using the default parameters, some of them supplied +from the Database section ("step" and "pings"), and some of them by +the probe module. +DOC + targetdoc => <<DOC, +The hosts are located in two sites of two hosts each, and the +configuration has been divided to site sections ('+') and host subsections +('++') accordingly. +DOC + }, # simple + "multiple-probes" => { + order => 2, + probes => <<DOC, ++ FPing +binary = /usr/bin/fping +packetsize = 1000 + ++ DNS +binary = /usr/bin/dig +lookup = name.example +pings = 5 +step = 180 + ++ EchoPingHttp +pings = 5 +url = /test-url +DOC + targets => <<DOC, +probe = FPing +menu = Top +title = Network Latency Grapher +remark = Welcome to this SmokePing website. + ++ network +menu = Net latency +title = Network latency (ICMP pings) + +++ myhost1 +host = myhost1.example +++ myhost2 +host = myhost2.example + ++ services +menu = Service latency +title = Service latency (DNS, HTTP) + +++ DNS +probe = DNS +menu = DNS latency +title = Service latency (DNS) + ++++ dns1 +host = dns1.example + ++++ dns2 +host = dns2.example + +++ HTTP +menu = HTTP latency +title = Service latency (HTTP) + ++++ www1 +host = www1.example + ++++ www2 +host = www2.example +DOC + probedoc => <<DOC, +Here we have three probes: FPing for the regular ICMP pings, +DNS for name server latency measurement and EchoPingHttp +for web servers. + +The FPing probe runs with the default parameters, except that the ICMP +packet size is 1000 bytes instead of the default 56 bytes. + +The DNS and EchoPingHttp probes have been configured to be a bit more +gentle with the servers, as they only do 5 queries (pings) instead of the +default 20 (or whatever is specified in the Database section). However, +DNS queries are made more often: 5 queries every 3 minutes instead of +every 5 minutes. +DOC + targetdoc => <<DOC, +The target tree has been divided by the probe used. This does not have +to be the case: every target (sub)section can use a different probe, +and the same probe can be used in different parts of the config tree. +DOC + }, # multiple-probes + "fping-instances" => { + order => 3, + probes => <<DOC, ++ FPing +binary = /usr/bin/fping + +++ FPingNormal +offset = 0% + +++ FPingLarge +packetsize = 5000 +offset = 50% +DOC + probedoc => <<DOC, +This example demonstrates the concept of probe instances. The FPingLarge +and FPingNormal probes are independent of each other, they just use +the same module, FPing. FPingNormal uses the default parameters, and +so does FPingLarge except for the 5 kilobyte packetsize. Both use the +same fping binary, and its path is configured FPing top section. + +The 'offset' parameters make sure the probes don't run at the same time - +FPingNormal is run every 'full' 5 minutes (eg. 8:00, 8:05, 8:10 and so on, +in wallclock time) while FPingLarge is run halfway through these intervals +(eg. 8:02:30, 8:07:30 etc.) + +The top FPing section does not define a probe in itself because it +has subsections. If we really wanted to have one probe named "FPing", +we could do so by making a subsection by that name. +DOC + targets => <<DOC, +probe = FPingNormal +menu = Top +title = Network Latency Grapher +remark = Welcome to this SmokePing website. + ++ network +menu = Net latency +title = Network latency (ICMP pings) + +++ myhost1 +menu = myhost1 +title = ICMP latency for myhost1 + ++++ normal +title = Normal packetsize (56 bytes) +probe = FPingNormal +host = myhost1.example + ++++ large +title = Large packetsize (5000 bytes) +probe = FPingLarge +host = myhost1.example + +++ myhost2 +menu = myhost2 +title = ICMP latency for myhost2 + ++++ normal +title = Normal packetsize (56 bytes) +probe = FPingNormal +host = myhost2.example + ++++ large +title = Large packetsize (5000 bytes) +probe = FPingLarge +host = myhost2.example +DOC + targetdoc => <<DOC, +The target section shows two host, myhost1.example and myhost2.example, +being pinged with two differently sized ICMP packets. This time the tree +is divided by the target host rather than the probe. +DOC + }, # fping-instances + "targetvars-with-Curl" => { + order => 4, + probes => <<DOC, ++ Curl +# probe-specific variables +binary = /usr/bin/curl +step = 60 + +# a default for this target-specific variable +urlformat = http://%host/ +DOC + probedoc => <<DOC, +This example explains the difference between probe- and target-specific +variables. We use the Curl probe for this. + +Every probe supports at least some probe-specific variables. The values +of these variables are common to all the targets of the probe, and +they can only be configured in the Probes section. In this case, +the probe-specific variables are "binary" and "step". + +Target-specific variables are supported by most probes, the most notable +exception being the FPing probe and its derivatives. Target-specific +variables can have different values for different targets. They can be +configured in both Probes and Targets sections. The values assigned in the +Probes section function become default values that can be overridden +in the Targets section. + +The documentation of each probe states which of its variables are +probe-specific and which are target-specific. + +In this case the "urlformat" variable is a target-specific one. It is +also quite uncommon, because it can contain a placeholder for the "host" +variable in the Targets section. This is not a general feature, its +usage is only limited to the "urlformat" variable and the "%host%" escape. + +(The reason why the FPing probe does not support target-specific variables +is simply the fact that the fping program measures all its targets in one +go, so they all have the same parameters. The other probes ping their targets +one at a time.) +DOC + targets => <<DOC, +probe = Curl +menu = Top +title = Network Latency Grapher +remark = Welcome to this SmokePing website. + ++ HTTP +menu = http +title = HTTP latency + +++ myhost1 +menu = myhost1 +title = HTTP latency for myhost1 +host = myhost1.example + +++ myhost2 +menu = myhost2 +title = HTTP latency for myhost2 +host = myhost2.example + +++ myhost3 +menu = myhost3 +title = HTTP latency for myhost3 (port 8080!) +host = myhost3.example +urlformat = http://%host%:8080/ + ++ FTP +menu = ftp +title = FTP latency +urlformat = ftp://%host%/ + +++ myhost1 +menu = myhost1 +title = FTP latency for myhost1 +host = myhost1.example + +++ myhost2 +menu = myhost2 +title = FTP latency for myhost2 +host = myhost2.example +DOC + targetsdoc => <<DOC, +The target tree is divided into an HTTP branch and an FTP one. +The servers "myhost1.example" and "myhost2.example" are probed +in both. The third server, "myhost3.example", only has an HTTP +server, and it's in a non-standard port (8080). + +The "urlformat" variable is specified for the whole FTP branch +as "ftp://%host%/". For the HTTP branch, the default from the +Probes section is used, except for myhost3, which overrides +it to tag the port number into the URL. + +The myhost3 assignment could just as well have included the hostname +verbatim (ie. urlformat = http://myhost3.example:8080/) instead of +using the %host% placeholder, but the host variable would still have +been required (even though it wouldn't have been used for anything). +DOC + }, # targetvars-with-Curl + echoping => { + order => 5, + probes => <<DOC, ++ FPing +binary = /usr/bin/fping + +# these expect to find echoping in /usr/bin +# if not, you'll have to specify the location separately for each probe +# + EchoPing # uses TCP or UDP echo (port 7) +# + EchoPingDiscard # uses TCP or UDP discard (port 9) +# + EchoPingChargen # uses TCP chargen (port 19) ++ EchoPingSmtp # SMTP (25/tcp) for mail servers ++ EchoPingHttps # HTTPS (443/tcp) for web servers ++ EchoPingHttp # HTTP (80/tcp) for web servers and caches ++ EchoPingIcp # ICP (3130/udp) for caches +DOC + probedoc => <<DOC, +This example shows most of the echoping-derived probes in action. +DOC + targets => <<DOC, +# default probe +probe = FPing + +menu = Top +title = Network Latency Grapher +remark = Welcome to this SmokePing website. + ++ MyServers + +menu = My Servers +title = My Servers + +++ www-server +menu = www-server +title = Web Server (www-server) / ICMP +# probe = FPing propagated from top +host = www-server.example + ++++ http +menu = http +title = Web Server (www-server) / HTTP +probe = EchoPingHttp +host = www-server.example +# default url is / + ++++ https +menu = https +title = Web Server (www-server) / HTTPS +probe = EchoPingHttps +host = www-server.example + +++ cache +menu = www-cache +title = Web Cache (www-cache) / ICMP +host = www-cache.example + ++++ http +menu = http +title = www-cache / HTTP +probe = EchoPingHttp +host = www-cache.example +port = 8080 # use the squid port +url = http://www.somehost.example/ + ++++ icp +menu = icp +title = www-cache / ICP +probe = EchoPingIcp +host = www-cache.example +url = http://www.somehost.example/ + +++ mail +menu = mail-server +title = Mail Server (mail-server) / ICMP +host = mail-server.example + ++++ smtp +menu = mail-server / SMTP +title = Mail Server (mail-server) / SMTP +probe = EchoPingSmtp +host = mail-server.example +DOC + targetdoc => <<DOC, +All the servers are pinged both with ICMP (the FPing probe) +and their respective echoping probe. The proxy server, www-cache, +is probed with both HTTP requests and ICP requests for the same +URL. +DOC + }, # echoping + template => { + order => 6, # last + probes => $template->{probes}, + targets => $template->{targets}, + probedoc => <<DOC, +This is the template configuration file distributed with Smokeping. +It is included in the examples as well for the sake of completeness. +DOC + targetdoc => <<DOC, +This is the template configuration file distributed with Smokeping. +It is included in the examples as well for the sake of completeness. +DOC + }, + }; # return +} # sub examples + +1; |