Your Name
414a990801
The single-timer threshold monitor generalizes into a scheduler: each job is a
chmod-600 file in schedule.d/<name>.env (INTERVAL 5m..59m/1h..23h/hourly/daily/
weekly/OnCalendar=..., NOTIFY policy, optional MSG, RULE for threshold,
COMMAND = literal rest of line) with its own systemd user timer pair
(pos-schedule-<name>.timer + oneshot .service, Persistent, reconciled on
enable/disable — orphan units + the legacy pos-event-trigger timer
auto-removed). Policies: always (full output every run), onchange (diff vs
last run, first run sends), onerror (non-zero exit or empty output),
threshold (old event-trigger behavior: first numeric vs RULE, alert on
false→true + recovery, per-job firing state), never (silent side-effect jobs).
run [name|all], list, config (interactive add/edit/remove/enable/disable with
validation), enable/disable [name|all], status, migrate (converts legacy
event.env rules → rule-N.env threshold jobs, verbatim LHS as COMMAND, adopts
the legacy timer's OnCalendar or 5m, removes the old timer). Per-run logs +
state in ~/.local/share/linux_post_install/schedule/{logs,state}/.
config/event.env + event-rules.template → config/schedule.d/ starter jobs
(nvme-health, cpu-temp, disk-root, silent log-cleanup); postinstall installs
them no-clobber into an empty schedule.d/ (legacy event.env users get a
migrate hint instead). bin/pos EXAMPLES + INTERACTIVE_CMDS
(system-schedule config) updated; install.sh ships the renamed tool+lib.
4.9 KiB
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, aria2 download daemon | 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 schedule |
Scheduled jobs: run a command on a timer, notify on threshold/change/error or silently | schedule |
pos ssh |
Load keys into the agent | ssh |
pos share |
Share USB devices & filesystems over the network (USB, NFS, SMB) | share |
pos communication |
Send Telegram/Matrix messages & alerts, /command listeners | 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 |
matrix.env |
pos communication matrix sender / listener |
MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, MATRIX_ROOM_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 |
schedule.d/ |
pos system schedule |
one <name>.env per job: INTERVAL, NOTIFY, MSG, RULE, COMMAND |
pos config telegram # set TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID
pos config matrix # set MATRIX_HOMESERVER / MATRIX_ROOM_ID, then:
pos communication matrix sender login --user @you:example.org # fetch an access token
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
Ship with telegram and matrix — add both to NOTIFY_PLATFORM to fan out
alerts (Matrix needs pos config matrix + a login-fetched token first).
Adding another platform = 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 --sendat 08:00) —systemd/pos-health.{service,timer}, enabled by postinstall oncetelegram.envexists. See system. - Entertainment auto-triggers — per-plugin
pos entertainment enable <plugin> <interval>, uses systemd user timers (or cron fallback). See entertainment. pos system schedulejobs — run any command on a per-job timer and notify on threshold/change/error/always or silently. See schedule.
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.