1SMOKEPING_UPGRADE(7)               SmokePing              SMOKEPING_UPGRADE(7)
2
3
4

NAME

6       smokeping_upgrade - Notes on upgrading Smokeping
7

OVERVIEW

9       This document tries to list incompatible or otherwise user-visible
10       changes in Smokeping versions, with instructions on how to fix any
11       possible problems. It also sporadically mentions new features and the
12       like.
13
14       The document currently starts with changes from 1.34 to 1.37. If you
15       run into problems with upgrading from earlier versions, please send a
16       description of the problems, preferably with notes on how to fix them,
17       to the "smokeping-users" mailing list, so they can be added to this
18       document.  The same applies to any problems you find with current
19       versions that are not documented here, of course. Patch submissions
20       against the POD source of this file are most appreciated.
21
22       If a version is not listed, there are no known problems in upgrading to
23       it from the previous release.
24
25       An official list of changes with each release can be found in the
26       CHANGES file in the Smokeping distribution. This document tries to
27       complement that with upgrading instructions etc.
28

2.4.2 to 2.4.3

30       To fix zooming for FF3.5 I prototype and scriptaculous have been
31       updated. To complete the fix you have to update your basepage.html too
32       and include effects in the scriptaculous load line
33
34        cropper/lib/scriptaculous.js?load=builder,effects,dragdrop
35

2.3.6 to 2.4.0

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

2.3.3 to 2.3.4

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

2.2.x to 2.3.x

46       2.3.0 is mainly about new features. Check out the reference
47       documentation on hierarchies and the target properties parents, hidden
48       and nomasterpoll.
49
50       The only thing you have to take a look at, is the file
51       basepage.html.dist which got some new css properties. Without them the
52       results of the new filter function will look quite bad.
53

2.1.x to 2.2.0

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

2.0.9 to 2.1.0

61   Echoping 6 support
62       This is the first Smokeping version that fully supports echoping 6.
63       Earlier versions of the EchoPingHttp probes don't work with echoping 6
64       because of a command line incompatibility. (Echoping 5 is still
65       supported, of course.)
66
67       This version also introduces three new probes using the new echoping
68       plugin interface introduced in version 6:
69
70       •   EchoPingDNS
71
72       •   EchoPingLDAP
73
74       •   EchoPingWhois
75
76       See the smokeping_examples document for simple examples of using these
77       probes.
78
79   New method in base.pm (if you write your own probes)
80       The base.pm module defines the method ProbeUnit. Override this if your
81       Probe does not return 'Seconds'. See the FTPtransfer.pm for
82       inspiration.
83

2.0.8 to 2.0.9

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

2.0.5 to 2.0.6

92   CGI self-referring links (again)
93       The way Smokeping creates the self-referring links was changed once
94       more.  See the section under '2.0.4 to 2.0.5' for a description of the
95       previous change.
96
97       The behaviour is now customizable via the "linkstyle" variable in the
98       "General" section of the configuration file. The default is now
99       "relative", creating links like <a href="?foo=bar">. I hope this works
100       for everybody, but if it doesn't, see smokeping_config for the
101       alternatives.
102

2.0.4 to 2.0.5

104   FPing
105       The 'timeout' variable has been removed.  It was used to give the
106       "fping" command the "-t" parameter, but as this parameter is only
107       effective in "fping"'s default mode, while Smokeping uses the counting
108       mode ("-c"), it never actually did anything.
109
110   CGI self-referring links
111       The way Smokeping creates the self-referring links was changed. The old
112       behaviour used the script name but not the host part, resulting in
113       links like <a href="/path/smokeping.cgi?foo=bar">. The new behaviour
114       uses the "cgiurl" variable: the links are always absolute like
115       <a href="http://some.host/path/smokeping.cgi?foo=bar">.
116

2.0.1 to 2.0.2

118   Edge-triggered alerts
119       The alert notifications can now optionally be sent only when the state
120       of the alert changes. This means that only the first match of the alert
121       generates a notification, subsequent matches don't. When the alert is
122       cleared, ie. there's no match anymore, another notification is sent.
123
124       This behaviour is enabled by the "edgetrigger" variable in the "Alerts"
125       section. The old behaviour (which sends a notification on each match)
126       is the default.
127

