Ubuntu Manpage: smokeping_upgrade - Notes on upgrading Smokeping

NAME

       smokeping_upgrade - Notes on upgrading Smokeping

OVERVIEW

       This document tries to list incompatible or otherwise user-visible changes in Smokeping versions, with
       instructions on how to fix any possible problems. It also sporadically mentions new features and the
       like.

       The document currently starts with changes from 1.34 to 1.37. If you run into problems with upgrading
       from earlier versions, please send a description of the problems, preferably with notes on how to fix
       them, to the "smokeping-users" mailing list, so they can be added to this document.  The same applies to
       any problems you find with current versions that are not documented here, of course. Patch submissions
       against the POD source of this file are most appreciated.

       If a version is not listed, there are no known problems in upgrading to it from the previous release.

       An official list of changes with each release can be found in the CHANGES file in the Smokeping
       distribution. This document tries to complement that with upgrading instructions etc.

2.4.2 to 2.4.3

       To fix zooming for FF3.5 I prototype and scriptaculous have been updated. To complete the fix you have to
       update your basepage.html too and include effects in the scriptaculous load line

        cropper/lib/scriptaculous.js?load=builder,effects,dragdrop

2.3.6 to 2.4.0

       The new SmokeTrace tool was added to SmokePing. For setup instructions read the smoketrace manual page.

2.3.3 to 2.3.4

       The communication protocol between master and slave has been made more secure. This requires that BOTH
       master and slave are upgraded to continue working.

2.2.x to 2.3.x

       2.3.0 is mainly about new features. Check out the reference documentation on hierarchies and the target
       properties parents, hidden and nomasterpoll.

       The only thing you have to take a look at, is the file basepage.html.dist which got some new css
       properties. Without them the results of the new filter function will look quite bad.

2.1.x to 2.2.0

   LWP Dependency
       The new master/slave functionality needs the LWP::UserAgent module from CPAN. Currently the dependency is
       not optional; you'll need the module even if you are only running one Smokeping instance.

2.0.9 to 2.1.0

   Echoping 6 support
       This is the first Smokeping version that fully supports echoping 6. Earlier versions of the EchoPingHttp
       probes don't work with echoping 6 because of a command line incompatibility. (Echoping 5 is still
       supported, of course.)

       This version also introduces three new probes using the new echoping plugin interface introduced in
       version 6:

       •   EchoPingDNS

       •   EchoPingLDAP

       •   EchoPingWhois

       See the smokeping_examples document for simple examples of using these probes.

   New method in base.pm (if you write your own probes)
       The  base.pm  module defines the method ProbeUnit. Override this if your Probe does not return 'Seconds'.
       See the FTPtransfer.pm for inspiration.

2.0.8 to 2.0.9

   FPing
       The 'timeout' variable removed in 2.0.5 has been brought back.  It is used to give  the  "fping"  command
       the  "-t"  parameter,  which  apparently affects the timeout of the last ping in the counting ("-C") mode
       used by Smokeping.

2.0.5 to 2.0.6

   CGI self-referring links (again)
       The way Smokeping creates the self-referring links was changed once more.  See the section  under  '2.0.4
       to 2.0.5' for a description of the previous change.

       The  behaviour  is  now  customizable  via  the  "linkstyle"  variable  in  the  "General" section of the
       configuration file. The default is now "relative", creating links like <a href="?foo=bar">. I  hope  this
       works for everybody, but if it doesn't, see smokeping_config for the alternatives.

2.0.4 to 2.0.5

   FPing
       The 'timeout' variable has been removed.  It was used to give the "fping" command the "-t" parameter, but
       as  this  parameter  is  only effective in "fping"'s default mode, while Smokeping uses the counting mode
       ("-c"), it never actually did anything.

   CGI self-referring links
       The way Smokeping creates the self-referring links was changed. The old behaviour used  the  script  name
       but  not the host part, resulting in links like <a href="/path/smokeping.cgi?foo=bar">. The new behaviour
       uses     the     "cgiurl"      variable:      the      links      are      always      absolute      like
       <a href="http://some.host/path/smokeping.cgi?foo=bar">.

2.0.1 to 2.0.2

   Edge-triggered alerts
       The  alert  notifications can now optionally be sent only when the state of the alert changes. This means
       that only the first match of the alert generates a notification, subsequent matches don't. When the alert
       is cleared, ie. there's no match anymore, another notification is sent.

       This behaviour is enabled by the "edgetrigger" variable in the "Alerts" section. The old behaviour (which
       sends a notification on each match) is the default.

1.40 to 2.0

The biggest change with the 2.0 release is that the configuration file is now parsed much more strictly.
This should result in (hopefully understandable) error messages making the configuration less of the
trial-and-error variety than it used to be. It also automates the generation of the configuration
documentation from the source code, so the docs are now more accurate.

A smaller change worth mentioning is the inclusion of the tSmoke script (contributed by Dan McGinn-Combs)
for sending summary emails on daily and weekly system status. Note that it needs the new 'tmail' variable
to be defined in the config file.

CONFIGURATION
The configuration syntax has stayed mostly the same, except for the issues below.

PROBE_CONF
The PROBE_CONF subsections have been deprecated. All the target-specific variables are now configured
in the same section as the target is. Just deleting the

++ PROBE_CONF

