alerts.cfg - Configuration for for xymond_alert module
The alerts.cfg file controls the sending of alerts by Xymon when monitoring
detects a failure.
The configuration file consists of rules
, that may have one or more
associated. A recipient specification may include additional
rules that limit the circumstances when this recipient is eligible for
receiving an alert.
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.
A rule consists of one of more filters using these keywords:
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:
page servers All Servers
subpage web Webservers
subpage db Database servers
Then the "All servers" page is found with PAGE=servers
"Webservers" page is PAGE=servers/web
and the "Database
servers" page is PAGE=servers/db
. Note that you can also use
regular expressions to specify the page name, e.g. PAGE=%.*/db
find the "Database servers" page regardless of where this page was
placed in the hierarchy.
The PAGE name of top-level page is an empty string. To match this, use
to match the empty string.
Rule excluding an alert if the pagename matches.
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:
group Production databases
Then the hosts in the Web-group can be matched with DISPLAYGROUP=Web
the database servers can be matched with DISPLAYGROUP="Production
. Note that you can also use regular expressions, e.g.
. If there is no group-setting for the host, use
Rule excluding a group by matching the
Rule matching an alert by the hostname.
Rule excluding an alert by matching the hostname.
Rule matching an alert by the service name.
Rule excluding an alert by matching the service
Rule matching an alert by the group name. Groupnames are
assigned to a status via the GROUP setting in the analysis.cfg file.
Rule excluding an alert by the group name. Groupnames
are assigned to a status via the GROUP setting in the analysis.cfg file.
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 hosts.cfg(5)
using the CLASS tag, or a client
running on the server can set the class (via a parameter to the client
Rule excluding an alert by the class name.
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.
Rule matching an alert by the time-of-day. This is
specified as the DOWNTIME timespecification in the hosts.cfg file.
Rule excluding an alert by the time-of-day. This
is specified as the DOWNTIME timespecification in the hosts.cfg file.
Rule matching 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).
Rule matches if the alert has recovered from an alert state.
Rule matches if the message is a "notify" message. This
type of message is sent when a host or test is disabled or enabled.
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.
The recipients are listed after the initial rule. The following keywords can be
used to define recipients:
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,
SCRIPT /path/to/script recipientID
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
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.
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.
How often an alert gets repeated. As with DURATION, time is a
number optionally followed by 'm', 'h' or 'd'.
The alert is sent to this recipient ONLY if no other recipients
received an alert for this event.
Stop looking for more recipients after this one matches. This is
implicit on IGNORE recipients.
You can specify rules for a recipient also. This limits the alerts
sent to this particular recipient.
It is possible to use macros
in the configuration file. To define a
$MYMACRO=text extending to end of line
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.
It is possible to nest macros, as long as the macro is defined before it is
Alerts can go out via custom scripts, by using the SCRIPT keyword for a
recipient. Such scritps have access to the following environment variables:
The full text of the status log triggering the alert
The "cookie" that can be used to acknowledge the alert
The recipientID from the SCRIPT entry
The name of the host that the alert is about
The IP-address of the host that has a problem
The name of the service that the alert is about
The numeric code for the service. From the SVCCODES definition.
HOSTNAME.SERVICE that the alert is about.
As BBHOSTSVC, but dots in the hostname replaced with
A 22-digit number made by BBSVCNUM, MACHIP and ACKCODE.
Is "0" if the service is alerting, "1" if
the service has recovered, "2" if the service was disabled.
Timestamp when the current status (color) began.
Number of seconds the service has been down.
When recovered, holds the text "Event duration : N"
where N is the DOWNSECS value.
Line-number in the alerts.cfg file that caused the script to be
invoked. Can be useful when troubleshooting alert configuration rules.
xymond_alert(8), xymond(8), xymon(7), the "Configuring Xymon Alerts"
guide in the Online documentation.