1.40 to 2.0

129       The biggest change with the 2.0 release is that the configuration file
130       is now parsed much more strictly. This should result in (hopefully
131       understandable) error messages making the configuration less of the
132       trial-and-error variety than it used to be. It also automates the
133       generation of the configuration documentation from the source code, so
134       the docs are now more accurate.
135
136       A smaller change worth mentioning is the inclusion of the tSmoke script
137       (contributed by Dan McGinn-Combs) for sending summary emails on daily
138       and weekly system status. Note that it needs the new 'tmail' variable
139       to be defined in the config file.
140
141   CONFIGURATION
142       The configuration syntax has stayed mostly the same, except for the
143       issues below.
144
145       PROBE_CONF
146           The PROBE_CONF subsections have been deprecated. All the target-
147           specific variables are now configured in the same section as the
148           target is. Just deleting the
149
150           ++ PROBE_CONF
151
152           lines should fix this (for any number of '+', obviously.)
153
154           The existence of a PROBE_CONF section makes smokeping exit with an
155           error message at parse time.
156
157           Note for distributors: these lines could easily be removed
158           automatically during upgrade.
159
160       Variable order
161           The "probe" variable must now be set before any variables that
162           depend on the selected probe. This is because setting "probe"
163           modifies the grammar of the rest of the section dynamically at
164           parse time.
165
166           Additionally, "probe" must now precede "host", for reasons that
167           have to do with the current implementation of mandatory variable
168           checking.
169
170           Both of these errors are recognized at parse time and produce error
171           messages accordingly.
172
173           Note for distributors: the "smokeping" command now has a new
174           '--check' option that can be used to verify the syntax of the
175           configuration file. It might be a good idea to do this on upgrade
176           and give the user an explanatory note if the verification fails.
177
178       Target-specific variables in the Probes section
179           This is not an incompatible change, but it is mentioned here
180           nevertheless.  Target-specific variables can now be specified in
181           the Probes section as well, and the values given become defaults
182           for all the targets.
183
184       Timeouts
185           The "timeout" variable in the Probes section is now the maximum
186           time expected for one ping to take. Previously it was the maximum
187           time allowed for all the pings to one target.  This is an
188           incompatible change, but the code now works in the way it was
189           documented to work even in 1.38.
190
191           Those probes offering a target-specific "timeout" variable will get
192           a default for it from the Probes section, as noted in the previous
193           item.  This should ensure that probes that enforce the ping timeout
194           themselves (most do) will not get killed due to timeout before they
195           have a chance to do it.
196
197       Matchers
198           The matcher modules have been renamed to start with a capital
199           letter, to differentiate the actual modules from the base classes.
200           You have to capitalize the matcher name in the pattern definition
201           accordingly.
202
203       Minimum number of pings
204           The "pings" variable now has an enforced minimum value of 3, as the
205           whole design of Smokeping is based on the idea of sending several
206           probes and measuring and visualizing the variation between them.
207
208       RRD parameter checking
209           Smokeping now checks at startup that the parameters of any existing
210           RRD files match those specified in the configuration file. If there
211           is a discrepancy, it will try to fix the situation and refuse to
212           start if it can't.
213
214           This situation is most likely to happen if you have modified the
215           "pings" variable in your configuration file. You'll then have to
216           delete the old RRD file or somehow convert it to use the new
217           parameters.  The "rrdtune" command might be helpful here.
218
219       Configurable location for DYNAMIC-related files
220           There is now a new configuration variable, "dyndir", that can be
221           used to specify the location of the DYNAMIC-related files (.adr and
222           .snmp).  These files used to be kept under "datadir" along with the
223           RRD files, but since they need to be writable by the web server, it
224           may be useful to separate these.
225
226           If "dyndir" is not specified, Smokeping will use the "datadir"
227           value as the default. This should ensure that no existing setups
228           will break.
229
230       In addition to this, some probes have had minor incompatible changes to
231       their configuration.
232
233       RemoteFPing
234           The "rbinary" variable is now mandatory. This is a side effect from
235           a bigger change: the probe is now derived from the FPing probe and
236           supports all the variables FPing does.
237
238       FPing6
239           This probe is also now derived from FPing and supports all the
240           variables FPing does.
241
242       Curl
243           The URL that will be used is now specified with the variable
244           "urlformat" instead of "url". The new variable can (and usually
245           should) include a placeholder for the "host" variable of each
246           target as "%host%", eg. "urlformat = http://%host%/".  The new
247           variable is mandatory.
248
249           The change was made to fix the confusing situation where the "host"
250           variable was required for each actual target, but it didn't
251           actually have any effect (as the server to be probed came from the
252           "url" variable.)
253
254           Timeouts are now recognized properly by looking at the curl exit
255           code.  The default timeout of this probe has been raised to 10
256           seconds.
257
258           The command line is now executed without an intervening /bin/sh,
259           and so quotes are not needed anymore around the User-Agent string
260           (the "agent" parameter).  Smokeping will complain if it notices
261           quotes around the string.
262
263           Any extra arguments for "curl" can now be specified in the
264           "extraargs" variable.
265
266       EchoPingHttp
267           The default timeout of this probe has been raised to 10 seconds.
268
269       EchoPingHttps
270           The default timeout of this probe has been raised to 10 seconds.
271
272       EchoPingIcp
273           The "url" variable is now mandatory, as the old default "/" didn't
274           make sense because it's relative rather than absolute.
275
276       LDAP
277           The "filter" variable is now mandatory, as Net::LDAP bails out
278           without it.
279
280           The "sleeptime" variable was changed to "mininterval" and its
281           semantics were changed accordingly (it's now the minimum time
282           between two queries rather than the time slept between the end of
283           one and the start of the another.)
284
285       Radius
286           The "sleeptime" variable was changed to "mininterval" and its
287           semantics were changed accordingly. See the LDAP explanation above.
288
289       AnotherDNS
290           The "sleeptime" variable was changed to "mininterval" and its
291           semantics were changed accordingly. See the LDAP explanation above.
292           Additionally, the time is now specified in seconds rather than
293           microseconds.
294
295       AnotherSSH
296           The "sleeptime" variable was changed to "mininterval" and its
297           semantics were changed accordingly. See the LDAP explanation above.
298           Additionally, the time is now specified in seconds rather than
299           microseconds.
300
301       TelnetIOSPing
302           The name of this probe was changed: it now starts with a capital
303           letter like all the others do.
304
305           The "target" variable was removed. The target should now be
306           specified in the "host" variable, like it is with all the other
307           probes.
308
309   CGI::Carp module version
310       The recommended version for CGI::Carp is now at least 1.24, included in
311       CGI.pm-2.82 and the Perl standard distribution starting from 5.8.1.
312       See the smokeping_install document.
313

