ALERTS.CFG

Section: File Formats (5)
Updated: Version 4.3.30: 4 Sep 2019
Index Return to Main Contents

 

alerts.cfg - Configuration for for xymond_alert module

 

~xymon/server/etc/alerts.cfg

 

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 recipients 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
10.0.0.1 www1.foo.com
subpage db Database servers
10.0.0.2 db1.foo.com

Then the "All servers" page is found with PAGE=servers, the "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 would 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 PAGE=%^$ 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 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

Then the hosts in the Web-group can be matched with DISPLAYGROUP=Web, and the database servers can be matched with DISPLAYGROUP="Production databases". Note that you can also use regular expressions, e.g. DISPLAYGROUP=%database. If there is no group-setting for the host, use "DISPLAYGROUP=NONE".

Rule excluding a group by matching the display-group string.
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 name.
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 startup-script).
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), 'd' (days) or 'w' (weeks). Note that this is the age of the alert event, not of the current colour: the event begins when the status first goes into an alerting colour and deliberately survives a later yellow→red change. A status that has been yellow for two hours therefore matches DURATION>10 the instant it turns red. Use FOR when you mean the colour's own age.
Rule matching an alert only once the rule's colour has held continuously for at least the given time - the counterpart of DURATION for damping short-lived transitions. E.g. COLOR=red FOR=10 alerts on a red that has lasted ten minutes, whether it arrived from green or from yellow. The time is specified as for DURATION.

The effective colour - the rule's and the recipient's together - must be a single one: with several, a later generalisation of FOR to whole-condition hold time would not be compatible, so such a rule is reported and the FOR ignored. A FOR on the rule line with COLOR= on the recipient is therefore accepted: the recipient names the colour.

Where both the rule and a recipient set FOR, the longer applies, as for the other filters: a recipient narrows what the rule lets through, it never widens it. There is no FOR< - damping needs only a lower bound, and DURATION< already covers early-window routing.

A period where the test stopped reporting counts towards the hold time only if the status comes back the same colour, and only up to four times the report validity that applied when the silence began (two hours by default). A test absent for a month therefore does not return claiming a month-long hold time.

Send recovery and disabled-state messages to matching recipients. This can be set on a rule or on an individual recipient.
Suppress recovery and disabled-state messages. On a recipient, this overrides a RECOVERED setting inherited from the rule.
Send "notify" messages to matching recipients. This type of message is sent when a host or test is disabled or enabled.
Suppress notify messages. On a recipient, this overrides a NOTICE setting inherited from the rule.

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, respectively.
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.
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. "PAGER" produces an empty message body. "SCRIPT" is a brief message template for scripts.
How often an alert gets repeated. Time is a number optionally followed by 'm' (minutes, default), 'h' (hours), 'd' (days) or 'w' (weeks).
The alert is sent to this recipient ONLY if no other recipients received an alert for this event.

For example, place an UNMATCHED recipient after more specific rules to provide a fallback:

HOST=database.example.com SERVICE=cpu
	MAIL database-team@example.com
HOST=%.*
	MAIL operations@example.com UNMATCHED

The operations recipient is used only when an earlier recipient did not receive the alert, so recipient order is significant.

Stop looking for more recipients after this one matches. This is implicit on IGNORE recipients.
Suppress paging, recovery and disabled-state messages for this recipient. Notify messages are still allowed.
You can specify rule filters after a recipient on the same logical line. This limits the alerts sent to that recipient. End a physical line with a backslash to continue the logical line. If multiple recipients occur on one logical line, trailing rule filters apply to all recipients on that line.

FORMAT, REPEAT, STOP, UNMATCHED and NOALERT are recipient-only modifiers. They can also be placed on a following line, where they modify the preceding recipient.

 

It is possible to use macros in the configuration file. To define a macro:

$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 used.

 

Alerts can go out via custom scripts, by using the SCRIPT keyword for a recipient. Such scripts have access to the following environment variables:

The color of the alert: "red", "yellow" or "purple".
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 commas
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.
Unique identifier derived from the host, service and event start time.

Available host metadata is also exported as XMH_* environment variables. See xymon-xmh(5) for the full list and descriptions.

 

xymond_alert(8), xymond(8), xymon(7), xymon-xmh(5), the "Configuring Xymon Alerts" guide in the Online documentation.

 

NAME
SYNOPSIS
DESCRIPTION
FILE FORMAT
RULES
RECIPIENTS
MACROS
ALERT SCRIPTS
SEE ALSO
This document was created by mandoc, using the manual pages.