1SMOKEPING_UPGRADE(7) SmokePing SMOKEPING_UPGRADE(7)
2
6 smokeping_upgrade - Notes on upgrading Smokeping
7
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 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 If a version is not listed, there are no known problems in upgrading to
23 it from the previous release.
24 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
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 cropper/lib/scriptaculous.js?load=builder,effects,dragdrop
35
37 The new SmokeTrace tool was added to SmokePing. For setup instructions
38 read the smoketrace manual page.
39
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
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 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
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
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 This version also introduces three new probes using the new echoping
68 plugin interface introduced in version 6:
69 • EchoPingDNS
71 • EchoPingLDAP
73 • EchoPingWhois
75 See the smokeping_examples document for simple examples of using these
77 probes.
78 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
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
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 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
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 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
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 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
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 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 CONFIGURATION
142 The configuration syntax has stayed mostly the same, except for the
143 issues below.
144 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 ++ PROBE_CONF
151 lines should fix this (for any number of '+', obviously.)
153 The existence of a PROBE_CONF section makes smokeping exit with an
155 error message at parse time.
156 Note for distributors: these lines could easily be removed
158 automatically during upgrade.
159 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 Additionally, "probe" must now precede "host", for reasons that
167 have to do with the current implementation of mandatory variable
168 checking.
169 Both of these errors are recognized at parse time and produce error
171 messages accordingly.
172 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 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 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 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 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 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 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 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 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 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 In addition to this, some probes have had minor incompatible changes to
231 their configuration.
232 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 FPing6
239 This probe is also now derived from FPing and supports all the
240 variables FPing does.
241 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 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 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 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 Any extra arguments for "curl" can now be specified in the
264 "extraargs" variable.
265 EchoPingHttp
267 The default timeout of this probe has been raised to 10 seconds.
268 EchoPingHttps
270 The default timeout of this probe has been raised to 10 seconds.
271 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 LDAP
277 The "filter" variable is now mandatory, as Net::LDAP bails out
278 without it.
279 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 Radius
286 The "sleeptime" variable was changed to "mininterval" and its
287 semantics were changed accordingly. See the LDAP explanation above.
288 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 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 TelnetIOSPing
302 The name of this probe was changed: it now starts with a capital
303 letter like all the others do.
304 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 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
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
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 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 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
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 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 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
357 Niko Tyni <ntyni@iki.fi>
358
360 The other Smokeping documents, especially smokeping_config.
3612.8.2 2022-07-23 SMOKEPING_UPGRADE(7)