ALERTS.CFG(5)

💖 ALERTS.CFG(5) 💖

okay bestie, listen up — this is the manual page for alerts.cfg, and it lives in the File Formats Manual section. It's the file that tells Xymon who to scream at when stuff breaks. no cap. 🫶

---

✨ NAME ✨

alerts.cfg — the config file for the xymond_alert module 💅

---

🌸 SYNOPSIS 🌸

~xymon/server/etc/alerts.cfg

---

🦋 DESCRIPTION 🦋

The alerts.cfg file is literally the main character that controls how Xymon sends out alerts when its monitoring catches a failure. it's giving "who gets notified and when". 💖

---

🎀 FILE FORMAT 🎀

So the file is made up of rules, and each rule can have one or more recipients attached to it. And a recipient spec? it can also carry extra rules that narrow down exactly when that recipient is allowed to get the alert. very demure, very mindful. ✨

Blank lines? ignored. Lines starting with a hash mark (#)? also ignored, they're comments. and if a line is getting way too long, you can break it by putting a backslash at the end and continuing the entry on the next line. slay. 💅

---

👑 RULES 👑

A rule is made of one or more filters, using these keywords:

• PAGE=targetstring — matches an alert by the name of the page in Xymon. This is the path of the page as defined in the hosts.cfg file. like, check 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

So 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. also bestie, you can use regular expressions for the page name too — like PAGE=%.*/db would find the "Database servers" page no matter where it sits in the hierarchy. iconic. 🦋

Oh and the PAGE name of a top-level page is an empty string. to match that, use PAGE=%^$ to match the empty string.

• EXPAGE=targetstring — excludes an alert if the pagename matches. 🙈
• DISPLAYGROUP=groupstring — matches an alert by the text of the display-group (that's the 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. for example, with 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

the hosts in the Web-group can be matched with DISPLAYGROUP=Web, and the database servers can be matched with DISPLAYGROUP="Production databases". you can also use regular expressions, like DISPLAYGROUP=%database. And if there's no group-setting for the host, use "DISPLAYGROUP=NONE". 💜

• EXDISPLAYGROUP=groupstring — excludes a group by matching the display-group string.
• HOST=targetstring — matches an alert by the hostname.
• EXHOST=targetstring — excludes an alert by matching the hostname.
• SERVICE=targetstring — matches an alert by the service name.
• EXSERVICE=targetstring — excludes an alert by matching the service name.
• GROUP=groupname — matches an alert by the group name. Groupnames get assigned to a status via the GROUP setting in the analysis.cfg file.
• EXGROUP=groupname — excludes an alert by the group name. Groupnames get assigned to a status via the GROUP setting in the analysis.cfg file.
• CLASS=classname — matches 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).
• EXCLASS=classname — excludes an alert by the class name.
• COLOR=color[,color] — matches 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.
• TIME=timespecification — matches an alert by the time-of-day. This is specified as the DOWNTIME timespecification in the hosts.cfg file.
• EXTIME=timespecification — excludes an alert by the time-of-day. This is specified as the DOWNTIME timespecification in the hosts.cfg file.
• DURATION>time, DURATION<time — matches an alert if the event has lasted longer/shorter than the given duration. like DURATION>1h (lasted longer than 1 hour) or DURATION<30 (only sends alerts the first 30 minutes). The duration is a number, optionally followed by 'm' (minutes, the default), 'h' (hours) or 'd' (days).
• RECOVERED — the rule matches if the alert has recovered from an alert state. 🩹
• NOTICE — the rule matches if the message is a "notify" message. This type of message gets sent when a host or test is disabled or enabled.

And the targetstring? it's either a simple pagename, hostname or servicename, OR a % followed by a Perl-compatible regular expression. For example, "HOST=%www(.*)" will match any hostname that begins with "www". Same deal for the groupname setting. 💫

---

💌 RECIPIENTS 💌

The recipients get listed after the initial rule. These keywords define them:

• MAIL address[,address] — a recipient who receives an e-mail alert. Takes one parameter: the e-mail address. The strings "&host&", "&service&" and "&color&" in an address get replaced with the hostname, service and color of the alert, respectively. 📧
• SCRIPT /path/to/script recipientID — a recipient that invokes a script. Takes two parameters: the script filename, and the recipient that gets passed to the script. The strings "&host&", "&service&" and "&color&" in the recipientID get replaced with the hostname, service and color of the alert, respectively.
• IGNORE — this defines a recipient that does NOT trigger any alerts, and it also terminates the search for more recipients. Super useful if you've got a rule handling most alerts, but there's just that one particular server where you don't want cpu alerts on Monday morning. 🙈

Heads up bestie: the IGNORE recipient always has the STOP flag defined, so when the IGNORE recipient is matched, no more recipients will be considered. So where you put this recipient in your set of recipients matters. 💀

• FORMAT=formatstring — the 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.
• REPEAT=time — how often an alert gets repeated. Just like with DURATION, time is a number optionally followed by 'm', 'h' or 'd'.
• UNMATCHED — the alert is sent to this recipient ONLY if no other recipients received an alert for this event. 🫶
• STOP — stop looking for more recipients after this one matches. This is implicit on IGNORE recipients.
• Rules — you can specify rules for a recipient too. This limits the alerts sent to this particular recipient. 💅

---

🧚 MACROS 🧚

Bestie, you can use macros in the config file. To define one:

$MYMACRO=text extending to end of line

Once a macro is defined, you can use it all throughout the file. Wherever the text $MYMACRO appears, it gets substituted with the text of the macro before any processing of rules and recipients happens. ✨

And yes, you can nest macros — as long as the macro is defined before it's used. 🌈

---

🔥 ALERT SCRIPTS 🔥

Alerts can go out via custom scripts by using the SCRIPT keyword for a recipient. Those scripts get access to these environment variables:

• BBALPHAMSG — the full text of the status log triggering the alert
• ACKCODE — the "cookie" that can be used to acknowledge the alert
• RCPT — the recipientID from the SCRIPT entry
• BBHOSTNAME — the name of the host that the alert is about
• MACHIP — the IP-address of the host that has a problem
• BBSVCNAME — the name of the service that the alert is about
• BBSVCNUM — the numeric code for the service. From the SVCCODES definition.
• BBHOSTSVC — HOSTNAME.SERVICE that the alert is about.
• BBHOSTSVCCOMMAS — as BBHOSTSVC, but dots in the hostname replaced with commas
• BBNUMERIC — a 22-digit number made by BBSVCNUM, MACHIP and ACKCODE.
• RECOVERED — is "0" if the service is alerting, "1" if the service has recovered, "2" if the service was disabled.
• EVENTSTART — timestamp when the current status (color) began.
• SECS — number of seconds the service has been down.
• DOWNSECSMSG — when recovered, holds the text "Event duration : N" where N is the DOWNSECS value.
• CFID — line-number in the alerts.cfg file that caused the script to be invoked. Can be useful when troubleshooting alert configuration rules. 🔍

---

🌟 SEE ALSO 🌟

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

---

k that's literally the whole thing bestie, go forth and configure your alerts 💖✨

Xymon — Version 4.3.30: 4 Sep 2019 🎀 mwah, love u, bye 💅🦋