lines should fix this (for any number of '+', obviously.)

The existence of a PROBE_CONF section makes smokeping exit with an error message at parse time.

Note for distributors: these lines could easily be removed automatically during upgrade.

Variable order
The "probe" variable must now be set before any variables that depend on the selected probe. This is
because setting "probe" modifies the grammar of the rest of the section dynamically at parse time.

Additionally, "probe" must now precede "host", for reasons that have to do with the current
implementation of mandatory variable checking.

Both of these errors are recognized at parse time and produce error messages accordingly.

Note for distributors: the "smokeping" command now has a new '--check' option that can be used to
verify the syntax of the configuration file. It might be a good idea to do this on upgrade and give
the user an explanatory note if the verification fails.

Target-specific variables in the Probes section
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.

Timeouts
The "timeout" variable in the Probes section is now the maximum time expected for one ping to take.
Previously it was the maximum time allowed for all the pings to one target. This is an incompatible
change, but the code now works in the way it was documented to work even in 1.38.

Those probes offering a target-specific "timeout" variable will get a default for it from the Probes
section, as noted in the previous item. This should ensure that probes that enforce the ping timeout
themselves (most do) will not get killed due to timeout before they have a chance to do it.

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.

Minimum number of pings
The "pings" variable now has an enforced minimum value of 3, as the whole design of Smokeping is
based on the idea of sending several probes and measuring and visualizing the variation between them.

RRD parameter checking
Smokeping now checks at startup that the parameters of any existing RRD files match those specified
in the configuration file. If there is a discrepancy, it will try to fix the situation and refuse to
start if it can't.

This situation is most likely to happen if you have modified the "pings" variable in your
configuration file. You'll then have to delete the old RRD file or somehow convert it to use the new
parameters. The "rrdtune" command might be helpful here.

Configurable location for DYNAMIC-related files
There is now a new configuration variable, "dyndir", that can be used to specify the location of the
DYNAMIC-related files (.adr and .snmp). These files used to be kept under "datadir" along with the
RRD files, but since they need to be writable by the web server, it may be useful to separate these.

If "dyndir" is not specified, Smokeping will use the "datadir" value as the default. This should
ensure that no existing setups will break.

In addition to this, some probes have had minor incompatible changes to their configuration.

RemoteFPing
The "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.

FPing6
This probe is also now derived from FPing and supports all the variables FPing does.

Curl
The URL that will be used is now specified with the variable "urlformat" instead of "url". The new
variable can (and usually should) include a placeholder for the "host" variable of each target as
"%host%", eg. "urlformat = http://%host%/". The new variable is mandatory.

The change was made to fix the confusing situation where the "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 "url"
variable.)

Timeouts are now recognized properly by looking at the curl exit code. The default timeout of this
probe has been raised to 10 seconds.

The command line is now executed without an intervening /bin/sh, and so quotes are not needed anymore
around the User-Agent string (the "agent" parameter). Smokeping will complain if it notices quotes
around the string.

Any extra arguments for "curl" can now be specified in the "extraargs" variable.

EchoPingHttp
The default timeout of this probe has been raised to 10 seconds.

EchoPingHttps
The default timeout of this probe has been raised to 10 seconds.

EchoPingIcp
The "url" variable is now mandatory, as the old default "/" didn't make sense because it's relative
rather than absolute.

LDAP
The "filter" variable is now mandatory, as Net::LDAP bails out without it.

The "sleeptime" variable was changed to "mininterval" and its semantics 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.)

Radius
The "sleeptime" variable was changed to "mininterval" and its semantics were changed accordingly. See
the LDAP explanation above.

AnotherDNS
The "sleeptime" variable was changed to "mininterval" and its semantics were changed accordingly. See
the LDAP explanation above. Additionally, the time is now specified in seconds rather than
microseconds.

AnotherSSH
The "sleeptime" variable was changed to "mininterval" and its semantics were changed accordingly. See
the LDAP explanation above. Additionally, the time is now specified in seconds rather than
microseconds.

TelnetIOSPing
The name of this probe was changed: it now starts with a capital letter like all the others do.

The "target" variable was removed. The target should now be specified in the "host" variable, like it
is with all the other probes.

CGI::Carp module version
The recommended version for CGI::Carp is now at least 1.24, included in CGI.pm-2.82 and the Perl standard
distribution starting from 5.8.1. See the smokeping_install document.

1.38 to 1.40

       The new navigation feature
           The big visible difference between 1.38 and 1.40 is the new browser navigation feature: when clicking
           on the graphs in detail view you can select different time ranges for the graph. The creation of this
           feature has been sponsored by BeverlyCorp.com.

1.34 to 1.37

       The 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 variables were "rhost", "rbinary" and "rhost".

       Logging changes
           The "smokeping" daemon now warns at startup if syslog support is not turned on in  the  config  file.
           This is because many diagnostic messages will otherwise get lost.

       Concurrent probes
           Each probe now runs in its own process, instead of them all running sequentially in one process. This
           makes  it  possible  to  specify  different  step  lengths  for different probes. You can get the old
           behaviour back by setting 'concurrentprobes = no'.

COPYRIGHT

       Copyright 2005 by Niko Tyni.

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.

AUTHOR

       Niko Tyni <ntyni@iki.fi>