docs: add pos HOW-TO guide set (index + 8 category guides)

2026-08-06 02:54:36 -04:00
parent 025971ca1e
commit 8bef0f8c6d
13 changed files with 844 additions and 0 deletions
@@ -0,0 +1,148 @@
+# How-To: `pos system`
+
+Host care: encrypted backups, firewall, and the health dashboard. Tools:
+`backup`, `firewall`, `health`.
+
+| Tool | What it does |
+|------|--------------|
+| `pos system health` | Host health dashboard (disk, RAM, services, backup age, fail2ban, docker) |
+| `pos system backup` | gpg-encrypted (AES-256) folder snapshots |
+| `pos system firewall` | Interactive UFW ("UFW POWER") management |
+
+---
+
+## `pos system health` — host health dashboard
+
+```bash
+pos system health                 # console report; exits 1 if any check FAILs
+pos system health --send          # also send the summary via notify platforms
+pos system health --markdown      # same, markdown parse mode (implies --send)
+```
+
+Checks: disk per mount (>90% = FAIL), RAM/swap, failed systemd units, backup
+age, fail2ban, docker containers. Header shows hostname, uptime, load, public IP.
+
+`--help` prints the **effective** config values (env > `system.env` > default),
+e.g.:
+
+```
+Environment (effective values):
+  NOTIFY_PLATFORM             telegram
+  HEALTH_BACKUP_MAX_AGE_DAYS  2
+  BACKUP_SERVICE_ROOTS        /srv /home/you/srv
+```
+
+### Configuration
+
+```bash
+# ~/.config/linux_post_install/system.env
+BACKUP_SERVICE_ROOTS=/srv /home/you/srv     # where backup-age is checked
+HEALTH_BACKUP_MAX_AGE_DAYS=3                # WARN if newest backup older
+# ~/.config/linux_post_install/notify.env
+NOTIFY_PLATFORM=telegram
+```
+
+### Daily digest (automated)
+
+`systemd/pos-health.{service,timer}` run `pos system health --send --markdown`
+at 08:00 as the installing user. Enable it (re-run postinstall after Telegram
+is configured):
+
+```bash
+./postinstall.sh                      # enables timer once telegram.env exists
+systemctl list-timers | grep pos-health
+systemctl start pos-health.service    # run once now, check status
+```
+
+**Recipes:**
+- Watch the backup age without email: enable the digest; if the backup check
+  turns WARN you'll see it in the morning report.
+- Exit code in a cron/scheduled check:
+  `pos system health >/dev/null 2>&1 || notify_send "health FAIL"`.
+
+**Troubleshooting:**
+- `[WARN] fail2ban installed but not running` → expected unless you have it
+  active; start it (`sudo systemctl enable --now fail2ban`) or ignore.
+- `[FAIL] services: nbd-server.service …` → a failed unit; inspect with
+  `systemctl status <unit>`.
+- `--send` prints a warn and exits 0 when no platform is configured — by design
+  (see [communication](communication.md)).
+
+---
+
+## `pos system backup` — encrypted folder snapshots
+
+```bash
+pos system backup <folder-path>       # encrypt to ./<name>_<date>.tar.gz.gpg
+pos system backup --service           # pick a folder from /srv + ~/srv
+```
+
+Uses `sudo tar` + gpg AES-256. The password is prompted **twice and never
+stored**; the artifact is `chmod 600`. On success (and on failure, via ERR
+trap) a `notify_send` alert is sent.
+
+`--service` lists folders under the roots in `BACKUP_SERVICE_ROOTS`
+(default `/srv $HOME/srv`; override via `system.env` or env) and lets you pick.
+
+### Recipes
+
+- **Nightly service backup + health check:**
+  ```bash
+  cd ~/backups && pos system backup --service
+  pos system health          # "backup: 0d old" turns OK
+  ```
+- **Cron it and get alerted:**
+  ```bash
+  30 3 * * * cd ~/backups && pos system backup --service >> ~/backups/backup.log 2>&1
+  ```
+  Success/failure are sent to Telegram automatically.
+
+**Troubleshooting:**
+- "Root not found: …" → the default roots don't exist; set `BACKUP_SERVICE_ROOTS`
+  in `system.env`.
+- Forgot the password → backups are unrecoverable; keep the passphrase in a
+  password manager. Nothing is stored anywhere else.
+- `sudo tar` prompt: ensure the user has sudo rights for the source dir.
+
+---
+
+## `pos system firewall` — interactive UFW ("UFW POWER")
+
+**Must run as root:**
+
+```bash
+sudo pos system firewall
+```
+
+Interactive menu: add rule (port/service/IP/directional), delete by number or
+text, status (simple/verbose/numbered), enable/disable/reset, default policies,
+and an executed-command history. Supports `--dry-run`:
+
+```bash
+sudo pos system firewall --dry-run
+```
+
+Every command is **previewed and confirmed** before execution. Executed
+mutating changes are announced via `notify_send` (read-only `ufw status` is
+not).
+
+### Recipes
+- Open SSH + a service:
+  `add rule → port/service → 22/tcp`, then `8080/tcp`; finish with `enable`.
+- See current rules for deletion: menu `3) Show status → numbered`.
+- `--dry-run` to rehearse a rule batch safely.
+
+**Troubleshooting:**
+- "Please run as root" → you need `sudo pos system firewall` (the notify config
+  still uses your user's `$HOME`, so alerts keep working).
+- Accidentally locked yourself out of SSH → console into the host,
+  `sudo ufw allow 22/tcp`, then `sudo ufw reload`.
+- `ufw reset` requires typing `RESET` — deliberate.
+
+---
+
+## Related
+
+- Reference: [DOC/POS.md → system](../POS.md)
+- Notify platform config: [communication.md](communication.md)
+- Backup roots shared with health: `system.env` ([DOC/POS.md](../POS.md))