path: root/doc/smokeping_upgrade.pod

=head1 NAME

smokeping_upgrade - Notes on upgrading Smokeping

=head1 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 C<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.

=head1 2.1.x to 2.2.0

=head2 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.

=head1 2.0.9 to 2.1.0

=head2 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:

=over

=item *

L<EchoPingDNS|Smokeping::probes::EchoPingDNS>

=item *

L<EchoPingLDAP|Smokeping::probes::EchoPingLDAP>

=item *

L<EchoPingWhois|Smokeping::probes::EchoPingWhois>

=back

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

=head2 New method in base.pm (if you write your own probes)

The F<base.pm> module defines the method ProbeUnit. Override this if your
Probe does not return 'Seconds'. See the F<FTPtransfer.pm> for inspiration.

=head1 2.0.8 to 2.0.9

=head2 L<FPing|Smokeping::probes::FPing>

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

=head1 2.0.5 to 2.0.6

=head2 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 C<linkstyle> variable in the
C<General> section of the configuration file. The default is now C<relative>,
creating links like S<<a href="?foo=bar">>. I hope this works for everybody,
but if it doesn't, see L<smokeping_config> for the alternatives.

=head1 2.0.4 to 2.0.5

=head2 L<FPing|Smokeping::probes::FPing>

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

=head2 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 S<<a href="/path/smokeping.cgi?foo=bar">>. The new behaviour uses the
C<cgiurl> variable: the links are always absolute like 
S<<a href="http://some.host/path/smokeping.cgi?foo=bar">>.

=head1 2.0.1 to 2.0.2

=head2 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 C<edgetrigger> variable in the C<Alerts>
section. The old behaviour (which sends a notification on each match)
is the default.

=head1 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.

=head2 CONFIGURATION

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

=over

=item 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.

=item Variable order

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

Additionally, C<probe> must now precede C<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 C<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.

=item 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.

=item Timeouts

The C<timeout> variable in the Probes section is now the maximum time
expected for B<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 C<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.

=item 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.

=item Minimum number of pings

The C<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.

=item 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
C<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 C<rrdtune> command might be helpful here.

=item Configurable location for DYNAMIC-related files

There is now a new configuration variable, C<dyndir>, that can be used
to specify the location of the DYNAMIC-related files (.adr and .snmp).
These files used to be kept under C<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 C<dyndir> is not specified, Smokeping will use the C<datadir> value
as the default. This should ensure that no existing setups will break.

=back

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

=over

=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 L<FPing6|Smokeping::probes::FPing6>

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

=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
for the C<host> variable of each target as C<%host%>, eg. C<urlformat = http://%host%/>.
The new variable is mandatory. 

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

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 C<agent>
parameter).  Smokeping will complain if it notices quotes around the
string.

Any extra arguments for C<curl> can now be specified in the C<extraargs> variable.

=item L<EchoPingHttp|Smokeping::probes::EchoPingHttp>

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

=item L<EchoPingHttps|Smokeping::probes::EchoPingHttps>

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

=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 L<LDAP|Smokeping::probes::LDAP>

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

The C<sleeptime> variable was changed to C<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.)

=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 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 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 L<TelnetIOSPing|Smokeping::probes::TelnetIOSPing>

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

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.

=back

=head2 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 L<the smokeping_install document|smokeping_install>. 

=head1 1.38 to 1.40

=over

=item 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.

=back

=head1 1.34 to 1.37

=over

=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
variables were C<rhost>, C<rbinary> and C<rhost>.

=item Logging changes

The C<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.

=item 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'.

=back

=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>

=head1 SEE ALSO

The other Smokeping documents, especially L<smokeping_config>.