1.38 to 1.40

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

1.34 to 1.37

322       The RemoteFPing probe
323           The configuration of this probe was moved from the Targets section
324           to the Probes section, as all the variables are really probe-
325           specific. The moved variables were "rhost", "rbinary" and "rhost".
326
327       Logging changes
328           The "smokeping" daemon now warns at startup if syslog support is
329           not turned on in the config file. This is because many diagnostic
330           messages will otherwise get lost.
331
332       Concurrent probes
333           Each probe now runs in its own process, instead of them all running
334           sequentially in one process. This makes it possible to specify
335           different step lengths for different probes. You can get the old
336           behaviour back by setting 'concurrentprobes = no'.
337
339       Copyright 2005 by Niko Tyni.
340

LICENSE

342       This program is free software; you can redistribute it and/or modify it
343       under the terms of the GNU General Public License as published by the
344       Free Software Foundation; either version 2 of the License, or (at your
345       option) any later version.
346
347       This program is distributed in the hope that it will be useful, but
348       WITHOUT ANY WARRANTY; without even the implied warranty of
349       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
350       General Public License for more details.
351
352       You should have received a copy of the GNU General Public License along
353       with this program; if not, write to the Free Software Foundation, Inc.,
354       675 Mass Ave, Cambridge, MA 02139, USA.
355

AUTHOR

357       Niko Tyni <ntyni@iki.fi>
358

SEE ALSO

360       The other Smokeping documents, especially smokeping_config.
361
362
363
3642.8.2                             2022-01-22              SMOKEPING_UPGRADE(7)
Impressum