Host-side alerts to a Matrix room, for the things that must never be missed.
  • Python 71.8%
  • Shell 28.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
nnra e260171959 feat: Friendlier CLI
- sema lists tools with one-line descriptions
- Running a tool without arguments shows short help, --help adds details
- "needs root, run: sudo ..." instead of permission errors and tracebacks
- sema matrix never sends an empty message, and says "Sent." in a terminal
- sema smart prints a per-disk summary when run by hand, stays quiet from the timer
- install.sh reloads systemd right after removing old units

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 07:04:06 +01:00
systemd feat: sema-* commands and the sema dispatcher 2026-11-04 06:58:45 +01:00
config.example feat: sema-* commands and the sema dispatcher 2026-11-04 06:58:45 +01:00
install.sh feat: Friendlier CLI 2026-11-04 07:04:06 +01:00
LICENSE init 2026-11-04 06:19:49 +01:00
README.md feat: sema-* commands and the sema dispatcher 2026-11-04 06:58:45 +01:00
sema feat: Friendlier CLI 2026-11-04 07:04:06 +01:00
sema-guard feat: Friendlier CLI 2026-11-04 07:04:06 +01:00
sema-matrix feat: Friendlier CLI 2026-11-04 07:04:06 +01:00
sema-smart feat: Friendlier CLI 2026-11-04 07:04:06 +01:00

sema

sema (σῆμα) - signal

Warning

This was made with Claude Opus 5.5.
It's made for personal use only, so don't expect any kind of support.

Host-side alerts to a Matrix room, for the things that must never be missed.
ZFS faults, dying drives, failed services and SSH logins go straight to Matrix, no containers involved.
Python 3.11+, standard library only.

Installation

  • Install, safe to run again after every change
sudo sh install.sh
  • Save the bot's access token
sudo install -m600 /dev/stdin /etc/sema/token
  • Set the room
sudoedit /etc/sema/config
What Where
Settings /etc/sema/config
Bot access token /etc/sema/token (root only)
Commands /usr/local/bin/{sema,sema-matrix,sema-guard,sema-smart}
Failed service alerts /etc/systemd/system/service.d/10-sema-onfailure.conf
ZFS alerts appended to /etc/zfs/zed.d/zed.rc
Drive alerts and self-tests DEVICESCAN line in /etc/smartd.conf
SMART metrics /var/lib/node_exporter/textfile/smart.prom
SSH bans nftables table inet sema_guard, state in /var/lib/sema/guard

Configuration

Everything lives in /etc/sema/config, edit it with sudoedit.
After changing MODULES, run sudo sh install.sh again, removed modules are cleanly turned off.

Setting Default What
ROOM Room ID (!xxxx) or alias (#alerts:server)
HOMESERVER http://127.0.0.1:8008 Matrix homeserver
MENTION @room Who urgent alerts ping: @room, a user ID, or ""
MODULES zed smartd onfailure smart guard Active modules
GUARD_TIMEOUT 90 Seconds to answer an SSH login
GUARD_TRUST_HOURS 12 Hours an approved user and IP skip approval, -1 forever
GUARD_BAN_HOURS -1 Hours a denied IP stays banned, -1 until lifted

@room needs the bot to have the power level for room pings, which is 50 (Moderator) by default.

Modules

Module What Pings
zed ZFS: disk faulted, pool degraded, data errors, scrub results Unless it's a clean scrub
smartd A drive reports it's failing, failed self-tests, scheduled self-tests Always
onfailure Any system service fails No
smart Drive health numbers for Prometheus (sema-smart) Sends nothing itself
guard SSH login approval and IP bans (sema-guard) Always

Slow problems like disks filling up are handled by Prometheus and Alertmanager in a separate Monitor stack, which reuse sema-matrix through matrix-receiver.

Usage

Every tool works both ways, sema matrix is the same as sema-matrix.
Run sema to list the tools.

  • Send a message
sema matrix -s "Title" "message"
  • Send from stdin
some-command | sema matrix -s "Title"
  • Send and ping MENTION
sema matrix -m -s "Title" "message"
  • Show SSH bans and trusted logins
sudo sema guard list
  • Lift a ban
sudo sema guard unban IP

guard

Every SSH login, password or key, is held before a shell starts until someone answers in Matrix.
The bot offers ✅ and ❌, just tap one.
✅ lets it in and trusts that user and IP for 12h, ❌ or no answer within 90s bans the IP.
Bans last until lifted, tap ✅ on the ban message to lift one.
Both durations are configurable, -1 meaning forever.
If Matrix is down, logins are allowed and you're told afterwards, so it can never lock you out.
Console logins never go through it.

  • Enable it, keeping a root shell open while testing
sudoedit /etc/pam.d/sshd
  • Add this right after account include system-remote-login
account   required  pam_exec.so stdout quiet /usr/local/bin/sema-guard pam
  • Disable it by removing that line, and drop guard from MODULES to uninstall it.
    The installer refuses to uninstall it while the PAM line is still there, since that would block every SSH login.

☦

   Ὤ
 Ὁ   Ν
Ι̅Ϲ̅ │ Χ̅Ϲ̅
───┼───
ΝΙ │ ΚΑ
   ☦

Εἰς δόξαν τοῦ Θεοῦ
To the glory of God

Τῇ Ὑπεραγίᾳ Θεοτόκῳ δόξα
Glory to the Most Holy Theotokos

Δόξα τῷ Θεῷ πάντων ἕνεκεν
Glory to God for all things

ΑΜΗΝ

☦