1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of ALERTS.CFG</TITLE>
</HEAD><BODY>
<H1>ALERTS.CFG</H1>
Section: File Formats (5)<BR>Updated: Version 4.3.17: 23 Feb 2014<BR><A HREF="#index">Index</A>
<A HREF="../index.html">Return to Main Contents</A><HR>
<A NAME="lbAB"> </A>
<H2>NAME</H2>
alerts.cfg - Configuration for for xymond_alert module
<P>
<A NAME="lbAC"> </A>
<H2>SYNOPSIS</H2>
<B>~xymon/server/etc/alerts.cfg</B>
<P>
<A NAME="lbAD"> </A>
<H2>DESCRIPTION</H2>
The alerts.cfg file controls the sending of alerts by Xymon
when monitoring detects a failure.
<P>
<A NAME="lbAE"> </A>
<H2>FILE FORMAT</H2>
The configuration file consists of <B>rules</B>, that may have one
or more <B>recipients</B> associated. A recipient specification may
include additional rules that limit the circumstances when this
recipient is eligible for receiving an alert.
<P>
Blank lines and lines starting with a hash mark (#) are treated as
comments and ignored. Long lines can be broken up by putting a
backslash at the end of the line and continuing the entry on the
next line.
<P>
<A NAME="lbAF"> </A>
<H2>RULES</H2>
A rule consists of one of more filters using these keywords:
<P>
<B>PAGE=targetstring</B>
Rule matching an alert by the name of the page in Xymon. This is the path of
the page as defined in the hosts.cfg file. E.g. if you have this setup:
<DL COMPACT>
<DT><DD>
<PRE>
page servers All Servers
subpage web Webservers
10.0.0.1 www1.foo.com
subpage db Database servers
10.0.0.2 db1.foo.com
</PRE>
</DL>
<P>
Then the "All servers" page is found with <B>PAGE=servers</B>, the
"Webservers" page is <B>PAGE=servers/web</B> and the "Database servers"
page is <B>PAGE=servers/db</B>. Note that you can also use regular expressions
to specify the page name, e.g. <B>PAGE=%.*/db</B> would find the "Database
servers" page regardless of where this page was placed in the hierarchy.
<P>
The PAGE name of top-level page is an empty string. To match this, use
<B>PAGE=%^$</B> to match the empty string.
<P>
<P>
<B>EXPAGE=targetstring</B>
Rule excluding an alert if the pagename matches.
<P>
<B>DISPLAYGROUP=groupstring</B>
Rule matching an alert by the text of the display-group (text following the group,
group-only, group-except heading) in the hosts.cfg file. "groupstring" is the text
for the group, stripped of any HTML tags. E.g. if you have this setup:
<DL COMPACT>
<DT><DD>
<PRE>
group Web
10.0.0.1 www1.foo.com
10.0.0.2 www2.foo.com
group Production databases
10.0.1.1 db1.foo.com
</PRE>
</DL>
<P>
Then the hosts in the Web-group can be matched with <B>DISPLAYGROUP=Web</B>,
and the database servers can be matched with <B>DISPLAYGROUP="Production databases"</B>.
Note that you can also use regular expressions, e.g. <B>DISPLAYGROUP=%database</B>.
If there is no group-setting for the host, use "DISPLAYGROUP=NONE".
<P>
<B>EXDISPLAYGROUP=groupstring</B>
Rule excluding a group by matching the display-group string.
<P>
<B>HOST=targetstring</B>
Rule matching an alert by the hostname.
<P>
<B>EXHOST=targetstring</B>
Rule excluding an alert by matching the hostname.
<P>
<B>SERVICE=targetstring</B>
Rule matching an alert by the service name.
<P>
<B>EXSERVICE=targetstring</B>
Rule excluding an alert by matching the service name.
<P>
<B>GROUP=groupname</B>
Rule matching an alert by the group name. Groupnames are assigned to a status via the GROUP
setting in the analysis.cfg file.
<P>
<B>EXGROUP=groupname</B>
Rule excluding an alert by the group name. Groupnames are assigned to a status via the GROUP
setting in the analysis.cfg file.
<P>
<B>CLASS=classname</B>
Rule matching an alert by the class that the host belongs to. By default, the classname is
the operating system name; you can set another class either in
<I><A HREF="../man5/hosts.cfg.5.html">hosts.cfg</A>(5)</I>
using the CLASS tag, or a client running on the server can set the class (via a parameter
to the client startup-script).
<P>
<B>EXCLASS=classname</B>
Rule excluding an alert by the class name.
<P>
<B>COLOR=color[,color]</B>
Rule matching an alert by color. Can be "red", "yellow", or "purple". The forms "!red", "!yellow" and "!purple" can also be used to NOT send an alert if the color is the specified one.
<P>
<B>TIME=timespecification</B>
Rule matching an alert by the time-of-day. This is specified as the DOWNTIME timespecification in the hosts.cfg file.
<P>
<B>DURATION>time, DURATION<time</B>
Rule matcing an alert if the event has lasted longer/shorter than the given duration. E.g. DURATION>1h (lasted longer than 1 hour) or DURATION<30 (only sends alerts the first 30 minutes). The duration is specified as a number, optionally followed by 'm' (minutes, default), 'h' (hours) or 'd' (days).
<P>
<B>RECOVERED</B>
Rule matches if the alert has recovered from an alert state.
<P>
<B>NOTICE</B>
Rule matches if the message is a "notify" message. This type of message is sent when a host or test is disabled or enabled.
<P>
The "targetstring" is either a simple pagename, hostname or servicename, OR a '%'
followed by a Perl-compatible regular expression. E.g. "HOST=%www(.*)" will match
any hostname that begins with "www". The same for the "groupname" setting.
<P>
<A NAME="lbAG"> </A>
<H2>RECIPIENTS</H2>
The recipients are listed after the initial rule. The following keywords can be used to define recipients:
<P>
<B>MAIL address[,address]</B>
Recipient who receives an e-mail alert. This takes one parameter, the e-mail address.
The strings "&host&", "&service&" and "&color&" in an address will be replaced with
the hostname, service and color of the alert, respectively.
<P>
<B>SCRIPT /path/to/script recipientID</B>
Recipient that invokes a script. This takes two parameters: The script filename, and the recipient that gets passed to the script.
The strings "&host&", "&service&" and "&color&" in the recipientID will be replaced with
the hostname, service and color of the alert, respectively.
<P>
<B>IGNORE</B>
This is used to define a recipient that does NOT trigger any alerts, and also terminates the
search for more recipients. It is useful if you have a rule that handles most alerts, but
there is just that one particular server where you don't want cpu alerts on Monday morning.
Note that the IGNORE recipient always has the STOP flag defined, so when the IGNORE recipient
is matched, no more recipients will be considered. So the location of this recipient in your
set of recipients is important.
<P>
<B>FORMAT=formatstring</B>
Format of the text message with the alert. Default is "TEXT" (suitable for e-mail alerts). "PLAIN" is the same as text, but without the URL link to the status webpage. "SMS" is a short message with no subject for SMS alerts. "SCRIPT" is a brief message template for scripts.
<P>
<B>REPEAT=time</B>
How often an alert gets repeated. As with DURATION, time is a number optionally followed by 'm', 'h' or 'd'.
<P>
<B>UNMATCHED</B>
The alert is sent to this recipient ONLY if no other recipients received an alert for this event.
<P>
<B>STOP</B>
Stop looking for more recipients after this one matches. This is implicit on IGNORE recipients.
<P>
<B>Rules</B>
You can specify rules for a recipient also. This limits the alerts sent to this particular recipient.
<P>
<A NAME="lbAH"> </A>
<H2>MACROS</H2>
It is possible to use <B>macros</B> in the configuration file. To define a macro:
<P>
<TT> </TT>$MYMACRO=text extending to end of line<BR>
<P>
After the definition of a macro, it can be used throughout the file. Wherever the
text $MYMACRO appears, it will be substituted with the text of the macro before
any processing of rules and recipients.
<P>
It is possible to nest macros, as long as the macro is defined before it is used.
<P>
<A NAME="lbAI"> </A>
<H2>ALERT SCRIPTS</H2>
Alerts can go out via custom scripts, by using the SCRIPT keyword for a recipient.
Such scritps have access to the following environment variables:
<P>
<B>BBALPHAMSG</B>
The full text of the status log triggering the alert
<P>
<B>ACKCODE</B>
The "cookie" that can be used to acknowledge the alert
<P>
<B>RCPT</B>
The recipientID from the SCRIPT entry
<P>
<B>BBHOSTNAME</B>
The name of the host that the alert is about
<P>
<B>MACHIP</B>
The IP-address of the host that has a problem
<P>
<B>BBSVCNAME</B>
The name of the service that the alert is about
<P>
<B>BBSVCNUM</B>
The numeric code for the service. From the SVCCODES definition.
<P>
<B>BBHOSTSVC</B>
HOSTNAME.SERVICE that the alert is about.
<P>
<B>BBHOSTSVCCOMMAS</B>
As BBHOSTSVC, but dots in the hostname replaced with commas
<P>
<B>BBNUMERIC</B>
A 22-digit number made by BBSVCNUM, MACHIP and ACKCODE.
<P>
<B>RECOVERED</B>
Is "0" if the service is alerting, "1" if the service has
recovered, "2" if the service was disabled.
<P>
<B>EVENTSTART</B>
Timestamp when the current status (color) began.
<P>
<B>SECS</B>
Number of seconds the service has been down.
<P>
<B>DOWNSECSMSG</B>
When recovered, holds the text "Event duration : N" where N is the DOWNSECS value.
<P>
<B>CFID</B>
Line-number in the alerts.cfg file that caused the script to be invoked.
Can be useful when troubleshooting alert configuration rules.
<P>
<A NAME="lbAJ"> </A>
<H2>SEE ALSO</H2>
<A HREF="../man8/xymond_alert.8.html">xymond_alert</A>(8), <A HREF="../man8/xymond.8.html">xymond</A>(8), <A HREF="../man7/xymon.7.html">xymon</A>(7), the "Configuring Xymon Alerts"
guide in the Online documentation.
<P>
<P>
<HR>
<A NAME="index"> </A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">FILE FORMAT</A><DD>
<DT><A HREF="#lbAF">RULES</A><DD>
<DT><A HREF="#lbAG">RECIPIENTS</A><DD>
<DT><A HREF="#lbAH">MACROS</A><DD>
<DT><A HREF="#lbAI">ALERT SCRIPTS</A><DD>
<DT><A HREF="#lbAJ">SEE ALSO</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 09:41:02 GMT, February 23, 2014
</BODY>
</HTML>
|
