XYMOND_ALERT(8)

💖 XYMOND_ALERT(8) 💖

okay so bestie, this is a page from the System Manager's Manual — it's xymond_alert, and she's a whole vibe. buckle up 🎀

---

✨ NAME ✨

xymond_alert — the xymond worker module that sends out alerts, no cap 📣

---

✨ SYNOPSIS ✨

xymond_channel --channel=page xymond_alert [options]

---

✨ DESCRIPTION ✨

so xymond_alert is a worker module for xymond, and the way she gets invited to the party is normally through the xymond_channel(8) program. she receives xymond page- and ack-messages from the "page" channel via stdin, and uses those to send out alerts about failed and recovered hosts and services. like, she's literally the one telling you your server is going through it 😭

the whole way she operates is controlled by the alerts.cfg(5) file. that file holds the definition of rules and recipients — which is fancy talk for who gets alerts, how often, and for what servers etc. she's not out here freestyling, she's following the config 💅

---

✨ OPTIONS ✨

• --config=FILENAME — sets the filename for the alerts.cfg file. default is "etc/alerts.cfg" sitting below the Xymon server directory. slay, configurable 💖
• --dump-config — dumps the configuration after parsing it. lowkey useful for tracking down problems with configuration file errors, iykyk 🔍
• --checkpoint-file=FILENAME — the file where the current state of the xymond_alert module gets saved. and when she starts up, she also reads this file to restore the previous state. memory queen 👑
• --checkpoint-interval=N — defines how often (in seconds) the checkpoint-file is saved. ⏱️
• --cfid — if this option is present, alert messages will include a line with "cfid:N" where N is the linenumber in the alerts.cfg file that caused this message to be sent. super useful for tracking down problems with duplicate alerts. periodt 🧚
• --test HOST SERVICE [options] — shows which alert rules match the given HOST/SERVICE combination. useful to debug configuration problems, and see what rules are used for an alert. 🕵️‍♀️

the possible options are:

• --color=COLORNAME — the COLORNAME parameter is the color of the alert: red, yellow or purple.
• --duration=MINUTES — the MINUTES parameter is the duration of the alert in minutes.
• --group=GROUPNAME — the GROUPNAME parameter is a groupid string from the analysis.cfg file.
• --time=TIMESTRING — the TIMESTRING parameter is the time-of-day for the alert, expressed as an absolute time in the epoch format (seconds since Jan 1 1970). this is easily obtained with the GNU date utility using the "+%s" output format. iconic 🌈

• --trace=FILENAME — send trace output to FILENAME. this allows for more detailed analysis of how alerts trigger, without having the full debugging enabled. bestie said just the highlights ✨
• --debug — enable debugging output. 🐛

---

✨ HOW XYMON DECIDES WHEN TO SEND ALERTS ✨

okay this is the part where we get into the lore 📖

the xymond_alert module is responsible for sending out all alerts. when a status first goes to one of the ALERTCOLORS, xymond_alert is notified of this change. she notes that the status is now in an alert state, and records the timestamp when this event started, and adds the alert to the list of statuses that may potentially trigger one or more alert messages. she's keeping receipts 📝

this list is then matched against the alerts.cfg configuration. this happens at least once a minute, but may happen more often. e.g. when a status first goes into an alert state, this will always trigger the matching to happen.

when scanning the configuration, xymond_alert looks at all of the configuration rules. she also checks the DURATION setting against how long time has elapsed since the event started — i.e. against the timestamp logged when xymond_alert first heard of this event.

when an alert recipient is found, the alert is sent and it is recorded when this recipient is due for his next alert message, based on the REPEAT setting defined for this recipient. the next time xymond_alert scans the configuration for what alerts to send, she will still find this recipient because all of the configuration rules are fulfilled — but an alert message will not be generated until the repeat interval has elapsed. patience is a virtue bestie 🫶

it can happen that a status first goes yellow and triggers an alert, and later it goes red — e.g. a disk filling up. in that case, xymond_alert clears the internal timer for when the next (repeat) alert is due for all recipients. you generally want to be told when something that has been in a warning state becomes critical, so in that case the REPEAT setting is ignored and the alert is sent. this only happens the first time such a change occurs — if the status switches between yellow and red multiple times, only the first transition from yellow→red causes this override. one-time exception, we don't do reruns 💀

when a status recovers, a recovery message may be sent — depending on the configuration — and then xymond_alert forgets everything about this status. so the next time it goes into an alert state, the entire process starts all over again. clean slate, main character energy 👑

---

✨ ENVIRONMENT ✨

• MAIL — the first part of a command line used to send out an e-mail with a subject, typically set to "/usr/bin/mail -s". xymond_alert will add the subject and the mail recipients to form the command line used for sending out email alerts. 💌
• MAILC — the first part of a command line used to send out an e-mail without a subject. typically this will be "/usr/bin/mail". xymond_alert will add the mail recipients to form the command line used for sending out email alerts.

---

✨ FILES ✨

• ~xymon/server/etc/alerts.cfg

---

✨ SEE ALSO ✨

alerts.cfg(5), xymond(8), xymond_channel(8), xymon(7)

---

and that's the whole page bestie 🦋 ngl this one's a banger.

Xymon, Version 4.3.30, dated 4 Sep 2019 — mwah, iconic, no notes 💅✨