Linux_post_install/DOC/howto/event-trigger.md

How-To: pos system event-trigger

State-based threshold monitors: each line of event.env is an independent rule; when a rule's check crosses its threshold you get one alert (plus one recovery message when it clears). Alerts go through lib/notify.sh — Telegram by default, NOTIFY_PLATFORM for more.

pos system event-trigger config          # interactive rule editor
pos system event-trigger list            # rules + live check values
pos system event-trigger enable 5m       # evaluate every 5 minutes via systemd
pos system event-trigger status          # timer + rule count
pos system event-trigger disable         # stop monitoring
pos system event-trigger run --dry-run   # preview what would fire

---

Rule format

One rule per line in ~/.config/linux_post_install/event.env (chmod 600):

["<message>" if ] <check-command> <op> <threshold>

Part	Meaning
"<message>" if	Optional custom alert text (quote-stripped); without it the message is auto-composed
<check-command>	Any shell command; its first numeric output is the value (pipes/args fine)
<op>	> < >= <= == !=
<threshold>	Number with optional unit suffix — 60c, 80%, 10g all work

The operator is detected as the rightmost op threshold pair in the line, so check commands containing their own >/< (redirection, awk) don't confuse it.

Examples:

# event.env
"CPU too hot" if sensors -u coretemp-isa-0000 | awk '/Package id 0:/{f=1} f && /temp1_input:/{print $2; exit}' > 60c
"Disk nearly full" if df -P / | awk 'NR==2{print $5+0}' > 80%
"Load high" if uptime | sed 's/.*load average: //; s/,.*//' >= 4

A ready-made starter set (CPU, memory, disk space/health, NVMe, network, processes) lives in config/event-rules.template — copy it to ~/.config/linux_post_install/event.env or add the lines you want via pos system event-trigger config.

Behavior:

• The check runs on every pass. Non-numeric/empty output, or an unparseable line → the rule is skipped with a warning (other rules still run). The run summary reports how many rules evaluated and how many were skipped.
• sensors rules need lm-sensors installed (preinstall.sh installs it; verify with sensors -u before adding a rule — sensor names differ by chip, check sensors -u output for the real *_input key). Gotcha: a bare grep -m1 temp1_input can match a different chip's temp1_input first (e.g. acpitz's case temp) instead of the CPU — pin the chip with sensors -u <chip> (find it in sensors -u, e.g. coretemp-isa-0000) as in the example above.
• Alerts fire once when the condition turns true, and once more when it recovers — a hot CPU for two hours is one message, not twenty.
• State is tracked per rule in ~/.local/share/linux_post_install/eventer/state/ (keyed by a hash of the rule line — editing a rule resets its state).

Scheduling

enable [interval] installs a systemd user timer (pos-event-trigger.timer

• oneshot .service that runs pos system event-trigger run). Intervals: 5m 10m 15m 30m 45m hourly 2h 6h 12h daily weekly, or a raw OnCalendar=…. Requires a reachable user systemd manager; run sudo loginctl enable-linger $USER once so timers fire without login (the tool tries this and warns if it can't).

Alerting

run sends via lib/notify.sh notify_send, which delivers to every platform in NOTIFY_PLATFORM (default telegram; comma-separated = fan out). Adding a Matrix/Synapse sender later needs no changes here — see DOC/DEV.md → Alerting.

---

Related

• Reference: DOC/POS.md → system
• Notifications: communication / lib/notify.sh