Files

T

Your Name 030ec0b456 feat: pos system event-trigger — state-based threshold monitors (eventer)

Each line of event.env is an independent rule: ["msg" if ] <check> <op> <thr>.
Check runs on every pass; first numeric output compared float-safe; op is the
rightmost 'op threshold' pair so checks with their own >/< parse fine. Alerts
once on false->true + one recovery message on true->false (no repeats while
the condition holds); per-rule state keyed by rule-line hash in
~/.local/share/linux_post_install/eventer/state/.

Subcommands: run (timer entrypoint), config (interactive add/remove/edit with
check-validation), list (rules + live values), enable [interval] (systemd
user timer pos-event-trigger.timer; 5m..weekly or OnCalendar; graceful without
a user manager, loginctl enable-linger attempt), disable, status. --dry-run
honors the DEV.md convention. Alerts via lib/notify.sh (Telegram default).

New: bin/pos-system-event-trigger, lib/eventer-lib.sh, config/event.env
template (no-clobber via postinstall), install.sh lib install, INTERACTIVE_CMDS
entry. Docs: POS.md system row, HOWTO.md index, howto/event-trigger.md.
make gen && make check green; functional tests cover trigger/recovery/no-repeat,
float+unit parsing, editor add/remove/edit + validation + dry-run, timer
enable/disable/status, dispatcher routing.

2026-08-09 17:09:59 +00:00

4.1 KiB

Raw Blame History

`pos` HOW-TO Guides

Hands-on, copy-paste guides for every pos category. These are the tutorial layer: flags, examples, configuration, recipes, and troubleshooting. For the authoritative one-line reference (every command + flag), see DOC/POS.md.

Quick start — pick your category

Category	What you can do	Guide
`pos ai`	Chat with Google Gemini from CLI or Telegram	ai
`pos network`	IP info, hotspot, scan, port check	network
`pos docker`	Compose services, container dashboards, disposable VMs	docker
`pos media`	Download audio/video via yt-dlp	media
`pos system`	Backups, firewall, health dashboard	system
`pos system event-trigger`	Threshold-rule monitors that alert on crossing	event-trigger
`pos ssh`	Load keys into the agent	ssh
`pos usb`	Share USB devices over the network	usb
`pos communication`	Send Telegram messages/files/alerts	communication
`pos entertainment`	Scheduled auto-messages from public APIs	entertainment

Every tool is bin/pos-<category>-<command>; run pos <category> --help to list a category, and any tool's --help/--help-style usage for full flags.

Cross-cutting concepts (read once)

These apply to several categories at once.

Config files — `~/.config/linux_post_install/`

Runtime tool config lives here as <tool>.env files (chmod 600). Precedence is always flags > environment > config file. postinstall.sh installs the templates (without overwriting an existing file):

File	Used by	Keys
`telegram.env`	`pos communication telegram sender` / `listener`, everything that alerts	`TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`
`notify.env`	`lib/notify.sh` (all alerting)	`NOTIFY_PLATFORM` (e.g. `telegram,matrix`)
`system.env`	`pos system health`, `pos system backup`	`BACKUP_SERVICE_ROOTS`, `HEALTH_BACKUP_MAX_AGE_DAYS`
`compose.env`	`pos docker compose`	`TS_AUTHKEY`, `TZ`, `DNS_SERVER`, `SERVICES_BASE`
`entertainment.env`	`pos entertainment *`	plugin keys (`WEATHER_LAT`…), `ENABLED`
`ai.env`	`pos ai gemini`	`AI_GEMINI_API_KEY`, `AI_GEMINI_MODEL`

pos config telegram                     # set TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID
pos entertainment config set WEATHER_LAT=36.51 WEATHER_LON=40.75

The notify system — `lib/notify.sh`

Any tool that "announces" something calls notify_send, which delivers to every platform in NOTIFY_PLATFORM (default telegram). It is silent-fail: if no platform is configured it warns and never breaks the calling tool.

# ~/.config/linux_post_install/notify.env
NOTIFY_PLATFORM=telegram        # comma-separated to send to all

Adding a platform later (e.g. Matrix/Synapse) = create bin/pos-communication-<p> implementing send <value> [--markdown] and list it. See DOC/DEV.md → Alerting for the contract.

Scheduling

Daily health digest (pos system health --send at 08:00) — systemd/pos-health.{service,timer}, enabled by postinstall once telegram.env exists. See system.
Entertainment auto-triggers — per-plugin pos entertainment enable <plugin> <interval>, uses systemd user timers (or cron fallback). See entertainment.

Gotcha: run from anywhere

install.sh copies bin/pos* + lib/* to /usr/local/bin, so pos works after the repo is deleted. After pulling new changes, re-run ./install.sh (or just copy the changed bin//lib/ files) to refresh the installed copies.

How the guides relate to `DOC/POS.md`

DOC/POS.md = reference. One table row per command, full flag lists, compose/ScaleTail config strategy. Use it when you need the exact flag.
This guide set = how-to. Examples, recipes, config walk-throughs, and troubleshooting, linking back to POS.md rather than duplicating it.

4.1 KiB Raw Blame History

pos HOW-TO Guides