From 47399d894a63143e8892cafdc5736d5cb1d101ae Mon Sep 17 00:00:00 2001
From: steffen <steffen@skui.io>
Date: Mon, 15 Jun 2026 21:15:40 +0200
Subject: [PATCH] Add platform-specific notes: ZFS memory, user systemd, group
 name quoting

---
 SETUP.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/SETUP.md b/SETUP.md
index a85e3bf..c2fab2d 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -183,6 +183,88 @@ systemctl daemon-reload
 
 ---
 
+## Platform-specific notes
+
+### ZFS servers (high memory usage)
+
+ZFS uses all available RAM as disk cache (ARC) by design. This causes `/proc/meminfo`'s
+`MemAvailable` to appear very low even when the system is healthy, triggering false
+`degraded` or `offline` memory alerts.
+
+**Fix:** raise the memory thresholds in `ethica-agent.yml` on ZFS hosts:
+
+```yaml
+- type: system_memory
+  name: Memory
+  degrade_threshold: 97   # ZFS ARC fills all free RAM — not a real shortage
+  offline_threshold: 99
+```
+
+**Monitor ZFS pool health instead** using `custom_cmd` (see `widgets/custom-cmd.yml`):
+
+```yaml
+- type: custom_cmd
+  name: rpool
+  kind: system
+  cmd: H=$(zpool list -H -o health rpool 2>/dev/null); C=$(zpool list -H -o cap rpool 2>/dev/null | tr -d %); [ "$H" = "ONLINE" ] || exit 2; [ "$C" -ge 90 ] && exit 2; [ "$C" -ge 75 ] && exit 1; exit 0
+
+- type: custom_cmd
+  name: storage pool
+  kind: system
+  cmd: H=$(zpool list -H -o health data 2>/dev/null); C=$(zpool list -H -o cap data 2>/dev/null | tr -d %); [ "$H" = "ONLINE" ] || exit 2; [ "$C" -ge 90 ] && exit 2; [ "$C" -ge 75 ] && exit 1; exit 0
+```
+
+Replace `rpool` / `data` with your actual pool names (`zpool list` to check).
+
+---
+
+### Servers without sudo (user systemd service)
+
+If the SSH user does not have sudo, use a user-level systemd service instead:
+
+```bash
+mkdir -p ~/.config/systemd/user/
+cat > ~/.config/systemd/user/ethica-agent.service << 'EOF'
+[Unit]
+Description=Ethica Agent
+After=network-online.target
+
+[Service]
+WorkingDirectory=/opt/ethica-agent
+EnvironmentFile=/opt/ethica-agent/.env
+ExecStart=/usr/bin/python3 /opt/ethica-agent/ethica-agent.py --config /opt/ethica-agent/ethica-agent.yml
+Restart=always
+RestartSec=15
+
+[Install]
+WantedBy=default.target
+EOF
+
+systemctl --user daemon-reload
+systemctl --user enable --now ethica-agent
+systemctl --user status ethica-agent
+```
+
+**Auto-start on boot** (requires root once):
+```bash
+sudo loginctl enable-linger $USER
+```
+
+Without `enable-linger`, the user service stops when the SSH session closes.
+
+---
+
+### Server groups with spaces in the name
+
+When `ETHICA_GROUP` contains spaces, quote it in `.env`:
+
+```bash
+ETHICA_GROUP="Mail Server"   # correct
+ETHICA_GROUP=Mail Server     # wrong — bash splits on space
+```
+
+---
+
 ## Docker alternative
 
 ```bash