Sophie: smokeping-2.4.2-9mdv2010.0 noarch

smokeping-2.4.2-9mdv2010.0.noarch.rpm

SMOKEPING_UPGRADE(7) SmokePing SMOKEPING_UPGRADE(7)

NNAAMMEE
smokeping_upgrade - Notes on upgrading Smokeping

OOVVEERRVVIIEEWW
This document tries to list incompatible or otherwise user-visible
changes in Smokeping versions, with instructions on how to fix any pos-
sible 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 ver-
sions 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 com-
plement that with upgrading instructions etc.

22..33..66 ttoo 22..44..00
The new SmokeTrace tool was added to SmokePing. For setup instructions
read the smoketrace manual page.

22..33..33 ttoo 22..33..44
The communication protocol between master and slave has been made more
secure. This requires that BOTH master and slave are upgraded to con-
tinue working.

22..22..xx ttoo 22..33..xx
2.3.0 is mainly about new features. Check out the reference documenta-
tion on _h_i_e_r_a_r_c_h_i_e_s and the target properties _p_a_r_e_n_t_s, _h_i_d_d_e_n and
_n_o_m_a_s_t_e_r_p_o_l_l.

The only thing you have to take a look at, is the file _b_a_s_e_p_-
_a_g_e_._h_t_m_l_._d_i_s_t which got some new css properties. Without them the
results of the new filter function will look quite bad.

22..11..xx ttoo 22..22..00
LLWWPP DDeeppeennddeennccyy

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.

22..00..99 ttoo 22..11..00
EEcchhooppiinngg 66 ssuuppppoorrtt

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 sup-
ported, of course.)

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

+o EchoPingDNS

+o EchoPingLDAP

+o EchoPingWhois

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

NNeeww mmeetthhoodd iinn bbaassee..ppmm ((iiff yyoouu wwrriittee yyoouurr oowwnn pprroobbeess))

The _b_a_s_e_._p_m module defines the method ProbeUnit. Override this if your
Probe does not return 'Seconds'. See the _F_T_P_t_r_a_n_s_f_e_r_._p_m for inspira-
tion.

22..00..88 ttoo 22..00..99
FFPPiinngg

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.

22..00..55 ttoo 22..00..66
CCGGII sseellff--rreeffeerrrriinngg lliinnkkss ((aaggaaiinn))

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 "rela-
tive", creating links like <a href="?foo=bar">. I hope this works for
everybody, but if it doesn't, see smokeping_config for the alterna-
tives.

22..00..44 ttoo 22..00..55
FFPPiinngg

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 _d_e_f_a_u_l_t mode, while Smokeping uses the _c_o_u_n_t_i_n_g
mode ("-c"), it never actually did anything.

CCGGII sseellff--rreeffeerrrriinngg lliinnkkss

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

22..00..11 ttoo 22..00..22
EEddggee--ttrriiggggeerreedd aalleerrttss

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.

11..4400 ttoo 22..00
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 gen-
eration 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.

CCOONNFFIIGGUURRAATTIIOONN

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 automat-
ically 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" modi-
fies 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 con-
figuration 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 never-
theless. 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 oonnee ping to take. Previously it was the maximum
time allowed for all the pings to one target. This is an incompat-
ible 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 let-
ter, 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 param-
eters. 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 "url-
format" 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 actu-
ally 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 sec-
onds.

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 speci-
fied in the "host" variable, like it is with all the other probes.

CCGGII::::CCaarrpp mmoodduullee vveerrssiioonn

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.

11..3388 ttoo 11..4400
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.

11..3344 ttoo 11..3377
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-spe-
cific. 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 dif-
ferent step lengths for different probes. You can get the old
behaviour back by setting 'concurrentprobes = no'.

LLIICCEENNSSEE
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 MER-
CHANTABILITY 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.

AAUUTTHHOORR
Niko Tyni <ntyni@iki.fi>

SSEEEE AALLSSOO
The other Smokeping documents, especially smokeping_config.

2.4.2 2008-06-09 SMOKEPING_UPGRADE(7)