version 5.1.12

- fix: matrix/sms_voipms notifications blocked the event loop on timeout;
  make send_notification async, dispatch all channel drivers as non-blocking
  tasks (asyncio.to_thread for sync drivers, asyncio.wait_for for async);
  update all call sites to fire-and-forget via create_task
- feat: add /about page with version, runtime, uptime counter, and repo link
- fix: hbc_mini plugin data format now matches full hbc client so Host
  Overview displays memory, disk, and network metrics correctly

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

.gitea/workflows/release.yml

@@ -6,28 +6,41 @@ on:
 
 jobs:
   release:
-    runs-on: ubuntu-latest
+    runs-on: FreeBSD
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
         
+#      - name: Set up Python
+#        uses: actions/setup-python@v5
+#        with:
+#          python-version: '3.11'
       - name: Set up Python
-        uses: actions/setup-python@v5
+        # Use a generic run step for FreeBSD if actions/setup-python
-        with:
+        # fails in restricted environments.
-          python-version: '3.11'
+        run: |
+          python3 --version
+          python3 -m ensurepip --upgrade
           
       - name: Install build tools
         run: |
-          python -m pip install --upgrade pip
+          python3 -m pip install --upgrade pip
-          pip install build twine
+          python3 -m pip install build twine
           
       - name: Build package
-        run: python -m build
+        run: python3 -m build
         
       - name: Extract version from tag
         id: get_version
         run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
         
+      - name: Upload to Gitea PyPI registry
+        env:
+          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          python3 -m twine upload --repository-url https://git.wrede.ca/api/packages/andreas/pypi dist/*
+
       - name: Create release
         uses: actions/gitea-release-action@v1
         with:

.gitignore

@@ -11,3 +11,4 @@ dist/
 *.egg-info/
 ssl/
 uv.lock
+.hb.yaml

.hb.yaml

@@ -1,254 +0,0 @@
-#name: "w02"
-hb_port: 50003   
-hbd_host: ''
-#logfile: "/home/andreas/public_html/messages/andreas"
-logfile: "/home/andreas/logs/heartbeat/heartbeat.log"
-#logfile: "/Users/andreas/public_html/messages/andreas"
-logfmt: "msg"
-grace: 40
-interval: 10
-
-# Notification Channels - Define notification providers centrally
-# Each channel has a type (pushover, email, signal, mattermost) and type-specific configuration
-notification_channels:
-
-  pushover_standard:
-    type: pushover
-    token: ac7NLX2rPjXFareeDgLpXNoDf4iFmf
-    user: uDhH33UjQQDYtNzJb1ThRiWb9ingGK
-
-  signal_andreas:
-    type: signal
-    cli_path: /usr/local/bin/signal-cli
-    user: +14168226179
-    recipient: +14168226179
-  
-  email_andreas:
-    type: email
-    recipients: [aew.hbd.notify@wrede.ca]
-    sender: aew.hbd@wrede.ca
-    smtp_server: smtp.fastmail.com
-    smtp_port: 587
-    smtp_user: andreas@wrede.ca
-    smtp_password: pvtvefyp5gbhnch2
-  
-  # Example additional channels (commented out)
-  # pushover_urgent:
-  #   type: pushover
-  #   token: your-app-token
-  #   user: your-user-key
-  #
-  mattermost_devops:
-    type: mattermost
-    host: mattermost.example.com
-    token: webhook-token
-    channel: devops-alerts
-    username: heartbeat-bot
-    icon: https://example.com/heartbeat-icon.png
-
-# Default notification channels (used if host doesn't specify channels)
-default_notification_channels: [pushover_standard]
-
-# Host definitions - combines threshold mapping, watch status, DNS updates, and notifications
-hosts:
-  wentworth:
-    threshold_config: default
-    watch: true
-    notification_channels: [pushover_standard]
-    dyndns: false
-  
-  y:
-    threshold_config: default
-    watch: true
-    notification_channels: [pushover_standard]
-    dyndns: false
-  
-  winter:
-    threshold_config: default
-    watch: true
-    notification_channels: [pushover_standard]
-    dyndns: false
-  
-  wally:
-    threshold_config: freebsd_server
-    watch: false
-    notification_channels: [pushover_standard]
-    dyndns: false
-  
-  eris:
-    threshold_config: truenas_server
-    watch: false
-    notification_channels: [pushover_standard]
-    dyndns: false
-  
-  haschloss:
-    threshold_config: default
-    watch: false
-    dyndns: true
-  
-  wayback:
-    threshold_config: default
-    watch: false
-    notification_channels: [pushover_standard]
-    dyndns: true
-  
-  wertvoll:
-    threshold_config: default
-    watch: false
-    notification_channels: [pushover_standard]
-    dyndns: true
-  
-  weekend:
-    threshold_config: freebsd_server
-    watch: false
-    notification_channels: [pushover_standard]
-    dyndns: true
-  
-  cotgate:
-    threshold_config: default
-    watch: false
-    dyndns: true
-  
-  rvgate:
-    threshold_config: default
-    watch: false
-    dyndns: true
-  
-  draper:
-    threshold_config: default
-    watch: false
-    notification_channels: [pushover_standard]
-    dyndns: true
-
-# Hosts to drop/ignore
-drophosts: {"unknown", "wookie15", "wort"}
-
-nsupdate_bin: "/usr/local/bin/nsupdate"
-
-dyndomains: {"wrede.org"}
-
-ws_port: 50005
-# wss_port: 50006  # Commented out - use plain WebSocket instead of secure WSS
-# cert_path: "/usr/local/etc/letsencrypt/live/hbd.wrede.ca/"
-# cert_path: "test/"
-# CERT_PATH = "./test/"
-# wss_pem: "fullchain.pem"
-# wss_key: "privkey.pem"
-
-journal_enabled: true                    # Enable/disable journaling
-journal_dir: /home/andreas/logs/heartbeat         # Journal directory
-journal_file: messages.journal           # Base filename
-journal_max_size: 104857600             # Max size (100MB default)
-journal_max_backups: 10                 # Number of backups to keep
-
-threshold_configs:
-  default:
-    thresholds:
-      cpu_monitor:
-        cpu_percent:
-          warning: 80.0
-          critical: 90.0
-      memory_monitor:
-        percent:
-          warning: 85.0
-          critical: 95.0
-      disk_monitor:
-        partitions:
-          /:
-            percent:
-              warning: 85.0
-              critical: 90.0
-      rtt:
-        warning: 50
-        critical: 250.0
-
-
-  freebsd_server:
-    thresholds:
-      cpu_monitor:
-        cpu_percent:
-          warning: 80.0
-          critical: 90.0
-      memory_monitor:
-        memory_percent:
-          warning: 97.0
-          critical: 100.0
-      disk_monitor:
-        partitions:
-          /:
-            percent:
-              warning: 85.0
-              critical: 90.0
-      nagios_runner:
-   #     overall_status_code:
-   #       warning: 1
-   #       critical: 2
-   #       operator: ">="
-        load_status:
-          warning: WARNING
-          critical: CRITICAL
-          operator: "=="
-        ups_load:
-          display: "load to high: {ups_output}"
-          warning: 70
-          critical: 80
-          operator: ">="
-        ups_status_code:
-          display: "{ups_output}"
-          warning: 1
-          critical: 2
-          operator: ">="
-        nextcloud_apps_status_code:
-          display: "{nextcloud_apps_output}"
-          warning: 1
-          critical: 2
-          operator: ">="
-      rtt:
-        warning: 50
-        critical: 250.0
-
-  truenas_server:
-    thresholds:
-      cpu_monitor:
-        cpu_percent:
-          warning: 80.0
-          critical: 90.0
-      memory_monitor:
-        percent:
-          warning: 3.0
-          critical: 95.0
-      disk_monitor:
-        partitions:
-          /:
-            percent:
-              warning: 85.0
-              critical: 90.0
-      nagios_runner:
-   #     overall_status_code:
-   #       warning: 1
-   #       critical: 2
-   #       operator: ">="
-        load_status:
-          warning: WARNING
-          critical: CRITICAL
-          operator: "=="
-        ups_load:
-          display: "load to high: {ups_output}"
-          WARNING: 70
-          CRITICAL: 80
-          OPERATOR: ">="
-        ups_status_code:
-          DISPLAY: "{ups_output}"
-          warning: 1
-          critical: 2
-          operator: ">="
-        nextcloud_apps_status_code:
-          display: "{nextcloud_apps_output}"
-          warning: 1
-          critical: 2
-          operator: ">="
-      rtt:
-        warning: 120
-        critical: 250.0
-
-

.vscode/launch.json

@@ -4,12 +4,13 @@
   // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
+
     {
       "name": "Python: Run hbd (module)",
       "type": "debugpy",
       "request": "launch",
       "module": "hbd.server.cli",
-      "args": ["-c", "/home/andreas/git/heartbeat/.hb.yaml", "-f", "-v", "-x", "-x", "-x", "-x"],
+      "args": ["-c", "~/.hb.yaml", "-f", "-v"],
       "cwd": "${workspaceFolder}",
       "env": {
         "PYTHONPATH": "${workspaceFolder}"
@@ -28,14 +29,14 @@
       ]
     },
     {
-      "name": "Python: Run hbd with debugpy (listen)",
+      "name": "Python: Run hbc (module)",
       "type": "debugpy",
       "request": "launch",
-      "module": "debugpy",
+      "module": "hbd.client.main",
-      "args": ["--listen", "5678", "--wait-for-client", "-m", "hbd.server.cli", "-c", ".hb.yaml", "-f", "-v"],
+      "args": ["-c", "~/.hbc.yaml",  "-v", "winter"],
+      "cwd": "${workspaceFolder}",
       "env": { "PYTHONPATH": "${workspaceFolder}" },
       "console": "integratedTerminal",
-      "justMyCode": false
     }
   ]
 }

CLAUDE. md

@@ -0,0 +1,4 @@
+1. Don't assume. Don't hide confusion. Surface tradeoffs.
+2. Minimum code that solves the problem. Nothing speculative.
+3. Touch only what you must. Clean up only your own mess.
+4. Define success criteria. Loop until verified.

README.md

@@ -11,8 +11,13 @@ A lightweight daemon that listens for UDP heartbeat messages and acts on them: k
 - Queue DNS updates via `nsupdate` and run them in a background thread ✅
 - WebSocket API for live updates (hosts & messages) ✅
 - Notification pipeline (email, Pushover, Mattermost, Signal) ✅
+- **User management & access control** ✅
+  - Optional user accounts with bcrypt-style password hashing (stdlib only)
+  - Per-host roles: owner, manager, monitor
+  - Session-based auth with cookie support (browser login page included)
+  - Backwards compatible: no auth required when no users are configured
 - **HTTP API & Web UI** ✅
-  - REST API for plugin data, alerts, and host information
+  - REST API for plugin data, alerts, host information, and user management
   - Live dashboard with WebSocket updates
   - Interactive plugin metrics visualization
   - Alerts dashboard with filtering and summaries
@@ -71,7 +76,7 @@ See [docs/NAGIOS_INTEGRATION.md](docs/NAGIOS_INTEGRATION.md) for complete integr
 ### Creating Custom Plugins
 
 ```python
-from hbd.plugin import MonitorPlugin
+from hbd.client.plugin import MonitorPlugin
 
 class DiskMonitorPlugin(MonitorPlugin):
     name = "disk_monitor"
@@ -84,7 +89,7 @@ class DiskMonitorPlugin(MonitorPlugin):
         }
 ```
 
-Place plugins in `hbd/plugins/` and they'll be automatically discovered and loaded by the client.
+Place plugins in `hbd/client/plugins/` and they'll be automatically discovered and loaded by the client.
 
 ---
 
@@ -266,20 +271,63 @@ See [docs/THRESHOLD_ALERTING.md](docs/THRESHOLD_ALERTING.md) for comprehensive d
 
 ---
 
+## 👥 User Management
+
+Heartbeat supports optional user accounts with role-based access control per host.
+
+### Roles
+
+- **monitor** — view status, plugin data, alerts
+- **manager** — monitor + queue commands, trigger DNS, queue upgrades
+- **owner** — manager + drop host, transfer ownership, update access
+- **admin** (user flag) — owner-level access on every host
+
+When no users are configured the server runs in **unauthenticated mode** — all existing behaviour is unchanged.
+
+### Quick setup
+
+```yaml
+users:
+  alice:
+    full_name: Alice Smith
+    password: pbkdf2:sha256:...    # hbd passwd alice
+    admin: true
+
+default_owner: alice
+
+hosts:
+  webserver01:
+    owner: alice
+    managers: [bob]
+    monitors: [carol]
+```
+
+```bash
+# Generate a password hash
+hbd passwd alice
+```
+
+Browser users are redirected to `/login` automatically. The session cookie is set on login, so `fetch()` calls from dashboards work without any JavaScript changes.
+
+See [docs/USERS.md](docs/USERS.md) for complete user management documentation.
+
+---
+
 ## 🌐 HTTP API & Web UI
 
 Heartbeat includes a built-in HTTP/WebSocket server that provides both a REST API and web-based dashboards for monitoring and visualization.
 
 ### Features
 
-- **REST API**: JSON endpoints for accessing plugin data, alerts, and host information
+- **User auth**: Optional session-based authentication with per-host role enforcement
+- **REST API**: JSON endpoints for accessing plugin data, alerts, host information, and user management
 - **Live Dashboard**: Real-time WebSocket-powered host status view
 - **Plugin Metrics**: Interactive visualization of all plugin data with auto-refresh
 - **Alerts Dashboard**: Comprehensive alert monitoring with filtering and summaries
-- **CORS Support**: Configurable for integration with external applications
 
 ### Web Dashboards
 
+- **Login** (`/login`): Browser login form (shown automatically when auth is configured)
 - **Live View** (`/live`): Real-time host connectivity, latency, and messages
 - **Plugin Metrics** (`/plugins`): Browse and visualize metrics from all plugins
 - **Alerts Dashboard** (`/alerts`): Monitor active alerts with severity filtering
@@ -287,56 +335,29 @@ Heartbeat includes a built-in HTTP/WebSocket server that provides both a REST AP
 ### API Endpoints
 
 ```bash
+# Log in (when auth is configured)
+TOKEN=$(curl -s -X POST http://localhost:50004/api/0/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"alice","password":"secret"}' | jq -r .token)
+AUTH="-H \"Authorization: Bearer $TOKEN\""
+
 # List all monitored hosts
-curl http://localhost:50004/api/0/hosts
+curl $AUTH http://localhost:50004/api/0/hosts
 
 # Get all plugin data for a host
-curl http://localhost:50004/api/0/hosts/webserver01/plugins
+curl $AUTH http://localhost:50004/api/0/hosts/webserver01/plugins
 
 # Get detailed plugin history (last 50 samples)
-curl http://localhost:50004/api/0/hosts/webserver01/plugins/cpu_monitor?limit=50
+curl $AUTH "http://localhost:50004/api/0/hosts/webserver01/plugins/cpu_monitor?limit=50"
 
 # Get alert states for a specific host
-curl http://localhost:50004/api/0/hosts/webserver01/alerts
+curl $AUTH http://localhost:50004/api/0/hosts/webserver01/alerts
 
 # Get all active alerts across all hosts
-curl http://localhost:50004/api/0/alerts
+curl $AUTH http://localhost:50004/api/0/alerts
-```
 
-### Integration Examples
+# View/update host access roles
-
+curl $AUTH http://localhost:50004/api/0/hosts/webserver01/access
-**Python Client:**
-```python
-import requests
-
-# Monitor for critical alerts
-response = requests.get('http://localhost:50004/api/0/alerts')
-alerts = response.json()
-
-if alerts['summary']['critical'] > 0:
-    print(f"⚠️ {alerts['summary']['critical']} CRITICAL alerts!")
-    for alert in alerts['alerts']:
-        if alert['level'] == 'CRITICAL':
-            print(f"  {alert['hostname']}: {alert['metric_path']} = {alert['last_value']}")
-```
-
-**Bash Monitoring Script:**
-```bash
-#!/bin/bash
-# Check for critical alerts
-CRITICAL=$(curl -s http://localhost:50004/api/0/alerts | jq '.summary.critical')
-if [ "$CRITICAL" -gt 0 ]; then
-    echo "CRITICAL: $CRITICAL critical alerts detected!"
-    # Send notification
-fi
-```
-
-### Demo & Testing
-
-Run the API demo script to test all endpoints:
-
-```bash
-python3 scripts/demo_http_api.py
 ```
 
 See [docs/HTTP_API.md](docs/HTTP_API.md) for complete API documentation including response formats, error handling, and integration examples.
@@ -347,7 +368,7 @@ See [docs/HTTP_API.md](docs/HTTP_API.md) for complete API documentation includin
 
 Prerequisites:
 
-- Python 3.10+ (project uses language features from recent Python)
+- Python 3.11+ (project uses language features from recent Python)
 - `nsupdate` (for DNS updates) if using dynamic DNS
 
 Install dependencies (recommended into a venv):
@@ -356,7 +377,7 @@ This project now declares its dependencies in `pyproject.toml`. Instead
 of the old `requirements.txt` flow, install the package into a virtualenv
 using `pip`:
 
-See `scripts/install.sh` for a way to install.
+See `scripts/hb_install.sh` for a way to install.
 
 Run the daemon (example):
 
@@ -368,7 +389,7 @@ hbd -c .hb.yaml -f -v
 You can also run it directly via the package entrypoint after installation:
 
 ```bash
-python -m hbd.cli -c /path/to/config.yaml
+python -m hbd.server.cli -c /path/to/config.yaml
 ```
 
 ### Running the Client
@@ -376,14 +397,23 @@ python -m hbd.cli -c /path/to/config.yaml
 The heartbeat client (`hbc`) sends periodic heartbeats and plugin data to the server:
 
 ```bash
-# Basic usage pointing to server
+# Basic usage pointing to server (host is a positional argument)
-python -m hbd.hbc --server your-server.example.com
+hbc your-server.example.com
 
-# With custom configuration
+# Run as daemon with a config file
-python -m hbd.hbc --server 192.168.1.100 --port 50003 --interval 30
+hbc -d -c /etc/hbc.yaml your-server.example.com
 
-# Run with specific plugins enabled/disabled
+# Send a one-off boot message
-python -m hbd.hbc --server hbd.local --disable-plugin os_info
+hbc --boot your-server.example.com
+
+# Verbose output
+hbc -v your-server.example.com
+```
+
+You can also run it via the module entrypoint:
+
+```bash
+python -m hbd.client.main your-server.example.com
 ```
 
 Client configuration can also be specified in YAML:
@@ -411,36 +441,97 @@ plugins:
 
 All monitoring plugins default to 5-minute (300 second) intervals, but can be customized as needed.
 
+### hbc_mini — single-file client (no external dependencies)
+
+`scripts/hbc_mini.py` is a self-contained version of the heartbeat client that requires only Python 3.8+ and no external packages. Copy it to any host and run it directly — no virtualenv, no `pip install`.
+
+```bash
+# Basic usage
+python3 hbc_mini.py your-server.example.com
+
+# Run as daemon
+python3 hbc_mini.py -d your-server.example.com
+
+# Send a boot message
+python3 hbc_mini.py -b your-server.example.com
+
+# Send a one-off message
+python3 hbc_mini.py -m "maintenance starting" your-server.example.com
+```
+
+**Config:** `~/.hbc.json` (same keys as `~/.hbc.yaml`, JSON format). Example:
+
+```json
+{
+  "hb_port": 50003,
+  "interval": 30,
+  "plugins": {
+    "ping_monitor": {
+      "interval": 60,
+      "hosts": ["8.8.8.8", "192.168.1.1"]
+    },
+    "nagios_runner": {
+      "interval": 300,
+      "commands": [
+        {"name": "check_load", "command": "/usr/lib/nagios/plugins/check_load -w 5,4,3 -c 10,8,6"}
+      ]
+    }
+  }
+}
+```
+
+**Plugin availability:**
+
+| Plugin | Platform | Data source |
+|---|---|---|
+| `os_info` | all | `platform` stdlib |
+| `ping_monitor` | all | `ping` subprocess |
+| `nagios_runner` | all (not Windows) | subprocess |
+| `cpu_monitor` | Linux | `/proc/stat` |
+| `memory_monitor` | Linux | `/proc/meminfo` |
+| `disk_monitor` | Linux, macOS, BSD | `df -P` subprocess |
+| `network_monitor` | Linux | `/proc/net/dev` |
+
+**What is not available compared to the full `hbc`:**
+
+- No YAML config (use JSON instead)
+- No `filesystem_info` plugin
+- `cpu_monitor` does not report per-core usage or CPU frequency (no psutil)
+- Plugins cannot be loaded from external `.py` files — all plugins are compiled in
+
+Everything else — heartbeat protocol, ACK/CMD/UPD handling, `hb_install.sh`-based self-update, daemonize, syslog — is identical to the full client.
+
+---
+
 ## 🐞 Debugging in VS Code
 
 This repository includes a ready-to-use `.vscode/launch.json` with configurations to run or attach the VS Code debugger to `hbd`.
 
 - Ensure the **Python** extension is installed and select the project `.venv` as the interpreter (bottom-left of VS Code).
 - Use **F5** and pick one of these configurations from the Run view:
-  - **Python: Run hbd (module)** — runs `hbd.cli` as a module and sets `PYTHONPATH` to the workspace root (recommended).
+  - **Python: Run hbd (module)** — runs `hbd.server.cli` as a module and sets `PYTHONPATH` to the workspace root (recommended).
   - **Python: Run hbd with debugpy (listen)** — launches `debugpy` and `hbd` together; useful when you want the process to listen for a debugger.
   - **Python: Attach (localhost:5678)** — attach the debugger to a running process started with `debugpy`.
 
 To start `hbd` manually and wait for the debugger to attach, run:
 
 ```bash
-PYTHONPATH=. python -m debugpy --listen 5678 --wait-for-client -m hbd.cli -c .hb.yaml -f -v
+PYTHONPATH=. python -m debugpy --listen 5678 --wait-for-client -m hbd.server.cli -c .hb.yaml -f -v
 ```
 
-Set breakpoints in modules such as `hbd/udp.py`, `hbd/dns.py`, or `hbd/server.py`, and use the **Attach** configuration to connect. Use `justMyCode: false` if you need to step into third-party code.
+Set breakpoints in modules such as `hbd/server/udp.py`, `hbd/server/dns.py`, or `hbd/server/main.py`, and use the **Attach** configuration to connect. Use `justMyCode: false` if you need to step into third-party code.
 
 ---
 
 ## 🛠 Configuration
 
-`hbd` reads YAML configuration (optional). If `PyYAML` is not installed, built-in defaults are used. Example configuration keys (see `hbd/config.py`):
+`hbd` reads YAML configuration (optional). If `PyYAML` is not installed, built-in defaults are used. Example configuration keys (see `hbd/server/config.py`):
 
 - `hb_port`: UDP port to listen for heartbeats (default: 50003)
 - `hbd_port`: internal control port (default: 50004)
 - `hbd_host`: bind address for HTTP/WSS
 - `pickfile`: path for persisted state
 - `logfile`: path to log file
-- `logfmt`: `text` or `msg`
 - `pushsrv`: push service (`pushover`|`mattermost`|`all`)
 - `interval` / `grace`: heartbeat timing configuration
 - `dyndomains`: list of dyndomains to update via `nsupdate`
@@ -452,6 +543,8 @@ Set breakpoints in modules such as `hbd/udp.py`, `hbd/dns.py`, or `hbd/server.py
 - `cert_path`: directory where TLS certificate and key are looked up (default: /usr/local/etc/ssl/)
 - `wss_pem`: filename for the certificate chain (default: fullchain.pem)
 - `wss_key`: filename for the private key (default: privkey.pem)
+- `users`: mapping of username → user attributes (full_name, avatar, password, admin, notification_channels)
+- `default_owner`: username that owns hosts with no explicit owner (falls back to first admin user)
 
 Example `.hb.yaml` (minimal):
 
@@ -464,29 +557,39 @@ nsupdate_bin: /usr/bin/nsupdate
 pushsrv: pushover
 ```
 
-> Tip: `config.DEFAULTS` in `hbd/config.py` contains the canonical defaults and accepted configuration keys.
+> Tip: `SERVER_DEFAULTS` in `hbd/server/config.py` contains the canonical defaults and accepted configuration keys.
 
 ---
 
 ## 🔧 Architecture & Modules
 
-- `hbd.proto` — serialization/deserialization of heartbeat messages (supports compressed payloads and plugin data)
+The package is organized into three subpackages:
-- `hbd.udp` — UDP parsing and `handle_datagram` implementation (main state machine)
+
-- `hbd.dns` — `create_nsupdate_payload`, `nsupdate`, and an asyncio DNS worker (`start_dns_worker`).
+**`hbd.common`** — shared code used by both client and server:
-  The DNS worker now runs as an `asyncio` task and the package exposes a
+- `hbd.common.proto` — serialization/deserialization of heartbeat messages (supports compressed payloads and plugin data)
-  small thread-safe bridge so legacy synchronous code can `put()` updates
+- `hbd.common.utils` — small utility helpers (`shortname`, `dur`, `initlog`)
-  into the queue; there is no longer a permanently-blocking background
+
-  `threading.Thread`.
+**`hbd.server`** — the heartbeat daemon (`hbd`):
-- `hbd.notify` — email and push notification helpers
+- `hbd.server.cli` — CLI entrypoint and argument parsing
-- `hbd.ws` — WebSocket server and thread-safe broadcast helpers
+- `hbd.server.main` — async orchestration to run UDP/HTTP/WSS components
-- `hbd.http` — HTTP handler factory for the status UI/API
+- `hbd.server.udp` — UDP parsing and `handle_datagram` implementation (main state machine)
-- `hbd.journal` — message journal with size-based log rotation and backup management
+- `hbd.server.dns` — `create_nsupdate_payload`, `nsupdate`, and an asyncio DNS worker (`start_dns_worker`).
-- `hbd.plugin` — plugin framework with base classes, registry, and dynamic loader
+  The DNS worker runs as an `asyncio` task and the package exposes a small thread-safe bridge
-- `hbd.plugins/` — built-in plugins (os_info, cpu_monitor, memory_monitor, disk_monitor, network_monitor, filesystem_info, nagios_runner)
+  so legacy synchronous code can `put()` updates into the queue.
-- `hbd.hbc` — heartbeat client that sends heartbeats and plugin data to server
+- `hbd.server.notify` — email and push notification helpers
-- `hbd.utils` — small utility helpers (`shortname`, `dur`, `initlog`)
+- `hbd.server.ws` — WebSocket server and thread-safe broadcast helpers
-- `hbd.cli` — CLI entrypoint and argument parsing
+- `hbd.server.http` — HTTP handler factory for the status UI/API
-- `hbd.server` — async orchestration to run UDP/HTTP/WSS components
+- `hbd.server.journal` — message journal with size-based log rotation and backup management
+- `hbd.server.threshold` — threshold alerting engine
+- `hbd.server.monitor` — host state monitoring
+- `hbd.server.hbdclass` — `Host` class and shared server state
+- `hbd.server.config` — configuration loader and defaults
+
+**`hbd.client`** — the heartbeat client (`hbc`):
+- `hbd.client.main` — client entrypoint; sends heartbeats and plugin data to the server
+- `hbd.client.plugin` — plugin framework with base classes, registry, and dynamic loader
+- `hbd.client.plugins/` — built-in plugins (os_info, cpu_monitor, memory_monitor, disk_monitor, network_monitor, filesystem_info, nagios_runner)
+- `hbd.client.config` — client configuration loader
 
 This modular layout makes the code easier to test and maintain.
 
@@ -494,12 +597,12 @@ This modular layout makes the code easier to test and maintain.
 
 - The main runtime is asyncio-based. Services (UDP listener, HTTP server, WebSocket server, monitor, and DNS worker) run as asyncio tasks.
 - On SIGINT/SIGTERM the server triggers a graceful shutdown: it cancels active tasks, signals the DNS worker via a sentinel, and cleans up resources before exit.
-- The DNS update worker is implemented as an `asyncio` task; synchronous producers can still enqueue DNS updates via a small thread-safe bridge available at `hbd.hbdclass.Host.dnsQ`.
+- The DNS update worker is implemented as an `asyncio` task; synchronous producers can still enqueue DNS updates via a small thread-safe bridge available at `hbd.server.hbdclass.Host.dnsQ`.
 
 **Templates & Static Files**
 
-- Template files are located under `hbd/templates` by default. The HTTP server resolves templates relative to the `hbd` package but the path can be overridden with the `templates_dir` config key.
+- Template files are located under `hbd/server/templates`. The HTTP server resolves templates relative to the `hbd.server` package but the path can be overridden with the `templates_dir` config key.
-- Static assets (CSS/JS/images) are served from `hbd/static` via the `/static/<path>` HTTP route. Place your static files in that directory or configure the HTTP server as needed.
+- Static assets (CSS/JS/images) are served from `hbd/server/static` via the `/static/<path>` HTTP route.
 
 ---
 

REFACTORING.md

@@ -1,234 +0,0 @@
-# HBD/HBC Separation Refactoring
-
-## Overview
-
-The heartbeat monitoring system has been refactored into a modular package structure with separate client and server components. This allows users to install only what they need and provides clear separation of concerns.
-
-## New Package Structure
-
-```
-hbd/
-├── __init__.py                 # Main package (minimal)
-├── client/                     # HBC - System monitoring client
-│   ├── __init__.py
-│   ├── main.py                # Entry point (was hbc.py)
-│   ├── config.py              # Client-specific configuration
-│   ├── plugin.py              # Plugin framework
-│   ├── threshold.py           # Threshold checking
-│   └── plugins/               # Monitoring plugins
-│       ├── cpu_monitor.py
-│       ├── disk_monitor.py
-│       ├── memory_monitor.py
-│       ├── network_monitor.py
-│       ├── filesystem_info.py
-│       ├── os_info.py
-│       └── nagios_runner.py
-├── server/                     # HBD - Heartbeat daemon/server
-│   ├── __init__.py
-│   ├── main.py                # Server runtime (was server.py)
-│   ├── cli.py                 # Command-line interface
-│   ├── config.py              # Server-specific configuration
-│   ├── http.py                # HTTP/REST API
-│   ├── ws.py                  # WebSocket server
-│   ├── udp.py                 # UDP heartbeat listener
-│   ├── dns.py                 # DNS update functionality
-│   ├── notify.py              # Notification handlers
-│   ├── monitor.py             # Host monitoring
-│   ├── hbdclass.py            # Host class definitions
-│   ├── journal.py             # Message journaling
-│   ├── templates/             # Jinja2 web templates
-│   └── static/                # Web UI assets
-└── common/                     # Shared utilities
-    ├── __init__.py
-    ├── proto.py               # Protocol encoding/decoding
-    └── utils.py               # Common utilities
-
-## Configuration Files
-
-### Client Configuration (hbd/client/config.py)
-
-Client-specific defaults:
-- `hb_port`: Port where hbd servers listen (default: 50003)
-- `interval`: Heartbeat interval in seconds (default: 10)
-- `plugins`: Per-plugin configuration
-- `thresholds`: Threshold configuration for monitoring
-
-### Server Configuration (hbd/server/config.py)
-
-Server-specific defaults:
-- `hb_port`: Port to listen for heartbeats (default: 50003)
-- `hbd_port`: HTTP API port (default: 50004)
-- `ws_port`: WebSocket port (default: 50005)
-- `logfile`, `logfmt`: Logging configuration
-- `pushsrv`, `pushover_token`, etc.: Notification settings
-- `watchhosts`, `dyndnshosts`: Host monitoring
-- `smtpserver`, etc.: Email settings
-- `journal_*`: Message journaling settings
-
-## Installation Options
-
-### Install Core Only (minimal, PyYAML only)
-```bash
-pip install hbd
-```
-
-### Install Client Only (for monitoring)
-```bash
-pip install hbd[client]
-# Installs: PyYAML, psutil
-```
-
-### Install Server Only (for daemon)
-```bash
-pip install hbd[server]
-# Installs: PyYAML, websockets, mattermostdriver, aiohttp, Jinja2
-```
-
-### Install Everything
-```bash
-pip install hbd[all]
-# Installs all dependencies for both client and server
-```
-
-### Development Installation
-```bash
-pip install -e ".[dev]"
-# Includes all dependencies plus testing/linting tools
-```
-
-## Command-Line Interfaces
-
-### HBC (Client)
-```bash
-hbc [options] host1 [host2 ...]
-
-# Entry point: hbd.client.main:main
-# Location: hbd/client/main.py
-```
-
-### HBD (Server)
-```bash
-hbd [options]
-
-# Entry point: hbd.server.cli:main
-# Location: hbd/server/cli.py → hbd/server/main.py
-```
-
-## Import Changes
-
-### Client Code
-```python
-# Old imports
-from .config import load_config
-from .proto import dicttos, stodict
-from .plugin import PluginRegistry
-
-# New imports
-from .config import load_config          # Still in client/
-from ..common.proto import dicttos       # Moved to common/
-from .plugin import PluginRegistry       # Still in client/
-```
-
-### Server Code
-```python
-# Old imports
-from .config import load_config
-from .proto import stodict
-from .threshold import AlertLevel
-
-# New imports
-from .config import load_config          # Server-specific config
-from ..common.proto import stodict       # Moved to common/
-from ..client.threshold import AlertLevel # Client module
-```
-
-### Plugin Code
-```python
-# Old import
-from hbd.plugin import MonitorPlugin
-
-# New import
-from hbd.client.plugin import MonitorPlugin
-```
-
-## Benefits
-
-1. **Modular Installation**: Install only what you need
-   - Client-only systems don't need web server dependencies
-   - Server-only systems don't need psutil
-   
-2. **Clearer Architecture**: Explicit separation of concerns
-   - Client: System monitoring and data collection
-   - Server: Heartbeat reception, web UI, notifications
-   - Common: Shared protocol and utilities
-
-3. **Independent Evolution**: Client and server can evolve separately
-   - Different release cycles possible
-   - Clear API boundaries via common/
-
-4. **Smaller Footprint**: Reduced dependency installation
-   - Client: ~1 dependency (psutil)
-   - Server: ~4 dependencies (websockets, aiohttp, Jinja2, mattermostdriver)
-
-## Migration Guide
-
-### For Existing Installations
-
-1. **Reinstall the package**:
-   ```bash
-   pip install -e ".[all]"  # For development
-   # or
-   pip install hbd[all]     # For production
-   ```
-
-2. **Configuration files remain unchanged**:
-   - Both client and server read from `~/.hb.yaml`
-   - All existing config keys are supported in both configs
-   - Server has additional keys (journal, websocket, email, etc.)
-   - Client has minimal keys (interval, plugins, thresholds)
-
-3. **Commands remain the same**:
-   - `hbc` command works identically
-   - `hbd` command works identically
-
-### For New Deployments
-
-1. **Client-only system** (monitoring host):
-   ```bash
-   pip install hbd[client]
-   hbc server1.example.com server2.example.com
-   ```
-
-2. **Server-only system** (monitoring daemon):
-   ```bash
-   pip install hbd[server]
-   hbd -c /etc/hbd.yaml -f
-   ```
-
-3. **Combined system** (dev/test):
-   ```bash
-   pip install hbd[all]
-   ```
-
-## Testing
-
-All imports and entry points have been tested and validated:
-- ✅ Package imports work correctly
-- ✅ `hbc` command entry point functional
-- ✅ `hbd` command entry point functional
-- ✅ Optional dependencies properly configured
-- ✅ All internal imports updated
-
-## Files Archived
-
-The following files were renamed to avoid conflicts:
-- `hbd/config.py` → `hbd/config.py.old` (split into client/server configs)
-- `hbd/hbc_old.py` → `hbd/hbc_old.py.bak` (backup file)
-
-## Next Steps
-
-1. Test client functionality with a monitoring host
-2. Test server functionality with web UI and notifications
-3. Update documentation (README.md) with new structure
-4. Consider publishing to PyPI with new structure
-5. Update any deployment scripts/Dockerfiles to use optional dependencies

async_sms_send.py

@@ -0,0 +1,40 @@
+async def send_sms(hass, user, password, sender_did, call):
+    """Send SMS message using multipart form-data like MMS."""
+    _LOGGER = logging.getLogger(__name__)
+    recipient = call.data.get("recipient")
+    message = call.data.get("message")
+
+    if not recipient or not message:
+        _LOGGER.error("Recipient or message missing.")
+        return
+
+    # Build form data dictionary
+    form_data = {
+        'api_username': str(user),
+        'api_password': str(password),
+        'did': str(sender_did),
+        'dst': str(recipient),
+        'message': str(message),
+        'method': 'sendSMS'
+    }
+
+    async with aiohttp.ClientSession() as session:
+        with aiohttp.MultipartWriter("form-data") as mp:
+            for key, value in form_data.items():
+                part = mp.append(value)
+                part.set_content_disposition('form-data', name=key)
+
+            _LOGGER.error("voipms_sms: sending SMS: %s", mp)
+            async with session.post(REST_ENDPOINT, data=mp) as response:
+                response_text = await response.text()
+                if response.status == 200:
+                    response_json = json.loads(response_text)
+                    if response_json['status'] == "success": 
+                        _LOGGER.info("voipms_sms: SMS sent successfully: %s", response_text)
+                    else:
+                        _LOGGER.error("voipms_sms: SMS not sent: %s", response_text)
+                else:
+                    _LOGGER.error("voipms_sms: Failed to send SMS. Status: %s, Response: %s", response.status, response_text)
+
+
+

docs/CONFIG_RELOAD.md

@@ -81,7 +81,6 @@ The following settings **cannot** be reloaded and require a service restart:
 
 - **Logging**
   - `logfile` - Log file path
-  - `logfmt` - Log format
 
 - **Journal Settings**
   - `journal_enabled` - Enable/disable journaling

docs/HTTP_API.md

@@ -15,12 +15,49 @@ Default port is `50004` (configurable via `hbd_port` in configuration).
 
 ---
 
+## Authentication
+
+When [user accounts are configured](USERS.md), every request must be authenticated.
+
+- **Browser requests** to HTML pages are redirected to `/login` automatically.  JavaScript `fetch()` calls on the dashboards send the session cookie automatically — no JS changes are needed.
+- **API / programmatic requests** must include the token in an `Authorization: Bearer <token>` header or an `X-Auth-Token` header.
+
+Unauthenticated API requests receive `401 Unauthorized`.  When no users are configured the server runs in unauthenticated mode and all endpoints are open.
+
+### Login
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:50004/api/0/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"alice","password":"secret"}' | jq -r .token)
+
+curl -H "Authorization: Bearer $TOKEN" http://localhost:50004/api/0/hosts
+```
+
+See [User Management](USERS.md) for full authentication documentation.
+
+---
+
 ## API Endpoints
 
+### Authentication
+
+| Method | Path | Description | Auth required |
+|--------|------|-------------|---------------|
+| `POST` | `/api/0/auth/login` | Obtain session token | No |
+| `POST` | `/api/0/auth/logout` | Invalidate session | Token |
+
+### Users
+
+| Method | Path | Description | Role |
+|--------|------|-------------|------|
+| `GET` | `/api/0/users` | List all users | Admin |
+| `GET` | `/api/0/users/me` | Own profile | Authenticated |
+
 ### Host Management
 
 #### GET /api/0/hosts
-Get list of all monitored hosts with their state information.
+Get list of all monitored hosts with their state information.  When auth is enabled, only hosts the caller has at least **monitor** access to are returned.
 
 **Response:**
 ```json
@@ -28,6 +65,9 @@ Get list of all monitored hosts with their state information.
   {
     "name": "webserver01",
     "dyn": false,
+    "owner": "alice",
+    "managers": ["bob"],
+    "monitors": ["carol"],
     "connections": [...]
   }
 ]
@@ -137,6 +177,32 @@ curl http://localhost:50004/api/0/hosts/database01/plugins/disk_monitor
 
 ---
 
+### Host Access
+
+#### GET /api/0/hosts/{hostname}/access
+Get owner/managers/monitors for a host. Requires **monitor** role or higher.
+
+**Response:**
+```json
+{
+  "owner": "alice",
+  "managers": ["bob"],
+  "monitors": ["carol"]
+}
+```
+
+#### PUT /api/0/hosts/{hostname}/access
+Update owner/managers/monitors. Requires **owner** role or admin.
+
+**Request body** (all fields optional):
+```json
+{ "owner": "bob", "managers": ["carol"], "monitors": [] }
+```
+
+Changes take effect immediately but are not written back to the config file. Update the config file and send `SIGHUP` to make them permanent.
+
+---
+
 ### Alert Endpoints
 
 #### GET /api/0/hosts/{hostname}/alerts
@@ -226,6 +292,16 @@ curl http://localhost:50004/api/0/alerts | jq .
 
 ## Web UI Pages
 
+### Login
+**URL:** `/login`
+
+Shown automatically when a browser request is made without a valid session (when users are configured). After successful login the browser is redirected to the originally requested page.
+
+### Logout
+**URL:** `/logout`
+
+Clears the session cookie and redirects to `/login`.
+
 ### Live Dashboard
 **URL:** `/live`
 
@@ -288,7 +364,13 @@ Comprehensive alert monitoring:
 #!/bin/bash
 # Check for critical alerts and send notification
 
-RESPONSE=$(curl -s http://localhost:50004/api/0/alerts)
+# Log in first (when auth is configured)
+TOKEN=$(curl -s -X POST http://localhost:50004/api/0/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"monitor","password":"secret"}' | jq -r .token)
+AUTH="-H \"Authorization: Bearer $TOKEN\""
+
+RESPONSE=$(curl -s $AUTH http://localhost:50004/api/0/alerts)
 CRITICAL_COUNT=$(echo "$RESPONSE" | jq '.summary.critical')
 
 if [ "$CRITICAL_COUNT" -gt 0 ]; then
@@ -305,8 +387,16 @@ fi
 import requests
 import json
 
+BASE = 'http://localhost:50004'
+
+# Log in (skip if auth not configured)
+resp = requests.post(f'{BASE}/api/0/auth/login',
+                     json={"username": "alice", "password": "secret"})
+token = resp.json().get("token")
+headers = {"Authorization": f"Bearer {token}"} if token else {}
+
 # Get all plugin data for a host
-response = requests.get('http://localhost:50004/api/0/hosts/webserver01/plugins')
+response = requests.get(f'{BASE}/api/0/hosts/webserver01/plugins', headers=headers)
 data = response.json()
 
 print(f"Host: {data['hostname']}")
@@ -318,7 +408,7 @@ for plugin, info in data['plugins'].items():
         print(f"  {metric}: {value}")
 
 # Check for alerts
-response = requests.get('http://localhost:50004/api/0/alerts')
+response = requests.get(f'{BASE}/api/0/alerts', headers=headers)
 alerts = response.json()
 
 if alerts['summary']['critical'] > 0:
@@ -389,6 +479,8 @@ API errors return appropriate HTTP status codes with JSON:
 **Common Status Codes:**
 - `200 OK` - Success
 - `400 Bad Request` - Invalid parameters
+- `401 Unauthorized` - Missing or invalid session token
+- `403 Forbidden` - Authenticated but insufficient role
 - `404 Not Found` - Resource not found
 - `500 Internal Server Error` - Server error
 
@@ -506,6 +598,14 @@ for route in list(app.router.routes()):
 
 ## Troubleshooting
 
+### API Returns 401
+- Auth is configured — include `Authorization: Bearer <token>` header
+- Token may have expired (24 h TTL) — log in again
+
+### API Returns 403
+- Authenticated user lacks the required role for this host/action
+- Check host's `owner`, `managers`, `monitors` config
+
 ### API Returns 404
 - Verify hostname in URL matches actual host name
 - Check host is sending heartbeats: `curl http://localhost:50004/api/0/hosts`
@@ -525,6 +625,7 @@ for route in list(app.router.routes()):
 
 ## See Also
 
+- [User Management](USERS.md)
 - [Plugin Development Guide](PLUGIN_DEVELOPMENT.md)
 - [Threshold Alerting Documentation](THRESHOLD_ALERTING.md)
 - [Message Journal Documentation](MESSAGE_JOURNAL.md)

docs/NOTIFICATIONS.md

@@ -2,532 +2,294 @@
 
 ## Overview
 
-The Heartbeat Monitoring System includes a flexible notification system that can send alerts through multiple channels including Email, Pushover, Signal, and Mattermost. The system supports centralized channel definitions with per-host routing, allowing fine-grained control over notification delivery.
+Notifications are dispatched to the **owner and managers** of a host, each via their own configured notification channels. Channel definitions are global; users reference them by name. No users configured → no notifications sent.
 
 ## Architecture
 
-### Components
+```
+Alert event (udp.py / threshold.py)
+  └─ notify.send_notification(host_name, Notification)
+       ├─ look up host.owner + host.managers
+       ├─ for each user → user.notification_channels
+       └─ for each channel → _dispatch_to_channel (filtered by min_level)
+```
 
-1. **Notification Channels** (`notification_channels` in config)
+Every notification carries:
-   - Centralized definitions of notification providers
+- **title** — `[LEVEL] hostname` (e.g. `[CRITICAL] webserver01`)
-   - Each channel has a type and type-specific credentials
+- **body** — detail message (metric value, threshold, duration)
-   - Reusable across multiple hosts
+- **url** — link to the plugin metrics page (`{base_url}/plugins#{hostname}`)
-
+- **level** — `RECOVER | WARNING | CRITICAL | INFO`
-2. **Channel Dispatcher** (`hbd/server/notify.py`)
-   - `pushmsg_for_host(hostname, message)`: Main entry point for host-specific notifications
-   - `_dispatch_to_channel(channel_name, channel_config, message)`: Routes to specific provider
-   - Provider functions: `pushover()`, `pushsignal()`, `pushmattermost()`, `send_email()`
-
-3. **Configuration Utilities** (`hbd/server/config.py`)
-   - `get_notification_channels_for_host(config, hostname)`: Retrieves channel names for a host
-   - `get_notification_channels_config(config, hostname)`: Retrieves full channel configurations
-   - `get_channel_config(config, channel_name)`: Gets configuration for a specific channel
-
-4. **Integration Points**
-   - **Threshold alerts**: `threshold.py` calls `notify_mod.pushmsg_for_host()`
-   - **Heartbeat events**: `udp.py` calls `notify_mod.pushmsg_for_host()` for boot/shutdown/overdue
-   - **Custom alerts**: Any code can call `notify_mod.pushmsg_for_host(hostname, message)`
 
 ## Configuration
 
-### Centralized Channel Definitions
+### Base URL
 
-Define notification channels once in your configuration file:
+Set `base_url` so notification links point to your hbd instance:
+
+```yaml
+base_url: https://hbd.example.com
+```
+
+### Global channel definitions
+
+Define channels once; reference them by name from user configs:
 
 ```yaml
 notification_channels:
-  # Signal notifications
-  signal_ops:
-    type: signal
-    cli_path: /usr/local/bin/signal-cli
-    user: +1234567890        # Your Signal number
-    recipient: +1234567890   # Recipient number
 
-  signal_oncall:
+  pushover_ops:
-    type: signal
+    type: pushover
-    cli_path: /usr/local/bin/signal-cli
+    token: your-app-token
-    user: +1234567890
+    user: your-user-key
-    recipient: +0987654321   # Different recipient
+    min_level: WARNING        # optional, default: WARNING
 
-  # Email notifications
   email_ops:
     type: email
-    recipients:
+    recipients: [ops@example.com]
-      - ops@example.com
+    sender: hbd@example.com
-      - alerts@example.com
-    sender: heartbeat@example.com
     smtp_server: smtp.example.com
     smtp_port: 587
-    smtp_user: heartbeat@example.com
+    smtp_user: hbd@example.com
-    smtp_password: your-smtp-password
+    smtp_password: secret
+    min_level: WARNING
 
-  email_devteam:
+  matrix_oncall:
-    type: email
+    type: matrix
-    recipients: [dev-alerts@example.com]
+    homeserver: https://matrix.example.org
-    sender: heartbeat-dev@example.com
+    access_token: syt_xxx
-    smtp_server: smtp.example.com
+    room_id: "!abc:matrix.example.org"
-    smtp_port: 587
+    min_level: CRITICAL       # only send critical alerts to this room
-    smtp_user: heartbeat-dev@example.com
-    smtp_password: your-smtp-password
 
-  # Pushover notifications
+  sms_oncall:
-  pushover_urgent:
+    type: sms_voipms
-    type: pushover
+    api_user: me@example.com
-    token: your-pushover-app-token
+    api_password: secret
-    user: your-pushover-user-key
+    did: "5551234567"         # your voip.ms DID number
+    dst: "5559876543"         # destination number
+    min_level: CRITICAL
 
-  pushover_normal:
+  signal_ops:
-    type: pushover
-    token: your-pushover-app-token
-    user: another-user-key
-  
-  # Mattermost notifications
-  mattermost_devops:
-    type: mattermost
-    host: mattermost.example.com
-    token: your-webhook-token
-    channel: devops-alerts
-    username: heartbeat-bot
-    icon: https://example.com/heartbeat-icon.png
-```
-
-### Default Notification Channels
-
-Specify default channels for hosts that don't have specific channel assignments:
-
-```yaml
-default_notification_channels:
-  - email_ops
-  - mattermost_devops
-```
-
-Hosts without `notification_channels` defined will use these defaults.
-
-### Per-Host Channel Assignment
-
-Assign specific channels to each host in the `hosts` section:
-
-```yaml
-hosts:
-  # Critical production web server - multiple channels for redundancy
-  prod-web-01:
-    threshold_config: high_sensitivity
-    watch: true
-    notification_channels:
-      - signal_oncall        # Immediate mobile notification
-      - pushover_urgent      # Secondary mobile notification
-      - email_ops            # Email for record keeping
-    dyndns: false
-  
-  # Database server - ops team notifications only
-  prod-db-01:
-    threshold_config: database
-    watch: true
-    notification_channels:
-      - signal_ops
-      - email_ops
-    dyndns: false
-  
-  # Development server - email only, no urgent notifications
-  dev-server-01:
-    threshold_config: low_sensitivity
-    watch: false
-    notification_channels:
-      - email_devteam
-    dyndns: false
-  
-  # Test server - uses default_notification_channels
-  test-server-01:
-    threshold_config: default
-    watch: false
-    dyndns: false
-    # No notification_channels specified = uses default_notification_channels
-```
-
-## Channel Types
-
-### Email
-
-Sends notifications via SMTP.
-
-**Configuration fields:**
-```yaml
-type: email
-recipients: [email1@example.com, email2@example.com]  # Required: List of recipients
-sender: heartbeat@example.com                         # Required: From address
-smtp_server: smtp.example.com                         # Required: SMTP server hostname
-smtp_port: 587                                        # Optional: Default 587
-smtp_user: heartbeat@example.com                      # Optional: For authenticated SMTP
-smtp_password: your-password                          # Optional: For authenticated SMTP
-```
-
-**Features:**
-- Supports multiple recipients
-- TLS/STARTTLS support on port 587
-- Authenticated and unauthenticated SMTP
-
-**Example:**
-```yaml
-notification_channels:
-  email_critical:
-    type: email
-    recipients: [admin@example.com, oncall@example.com]
-    sender: alerts@example.com
-    smtp_server: smtp.fastmail.com
-    smtp_port: 587
-    smtp_user: alerts@example.com
-    smtp_password: app-specific-password
-```
-
-### Pushover
-
-Sends push notifications to mobile devices via Pushover API.
-
-**Configuration fields:**
-```yaml
-type: pushover
-token: your-application-token    # Required: Your Pushover app token
-user: your-user-key              # Required: Recipient's user key
-```
-
-**Features:**
-- Instant mobile push notifications
-- Works on iOS and Android
-- Supports delivery confirmations
-
-**Setup:**
-1. Create a Pushover account at https://pushover.net
-2. Create an application to get your app token
-3. Note your user key from your account dashboard
-
-**Example:**
-```yaml
-notification_channels:
-  pushover_admin:
-    type: pushover
-    token: azGDORePK8gMaC0QOYAMyEEuzJnyUi
-    user: uQiRzpo4DXghDmr9QzzfQu27cmVRsG
-```
-
-### Signal
-
-Sends notifications via Signal messenger using signal-cli.
-
-**Configuration fields:**
-```yaml
-type: signal
-cli_path: /usr/local/bin/signal-cli    # Optional: Path to signal-cli binary
-user: +1234567890                       # Required: Your Signal phone number
-recipient: +0987654321                  # Required: Recipient phone number
-```
-
-**Prerequisites:**
-1. Install signal-cli: https://github.com/AsamK/signal-cli
-2. Register signal-cli with your phone number:
-   ```bash
-   signal-cli -u +1234567890 register
-   signal-cli -u +1234567890 verify CODE
-   ```
-3. Ensure signal-cli is in PATH or specify full path in config
-
-**Features:**
-- End-to-end encrypted messaging
-- Works without phone being online
-- No API fees or rate limits
-
-**Example:**
-```yaml
-notification_channels:
-  signal_admin:
     type: signal
     cli_path: /usr/local/bin/signal-cli
     user: +12025551234
     recipient: +12025559999
-```
 
-### Mattermost
+  mattermost_devops:
-
-Sends notifications to Mattermost team chat via incoming webhooks.
-
-**Configuration fields:**
-```yaml
     type: mattermost
-host: mattermost.example.com           # Required: Mattermost server hostname
+    host: mattermost.example.com
-token: your-webhook-token               # Required: Incoming webhook token
+    token: webhook-token
-channel: channel-name                   # Required: Target channel name
+    channel: devops-alerts
-username: heartbeat-bot                 # Optional: Bot display name
+    username: heartbeat-bot
-icon: https://example.com/icon.png      # Optional: Bot icon URL
 ```
 
-**Prerequisites:**
+### Users with notification channels
-1. Enable incoming webhooks in Mattermost
-2. Create an incoming webhook for your team
-3. Note the webhook token from the webhook URL
 
-**Features:**
+Each user lists which global channels they receive notifications on:
-- Team-wide visibility
-- Rich formatting support
-- Message threading
 
-**Example:**
 ```yaml
-notification_channels:
+users:
-  mattermost_ops:
+  alice:
-    type: mattermost
+    full_name: Alice Smith
-    host: chat.example.com
+    password: pbkdf2:sha256:...
-    token: abc123def456ghi789
+    admin: true
-    channel: infrastructure-alerts
+    notification_channels: [pushover_ops, email_ops]
-    username: heartbeat-monitor
+
-    icon: https://example.com/heartbeat-icon.png
+  bob:
+    full_name: Bob Jones
+    password: pbkdf2:sha256:...
+    notification_channels: [sms_oncall, matrix_oncall]
 ```
 
-## Notification Events
+### Host access — owner and managers
 
-The system sends notifications for various events:
+Notifications for a host go to its owner and all managers:
-
-### Threshold Alerts
-
-When monitored metrics exceed configured thresholds:
-
-- **State changes**: OK → WARNING, WARNING → CRITICAL, CRITICAL → OK
-- **Format**: `{LEVEL}: {hostname} - {metric_path} = {value} {threshold_info}`
-- **Example**: `CRITICAL: prod-web-01 - cpu_monitor.cpu_percent = 95.2 (threshold: > 90.0)`
-- **Re-notifications**: Periodic reminders for ongoing alerts (default: hourly)
-
-### Heartbeat Events
-
-Host lifecycle events:
-
-- **Host boot**: `{hostname} booted`
-- **Host shutdown**: `{hostname} {connection_type} shutdown`
-- **Host recovery**: `{hostname} {connection_type} is back`
-- **Connection issues**: `{hostname} {message}`
-- **Host overdue**: `{hostname} {connection_type} overdue`
-
-Only hosts with `watch: true` send heartbeat event notifications.
-
-### Custom Alerts
-
-Application code can send custom notifications:
-
-```python
-from hbd.server import notify as notify_mod
-
-# Send to host-specific channels
-notify_mod.pushmsg_for_host("prod-web-01", "Custom alert message")
-
-# Send using global config
-notify_mod.pushmsg_from_config("Global notification")
-
-# Send to specific config
-notify_mod.pushmsg(custom_config_dict, "Targeted notification")
-```
-
-## Design Principles
-
-The notification system follows these core principles:
-
-- **Centralization**: Define notification providers once, reference them by name
-- **Flexibility**: Each host can use different channels for different notification needs
-- **Redundancy**: Critical hosts can specify multiple channels for failover
-- **Clarity**: Clean separation between channel definition and channel assignment
-- **Type Safety**: Provider-specific validation at configuration time
-
-## Best Practices
-
-### Channel Organization
-
-- **Create purpose-specific channels**: `email_ops`, `signal_oncall`, `pushover_urgent`
-- **Separate by team/role**: `email_devteam`, `signal_dbateam`, `mattermost_security`
-- **Use descriptive names**: Channel names appear in logs and debugging
-
-### Redundancy
-
-For critical hosts, use multiple notification channels:
 
 ```yaml
 hosts:
-  critical-db:
+  webserver01:
-    notification_channels:
+    owner: alice             # receives all notifications for this host
-      - signal_oncall      # Primary: Mobile alert
+    managers: [bob]          # also receives notifications
-      - pushover_urgent    # Backup: Different mobile platform
+    threshold_config: default
-      - email_ops          # Tertiary: Email for record-keeping
+    watch: true              # bold in dashboard (cosmetic only)
+    dyndns: false
+
+  dbserver01:
+    owner: alice
+    managers: [bob]
+    threshold_config: database
+    dyndns: false
 ```
 
-### Notification Fatigue Prevention
+`watch: true` only affects display (bold name in the live dashboard). Notifications are now controlled entirely by owner/managers.
 
-- **Use `watch: false`** for non-critical hosts
+## Channel Types
-- **Configure appropriate thresholds** to avoid false positives
-- **Set different channels for different severities**
-- **Use `default_notification_channels`** for baseline, add more for critical systems
 
-### Security
+### `min_level` filtering
 
-- **Protect credentials**: Use file permissions to protect config files with passwords/tokens
+Every channel accepts an optional `min_level` field:
-- **Rotate tokens**: Periodically rotate API tokens and passwords
-- **Use app-specific passwords**: For email, use app-specific passwords instead of main account password
-- **Separate accounts**: Consider separate notification accounts for different environments (prod vs dev)
 
-### Testing
+| Value | Channels receive |
+|---|---|
+| `WARNING` (default) | WARNING, CRITICAL, RECOVER |
+| `CRITICAL` | CRITICAL only (and RECOVER) |
 
-Test notification channels before relying on them:
+`RECOVER` is always passed through — you don't want to miss a recovery.
 
+### pushover
+
+Sends push notifications via [Pushover](https://pushover.net). Includes title, body, and a clickable URL.
+
+```yaml
+type: pushover
+token: your-app-token     # Required: Pushover application token
+user: your-user-key       # Required: Recipient's user key
+min_level: WARNING
+```
+
+### email
+
+Sends via SMTP. Subject = title, body = message + URL on final line.
+
+```yaml
+type: email
+recipients: [ops@example.com, oncall@example.com]
+sender: hbd@example.com
+smtp_server: smtp.example.com
+smtp_port: 587             # 587 = STARTTLS (default), 465 = SSL
+smtp_user: hbd@example.com
+smtp_password: secret
+min_level: WARNING
+```
+
+### matrix
+
+Sends a formatted HTML message to a Matrix room via [matrix-nio](https://github.com/poljar/matrix-nio).
+
+```yaml
+type: matrix
+homeserver: https://matrix.example.org
+access_token: syt_xxx      # Bot account access token
+room_id: "!abc:matrix.example.org"
+min_level: WARNING
+```
+
+**Setup:**
+1. Create a bot Matrix account
+2. Obtain its access token (Element → Settings → Help & About → Access Token)
+3. Invite the bot to the target room and note the room ID
+
+### sms_voipms
+
+Sends SMS via the [voip.ms REST API](https://voip.ms/api/v1/rest.php). Message is truncated to 160 characters.
+
+```yaml
+type: sms_voipms
+api_user: me@example.com   # voip.ms account email
+api_password: secret       # voip.ms API password
+did: "5551234567"          # Your voip.ms DID (sending number)
+dst: "5559876543"          # Destination number
+min_level: CRITICAL
+```
+
+### signal
+
+Sends via [signal-cli](https://github.com/AsamK/signal-cli).
+
+```yaml
+type: signal
+cli_path: /usr/local/bin/signal-cli
+user: +12025551234         # Your registered Signal number
+recipient: +12025559999    # Recipient number
+min_level: WARNING
+```
+
+**Setup:**
 ```bash
-# Test signal-cli directly
+signal-cli -u +12025551234 register
-signal-cli -u +1234567890 send -m "Test message" +0987654321
+signal-cli -u +12025551234 verify CODE
-
-# Test SMTP
-echo "Test" | mail -s "Test Subject" admin@example.com
-
-# Test through heartbeat system (Python REPL)
-from hbd.server import notify as notify_mod, config as config_mod
-cfg = config_mod.load_config(".hb.yaml")
-notify_mod.setup(cfg)
-notify_mod.pushmsg_for_host("test-host", "Test notification")
 ```
 
+### mattermost
+
+Sends via Mattermost incoming webhook. Message is formatted as Markdown.
+
+```yaml
+type: mattermost
+host: mattermost.example.com
+token: your-webhook-token
+channel: devops-alerts
+username: heartbeat-bot    # Optional: display name
+icon: https://…/icon.png   # Optional: bot icon URL
+min_level: WARNING
+```
+
+## Notification events
+
+| Source | Level | Title example | Body example |
+|---|---|---|---|
+| Host overdue | CRITICAL | `[CRITICAL] webserver01` | `IPv4 overdue` |
+| Host recover | RECOVER | `[RECOVER] webserver01` | `IPv4 back after being overdue for 5:23` |
+| Host boot | INFO | `[INFO] webserver01` | `webserver01 booted` |
+| Host shutdown | INFO | `[INFO] webserver01` | `IPv4 shutdown` |
+| Threshold breach | WARNING/CRITICAL | `[CRITICAL] webserver01` | `cpu_percent = 95.2 (threshold: > 90.0)` |
+| Threshold reminder | CRITICAL | `[REMINDER/CRITICAL] webserver01` | `REMINDER (CRITICAL): … ongoing for 3600s` |
+| Connection issue | WARNING | `[WARNING] webserver01` | `new address detected …` |
+
+Reminder notifications (re-notify) are sent only for CRITICAL level alerts.
+
+## API reference
+
+### `send_notification(host_name, notif) -> dict`
+
+Main entry point. Dispatches to owner + managers.
+
+```python
+from hbd.server.notify import send_notification, Notification
+
+send_notification(
+    "webserver01",
+    Notification(
+        title="[CRITICAL] webserver01",
+        body="cpu_percent = 95.2 (threshold: > 90.0)",
+        level="CRITICAL",
+        url="https://hbd.example.com/plugins#webserver01",
+    ),
+)
+```
+
+Returns `{channel_name: bool}` for each channel dispatched.
+
+### `setup(cfg, loop=None)`
+
+Called once at startup from `main.py`. Pass the running asyncio event loop so Matrix sends work correctly.
+
 ## Troubleshooting
 
-### Notifications Not Sending
+**No notifications sent:**
+- Check that users are configured (`users:` section in yaml)
+- Check that the host has an `owner` or `managers` set
+- Check that users have `notification_channels` listed
+- Check that the channel names in user config match keys under `notification_channels:`
 
-1. **Check logs**: Look for "Failed to send notification" errors
+**min_level filtering too aggressive:**
-2. **Verify host is watched**: Ensure `watch: true` in host definition
+- Default is `WARNING` — both WARNING and CRITICAL are sent
-3. **Check channel configuration**: Verify credentials and settings
+- Set `min_level: WARNING` explicitly if you were expecting warnings but set CRITICAL
-4. **Test channel directly**: Use command-line tools to test provider
-5. **Check network**: Ensure server can reach notification endpoints
 
-### Signal Issues
+**Matrix sends time out:**
+- Verify the access token is valid and the bot is in the room
+- `matrix-nio` must be installed: `pip install matrix-nio`
 
-- **signal-cli not found**: Specify full path in `cli_path`
+**voip.ms SMS fails:**
-- **Not registered**: Run `signal-cli -u +NUMBER register` and verify
+- Enable the API in your voip.ms account (Account → API)
-- **Trust issues**: Run `signal-cli -u +NUMBER receive` to sync trust store
+- Verify the DID is SMS-capable in your voip.ms account
-- **Recipient not found**: Ensure recipient is in your Signal contacts
 
-### Email Issues
+**Signal not found:**
+- Specify full `cli_path`
+- Run `signal-cli -u +NUMBER receive` to sync trust store
 
-- **Authentication failed**: Check SMTP username/password
+**Email authentication failed:**
-- **TLS errors**: Verify SMTP port (587 for STARTTLS, 465 for SSL)
+- Use app-specific passwords for Gmail/Fastmail
-- **Relay denied**: Ensure SMTP server allows relay from your IP
+- Verify port: 587 for STARTTLS, 465 for SSL
-- **Timeout**: Check firewall rules for SMTP ports
 
-### Pushover Issues
+**Pushover `400` errors:**
-
+- Double-check `token` (app) and `user` (user key) — they are different values
-- **Invalid token/user**: Verify token and user key from Pushover dashboard
-- **API rate limits**: Pushover has monthly message limits on free tier
-- **HTTP errors**: Check Pushover API status page
-
-### Mattermost Issues
-
-- **Webhook not found**: Verify webhook token and ensure webhook is enabled
-- **Channel not found**: Check channel name spelling and permissions
-- **Driver import error**: Install mattermostdriver: `pip install mattermostdriver`
-
-## API Reference
-
-### Main Functions
-
-#### `pushmsg_for_host(hostname: str, msg: str, debug: int = 0) -> dict`
-
-Send notification to host-specific channels.
-
-**Parameters:**
-- `hostname`: Name of the host (used to look up notification channels)
-- `msg`: Message to send
-- `debug`: Debug level (0=no debug, 1+=debug output)
-
-**Returns:** Dictionary of results per channel: `{"signal_ops": True, "email_ops": False}`
-
-**Example:**
-```python
-from hbd.server import notify as notify_mod
-
-notify_mod.pushmsg_for_host("prod-web-01", "Server CPU at 95%")
-```
-
-**Behavior:**
-1. Looks up notification channels configured for the host
-2. If no host-specific channels, uses `default_notification_channels`
-3. Dispatches to each channel in parallel
-4. Returns dict of results keyed by channel name
-5. Logs success/failure for each channel
-
-## Examples
-
-### Complete Configuration Example
-
-```yaml
-# Notification channel definitions
-notification_channels:
-  signal_oncall:
-    type: signal
-    cli_path: /usr/local/bin/signal-cli
-    user: +12025551234
-    recipient: +12025555678
-  
-  email_ops:
-    type: email
-    recipients: [ops@example.com, alerts@example.com]
-    sender: heartbeat@example.com
-    smtp_server: smtp.fastmail.com
-    smtp_port: 587
-    smtp_user: heartbeat@example.com
-    smtp_password: app-password-here
-
-# Default channels
-default_notification_channels: [email_ops]
-
-# Host definitions with channel assignments
-hosts:
-  prod-web-01:
-    threshold_config: high_sensitivity
-    watch: true
-    notification_channels: [signal_oncall, email_ops]
-    dyndns: false
-  
-  dev-server-01:
-    threshold_config: low_sensitivity
-    watch: false
-    notification_channels: [email_ops]
-    dyndns: false
-```
-
-### Multiple Environments Example
-
-```yaml
-notification_channels:
-  # Production channels
-  signal_prod_oncall:
-    type: signal
-    user: +12025551234
-    recipient: +12025551111  # On-call phone
-  
-  email_prod_ops:
-    type: email
-    recipients: [prod-ops@example.com]
-    sender: prod-heartbeat@example.com
-    smtp_server: smtp.example.com
-  
-  # Staging channels
-  email_staging:
-    type: email
-    recipients: [staging-alerts@example.com]
-    sender: staging-heartbeat@example.com
-    smtp_server: smtp.example.com
-  
-  # Development channels
-  mattermost_dev:
-    type: mattermost
-    host: chat.example.com
-    token: dev-webhook-token
-    channel: dev-alerts
-
-hosts:
-  prod-api-01:
-    notification_channels: [signal_prod_oncall, email_prod_ops]
-  
-  staging-api-01:
-    notification_channels: [email_staging]
-  
-  dev-api-01:
-    notification_channels: [mattermost_dev]
-```

docs/USERS.md

@@ -0,0 +1,242 @@
+# User Management
+
+Heartbeat supports optional user accounts with role-based access control per host. When no users are configured the server runs in **unauthenticated mode** — all existing behaviour is unchanged.
+
+---
+
+## Overview
+
+Users are defined in the server config file. Each host can have an **owner**, zero or more **managers**, and zero or more **monitors**. A **default owner** catches any host that does not name an explicit owner.
+
+### Roles
+
+| Role | Inherits | Permissions |
+|------|----------|-------------|
+| **monitor** | — | View host status, plugin data, alerts; acknowledge alerts they were notified for |
+| **manager** | monitor | + Queue commands (`/c`), trigger DNS re-registration (`/n`), queue upgrades (`/u`); add/remove monitors |
+| **owner** | manager | + Drop host (`/d`); add/remove managers; transfer ownership; update host access |
+| **admin** *(flag)* | owner on all hosts | Full access to every host and the user list |
+
+`admin` is a flag on the user, not a per-host role. An admin user has owner-level access on every host without being listed as owner/manager/monitor.
+
+---
+
+## Configuration
+
+### Defining users
+
+```yaml
+users:
+  andreas:
+    full_name: Andreas Wrede
+    avatar: /path/to/avatar.png   # file path, URL, or base64 data URI (optional)
+    password: pbkdf2:sha256:...   # generated with: hbd passwd andreas
+    admin: true                   # optional — grants server-wide owner access
+
+  bob:
+    full_name: Bob Smith
+    password: pbkdf2:sha256:...
+    notification_channels: [pushover_standard]
+
+  carol:
+    full_name: Carol Jones
+    password: pbkdf2:sha256:...
+
+default_owner: andreas            # owns hosts with no explicit owner
+                                  # falls back to the first admin user if omitted
+```
+
+### Assigning roles to hosts
+
+```yaml
+hosts:
+  webserver01:
+    owner: andreas
+    managers: [bob]
+    monitors: [carol]
+    threshold_config: default
+    watch: true
+    notification_channels: [pushover_standard]
+
+  unattended-host:              # no owner → owned by default_owner
+    threshold_config: default
+    watch: true
+```
+
+### Generating a password hash
+
+```bash
+hbd passwd andreas
+```
+
+Enter and confirm the password when prompted. Paste the printed hash into the config file under the user's `password` key.
+
+You can also generate a hash non-interactively from Python:
+
+```python
+from hbd.server.users import hash_password
+print(hash_password("mysecret"))
+```
+
+Passwords are stored as PBKDF2-HMAC-SHA256 hashes (260 000 iterations). No third-party libraries are required — only Python's standard `hashlib`.
+
+---
+
+## Authentication
+
+When at least one user is defined, every request must be authenticated. Unauthenticated requests to HTML pages are redirected to `/login`; unauthenticated API requests receive `401 Unauthorized`.
+
+### Browser login
+
+Navigate to any page — you will be redirected to `/login` automatically. After submitting valid credentials the server sets an `hbd_session` cookie (HttpOnly, SameSite=Lax, 24 h lifetime). All subsequent requests, including JavaScript `fetch()` calls on the dashboards, carry the cookie automatically.
+
+To log out, visit `/logout`.
+
+### API / programmatic login
+
+```bash
+# Log in and capture the token
+TOKEN=$(curl -s -X POST http://localhost:50004/api/0/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"andreas","password":"mysecret"}' | jq -r .token)
+
+# Use the token in subsequent requests
+curl -H "Authorization: Bearer $TOKEN" http://localhost:50004/api/0/hosts
+```
+
+The token is identical to the session cookie value — both mechanisms work simultaneously.
+
+```bash
+# Log out
+curl -s -X POST http://localhost:50004/api/0/auth/logout \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## API Endpoints
+
+### Authentication
+
+#### POST /api/0/auth/login
+Obtain a session token.
+
+**Request body:**
+```json
+{ "username": "andreas", "password": "mysecret" }
+```
+
+**Response:**
+```json
+{ "token": "<opaque-hex-token>", "username": "andreas" }
+```
+Also sets the `hbd_session` cookie for browser clients.
+
+**Status codes:** `200 OK`, `401 Unauthorized`, `404` (auth not configured)
+
+---
+
+#### POST /api/0/auth/logout
+Invalidate the current session.
+
+**Headers:** `Authorization: Bearer <token>` or cookie
+
+**Response:** `{ "success": true }`
+
+---
+
+### Users
+
+#### GET /api/0/users
+List all users. **Admin only.**
+
+**Response:**
+```json
+[
+  { "username": "andreas", "full_name": "Andreas Wrede", "avatar": "", "admin": true, "notification_channels": [] },
+  { "username": "bob",     "full_name": "Bob Smith",     "avatar": "", "admin": false, "notification_channels": ["pushover_standard"] }
+]
+```
+
+---
+
+#### GET /api/0/users/me
+Return the currently authenticated user's profile.
+
+**Response:**
+```json
+{ "username": "carol", "full_name": "Carol Jones", "avatar": "", "admin": false, "notification_channels": [] }
+```
+
+---
+
+### Host Access
+
+#### GET /api/0/hosts/{hostname}/access
+Return owner/managers/monitors for a host. Requires at least **monitor** role.
+
+**Response:**
+```json
+{
+  "owner": "andreas",
+  "managers": ["bob"],
+  "monitors": ["carol"]
+}
+```
+
+---
+
+#### PUT /api/0/hosts/{hostname}/access
+Update owner/managers/monitors. Requires **owner** role or admin.
+
+**Request body** (all fields optional):
+```json
+{
+  "owner": "bob",
+  "managers": ["carol"],
+  "monitors": []
+}
+```
+
+Changes take effect immediately in memory. They are not written back to the config file — reload (`SIGHUP`) will re-apply config values. To make changes permanent, update the config file.
+
+---
+
+## Host visibility
+
+When users are configured, `GET /api/0/hosts` only returns hosts the authenticated user has at least monitor access to. Admins see all hosts.
+
+---
+
+## Config reload
+
+On `SIGHUP`, the server reloads the config file, re-loads the user registry, and re-applies `owner`/`managers`/`monitors` from config to all known hosts. Existing sessions remain valid after a reload.
+
+---
+
+## No-auth mode
+
+If `users:` is absent or empty, the server starts in **unauthenticated mode**:
+
+- No login required — all pages and API endpoints are accessible without credentials.
+- All permission checks pass unconditionally.
+- `/login`, `/logout`, and the auth/user API endpoints return `404`.
+
+This preserves full backwards compatibility with existing deployments.
+
+---
+
+## Security notes
+
+- Session tokens are 64-character cryptographically random hex strings (`secrets.token_hex(32)`).
+- Sessions expire after 24 hours (configurable via `users_mod.SESSION_TTL`).
+- Cookies are `HttpOnly` and `SameSite=Lax` — they are not accessible to JavaScript and are not sent on cross-site requests.
+- The HTTP API does not yet enforce TLS. For production use, place hbd behind a TLS-terminating reverse proxy (nginx, Caddy, etc.) or enable WSS.
+
+---
+
+## See Also
+
+- [HTTP API Documentation](HTTP_API.md)
+- [Notifications](NOTIFICATIONS.md)
+- Configuration example: `hbd/config_example.yaml`

docs/superpowers/plans/2026-04-25-plugin-error-checking.md

@@ -0,0 +1,602 @@
+# Plugin Error Checking Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Improve plugin error checking in hbc, especially for nagios_runner, and fix logger messages silently discarded in daemon mode.
+
+**Architecture:** Three focused changes across three files: (1) `hbd/client/plugin.py` gains a `skip_reason` attribute on Plugin and updated PluginLoader messaging; (2) `hbd/client/plugins/nagios_runner.py` gains async subprocess execution, stderr capture, signal-killed process handling, and init-time command path validation; (3) `hbd/client/main.py` gains proper post-fork logging reconfiguration to syslog.
+
+**Tech Stack:** Python 3.11+, asyncio, `logging.handlers.SysLogHandler`, pytest
+
+---
+
+## File Map
+
+| Action | Path | What changes |
+|---|---|---|
+| Modify | `hbd/client/plugin.py` | `Plugin.__init__` gains `skip_reason`; `PluginLoader` checks it |
+| Modify | `hbd/client/plugins/nagios_runner.py` | async subprocess, stderr, signal codes, init validation, `skip_reason` |
+| Modify | `hbd/client/main.py` | `_reconfigure_logging_for_daemon()` helper; remove redundant syslog calls |
+| Create | `tests/test_plugin.py` | PluginLoader messaging tests |
+| Create | `tests/test_nagios_runner.py` | NagiosRunnerPlugin behaviour tests |
+
+Run tests throughout with:
+```bash
+python -m pytest tests/test_plugin.py tests/test_nagios_runner.py -v
+```
+
+---
+
+## Task 1: Plugin.skip_reason + PluginLoader messaging
+
+**Files:**
+- Modify: `hbd/client/plugin.py:40-48` (Plugin.__init__)
+- Modify: `hbd/client/plugin.py:369-381` (PluginLoader.load_from_directory)
+- Create: `tests/test_plugin.py`
+
+- [ ] **Step 1: Write failing tests**
+
+Create `tests/test_plugin.py`:
+
+```python
+import asyncio
+import logging
+import textwrap
+
+from hbd.client.plugin import Plugin, PluginLoader, PluginRegistry
+
+
+def test_plugin_skip_reason_defaults_none(tmp_path):
+    plugin_code = textwrap.dedent("""
+        from hbd.client.plugin import MonitorPlugin
+
+        class MinimalPlugin(MonitorPlugin):
+            name = "minimal"
+            version = "1.0.0"
+            interval = 60
+
+            async def initialize(self):
+                return True
+
+            async def _collect_metrics(self):
+                return {}
+    """)
+    (tmp_path / "minimal.py").write_text(plugin_code)
+    registry = PluginRegistry()
+    loader = PluginLoader(registry)
+    asyncio.run(loader.load_from_directory(tmp_path))
+    plugin = registry.get("minimal")
+    assert plugin is not None
+    assert plugin.skip_reason is None
+
+
+def test_loader_logs_info_when_skip_reason_set(tmp_path, caplog):
+    plugin_code = textwrap.dedent("""
+        from hbd.client.plugin import MonitorPlugin
+
+        class SkippablePlugin(MonitorPlugin):
+            name = "skippable"
+            version = "1.0.0"
+            interval = 60
+
+            async def initialize(self):
+                self.skip_reason = "not configured in yaml"
+                return False
+
+            async def _collect_metrics(self):
+                return {}
+    """)
+    (tmp_path / "skippable.py").write_text(plugin_code)
+    registry = PluginRegistry()
+    loader = PluginLoader(registry)
+
+    with caplog.at_level(logging.INFO, logger="plugin.loader"):
+        count = asyncio.run(loader.load_from_directory(tmp_path))
+
+    assert count == 0
+    assert any("skipped: not configured in yaml" in r.message for r in caplog.records)
+    assert not any("failed initialization" in r.message for r in caplog.records)
+
+
+def test_loader_logs_warning_when_no_skip_reason(tmp_path, caplog):
+    plugin_code = textwrap.dedent("""
+        from hbd.client.plugin import MonitorPlugin
+
+        class FailPlugin(MonitorPlugin):
+            name = "fail"
+            version = "1.0.0"
+            interval = 60
+
+            async def initialize(self):
+                return False
+
+            async def _collect_metrics(self):
+                return {}
+    """)
+    (tmp_path / "fail_plugin.py").write_text(plugin_code)
+    registry = PluginRegistry()
+    loader = PluginLoader(registry)
+
+    with caplog.at_level(logging.WARNING, logger="plugin.loader"):
+        count = asyncio.run(loader.load_from_directory(tmp_path))
+
+    assert count == 0
+    assert any("failed initialization" in r.message for r in caplog.records)
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+python -m pytest tests/test_plugin.py -v
+```
+Expected: `test_plugin_skip_reason_defaults_none` FAILS (attribute missing), others may error.
+
+- [ ] **Step 3: Add `skip_reason` to `Plugin.__init__`**
+
+In `hbd/client/plugin.py`, in `Plugin.__init__` (around line 46), add one line:
+
+```python
+def __init__(self, config: Optional[Dict[str, Any]] = None):
+    self.config = config or {}
+    self.logger = logging.getLogger(f"plugin.{self.name}")
+    self._initialized = False
+    self.skip_reason: Optional[str] = None
+```
+
+- [ ] **Step 4: Update PluginLoader messaging**
+
+In `hbd/client/plugin.py`, replace the `if not initialized:` block (around line 372):
+
+```python
+                    if not initialized:
+                        if plugin.skip_reason:
+                            self.logger.info(
+                                f"Plugin {plugin.name} skipped: {plugin.skip_reason}"
+                            )
+                        else:
+                            self.logger.warning(
+                                f"Plugin {plugin.name} failed initialization, skipping"
+                            )
+                        continue
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+```bash
+python -m pytest tests/test_plugin.py -v
+```
+Expected: all 3 tests PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add hbd/client/plugin.py tests/test_plugin.py
+git commit -m "feat: add skip_reason to Plugin; improve PluginLoader init messaging"
+```
+
+---
+
+## Task 2: NagiosRunnerPlugin — skip_reason when no commands
+
+**Files:**
+- Modify: `hbd/client/plugins/nagios_runner.py:88-105` (initialize)
+- Modify: `tests/test_nagios_runner.py` (create)
+
+- [ ] **Step 1: Write failing test**
+
+Create `tests/test_nagios_runner.py`:
+
+```python
+import asyncio
+import logging
+import os
+import stat
+
+import pytest
+
+from hbd.client.plugins.nagios_runner import (
+    NagiosRunnerPlugin,
+    NAGIOS_OK,
+    NAGIOS_WARNING,
+    NAGIOS_CRITICAL,
+    NAGIOS_UNKNOWN,
+)
+
+
+def test_no_commands_sets_skip_reason():
+    plugin = NagiosRunnerPlugin(config={"commands": []})
+    result = asyncio.run(plugin.initialize())
+    assert result is False
+    assert plugin.skip_reason is not None
+    assert "nagios_runner.commands" in plugin.skip_reason
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+python -m pytest tests/test_nagios_runner.py::test_no_commands_sets_skip_reason -v
+```
+Expected: FAIL — `plugin.skip_reason` is `None`.
+
+- [ ] **Step 3: Set skip_reason in NagiosRunnerPlugin.initialize()**
+
+In `hbd/client/plugins/nagios_runner.py`, replace the early-return block in `initialize()` (around line 96):
+
+```python
+        if not self.commands:
+            self.skip_reason = "no commands configured (add nagios_runner.commands to config)"
+            self.logger.info("No Nagios commands configured")
+            return False
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+python -m pytest tests/test_nagios_runner.py::test_no_commands_sets_skip_reason -v
+```
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add hbd/client/plugins/nagios_runner.py tests/test_nagios_runner.py
+git commit -m "feat: set skip_reason on nagios_runner when no commands configured"
+```
+
+---
+
+## Task 3: NagiosRunnerPlugin — async subprocess, stderr capture, negative return codes
+
+**Files:**
+- Modify: `hbd/client/plugins/nagios_runner.py` (imports + `_run_nagios_plugin`)
+- Modify: `tests/test_nagios_runner.py`
+
+- [ ] **Step 1: Write failing tests**
+
+Append to `tests/test_nagios_runner.py`:
+
+```python
+def test_stderr_used_when_stdout_empty(tmp_path):
+    script = tmp_path / "check_err.sh"
+    script.write_text("#!/bin/sh\necho 'error from stderr' >&2\nexit 2\n")
+    script.chmod(script.stat().st_mode | stat.S_IEXEC)
+
+    config = {"commands": [{"name": "t", "command": str(script)}], "timeout": 5}
+    plugin = NagiosRunnerPlugin(config=config)
+    asyncio.run(plugin.initialize())
+    data = asyncio.run(plugin._collect_metrics())
+
+    assert "error from stderr" in data["t_output"]
+    assert data["t_status_code"] == NAGIOS_CRITICAL
+
+
+def test_stderr_appended_when_both_present(tmp_path):
+    script = tmp_path / "check_both.sh"
+    script.write_text("#!/bin/sh\necho 'OK - all good'\necho 'extra detail' >&2\nexit 0\n")
+    script.chmod(script.stat().st_mode | stat.S_IEXEC)
+
+    config = {"commands": [{"name": "t", "command": str(script)}], "timeout": 5}
+    plugin = NagiosRunnerPlugin(config=config)
+    asyncio.run(plugin.initialize())
+    data = asyncio.run(plugin._collect_metrics())
+
+    assert "OK - all good" in data["t_output"]
+    assert "extra detail" in data["t_output"]
+    assert data["t_status_code"] == NAGIOS_OK
+
+
+def test_negative_returncode_maps_to_unknown():
+    # kill -9 $$ kills the shell itself; asyncio sees returncode -9
+    config = {"commands": [{"name": "t", "command": "kill -9 $$"}], "timeout": 5}
+    plugin = NagiosRunnerPlugin(config=config)
+    asyncio.run(plugin.initialize())
+    data = asyncio.run(plugin._collect_metrics())
+
+    assert data["t_status_code"] == NAGIOS_UNKNOWN
+    assert "signal" in data["t_output"].lower()
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+python -m pytest tests/test_nagios_runner.py::test_stderr_used_when_stdout_empty \
+    tests/test_nagios_runner.py::test_stderr_appended_when_both_present \
+    tests/test_nagios_runner.py::test_negative_returncode_maps_to_unknown -v
+```
+Expected: all FAIL — current implementation ignores stderr and doesn't handle negative codes.
+
+- [ ] **Step 3: Update imports in nagios_runner.py**
+
+Replace the import block at the top of `hbd/client/plugins/nagios_runner.py`:
+
+```python
+import asyncio
+import os
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+from hbd.client.plugin import MonitorPlugin
+```
+
+(Remove `import subprocess`; add `import asyncio` and `import os`.)
+
+- [ ] **Step 4: Upgrade collection log level from DEBUG to INFO**
+
+In `hbd/client/plugins/nagios_runner.py`, in `_collect_metrics()`, change the debug log (around line 144) so results are visible at INFO level:
+
+```python
+                self.logger.info(
+                    f"Executed {name}: {STATUS_NAMES.get(status_code, 'UNKNOWN')} - {output[:50]}"
+                )
+```
+
+- [ ] **Step 5: Replace `_run_nagios_plugin` with async implementation**
+
+Replace the entire `_run_nagios_plugin` method in `hbd/client/plugins/nagios_runner.py`:
+
+```python
+    async def _run_nagios_plugin(
+        self,
+        command: str
+    ) -> Tuple[int, str, Dict[str, Any]]:
+        """Execute a Nagios plugin and parse its output."""
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            try:
+                stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                    proc.communicate(), timeout=self.timeout
+                )
+            except asyncio.TimeoutError:
+                proc.kill()
+                await proc.communicate()
+                self.logger.error(f"Command timed out: {command}")
+                return NAGIOS_UNKNOWN, f"Command timed out after {self.timeout}s", {}
+
+            status_code = proc.returncode
+
+            if status_code < 0:
+                return NAGIOS_UNKNOWN, f"Process killed by signal {-status_code}", {}
+
+            if status_code > 3:
+                status_code = NAGIOS_UNKNOWN
+
+            stdout = stdout_bytes.decode(errors="replace").strip()
+            stderr = stderr_bytes.decode(errors="replace").strip()
+
+            # Parse perfdata from stdout before mixing in stderr
+            perfdata = self._parse_perfdata(stdout)
+
+            # Build status message
+            status_part = stdout.split('|')[0].strip() if '|' in stdout else stdout
+
+            if not stdout and stderr:
+                output_msg = stderr
+            elif stdout and stderr:
+                output_msg = f"{status_part} [stderr: {stderr}]"
+            else:
+                output_msg = status_part
+
+            return status_code, output_msg, perfdata
+
+        except Exception as e:
+            self.logger.error(f"Error executing command: {e}")
+            return NAGIOS_UNKNOWN, f"Execution error: {str(e)}", {}
+```
+
+Also remove the now-unused `self.shell` line from `__init__` (the `shell` config key is no longer used since `create_subprocess_shell` always uses a shell):
+
+In `NagiosRunnerPlugin.__init__`, remove:
+```python
+        self.shell: bool = config.get("shell", True) if config else True
+```
+
+- [ ] **Step 6: Run tests to verify they pass**
+
+```bash
+python -m pytest tests/test_nagios_runner.py -v
+```
+Expected: all tests PASS including the 3 new ones.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add hbd/client/plugins/nagios_runner.py tests/test_nagios_runner.py
+git commit -m "feat: async subprocess in nagios_runner with stderr capture and signal handling"
+```
+
+---
+
+## Task 4: NagiosRunnerPlugin — command path validation at init
+
+**Files:**
+- Modify: `hbd/client/plugins/nagios_runner.py` (initialize)
+- Modify: `tests/test_nagios_runner.py`
+
+- [ ] **Step 1: Write failing tests**
+
+Append to `tests/test_nagios_runner.py`:
+
+```python
+def test_absolute_path_not_found_warns(caplog):
+    fake_cmd = "/nonexistent_hbc_test_path/check_something"
+    config = {"commands": [{"name": "t", "command": fake_cmd}]}
+    plugin = NagiosRunnerPlugin(config=config)
+
+    with caplog.at_level(logging.WARNING, logger="plugin.nagios_runner"):
+        asyncio.run(plugin.initialize())
+
+    assert any("not found" in r.message for r in caplog.records)
+
+
+def test_absolute_path_not_executable_warns(caplog, tmp_path):
+    non_exec = tmp_path / "check_test"
+    non_exec.write_text("#!/bin/sh\necho OK\n")
+    non_exec.chmod(0o644)  # readable but not executable
+
+    config = {"commands": [{"name": "t", "command": str(non_exec)}]}
+    plugin = NagiosRunnerPlugin(config=config)
+
+    with caplog.at_level(logging.WARNING, logger="plugin.nagios_runner"):
+        asyncio.run(plugin.initialize())
+
+    assert any("not executable" in r.message for r in caplog.records)
+
+
+def test_relative_path_not_checked(caplog):
+    # Relative paths (resolved via PATH) must not generate warnings
+    config = {"commands": [{"name": "t", "command": "echo OK"}]}
+    plugin = NagiosRunnerPlugin(config=config)
+
+    with caplog.at_level(logging.WARNING, logger="plugin.nagios_runner"):
+        asyncio.run(plugin.initialize())
+
+    assert not any(
+        "not found" in r.message or "not executable" in r.message
+        for r in caplog.records
+    )
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+python -m pytest tests/test_nagios_runner.py::test_absolute_path_not_found_warns \
+    tests/test_nagios_runner.py::test_absolute_path_not_executable_warns \
+    tests/test_nagios_runner.py::test_relative_path_not_checked -v
+```
+Expected: `test_absolute_path_not_found_warns` and `test_absolute_path_not_executable_warns` FAIL (no warnings logged); `test_relative_path_not_checked` may pass.
+
+- [ ] **Step 3: Add command path validation to `initialize()`**
+
+In `hbd/client/plugins/nagios_runner.py`, extend `initialize()` by adding validation after the existing "log each command" loop (after line 103, before `return True`):
+
+```python
+        # Validate absolute command paths early
+        for cmd_config in self.commands:
+            name = cmd_config.get("name", "unnamed")
+            command = cmd_config.get("command", "")
+            if not command:
+                continue
+            exe = command.split()[0]
+            if os.path.isabs(exe):
+                if not os.path.isfile(exe):
+                    self.logger.warning(
+                        f"Command '{name}': executable not found: {exe}"
+                    )
+                elif not os.access(exe, os.X_OK):
+                    self.logger.warning(
+                        f"Command '{name}': executable not executable: {exe}"
+                    )
+```
+
+- [ ] **Step 4: Run full test suite to verify all pass**
+
+```bash
+python -m pytest tests/test_plugin.py tests/test_nagios_runner.py -v
+```
+Expected: all tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add hbd/client/plugins/nagios_runner.py tests/test_nagios_runner.py
+git commit -m "feat: validate absolute command paths at nagios_runner init"
+```
+
+---
+
+## Task 5: Daemon mode logging — route to syslog after fork
+
+**Files:**
+- Modify: `hbd/client/main.py` (new helper + updated daemon block)
+
+No automated test for daemonization itself (fork behaviour is hard to unit-test). Manual verification steps are provided below.
+
+- [ ] **Step 1: Add `_reconfigure_logging_for_daemon` helper**
+
+In `hbd/client/main.py`, add this function just before `def build_parser()` (around line 589):
+
+```python
+def _reconfigure_logging_for_daemon(log_level: int) -> None:
+    """Replace StreamHandlers (now writing to /dev/null) with a SysLogHandler."""
+    from logging.handlers import SysLogHandler
+
+    root = logging.getLogger()
+    for handler in root.handlers[:]:
+        root.removeHandler(handler)
+        handler.close()
+
+    try:
+        syslog_handler = SysLogHandler(
+            address="/dev/log",
+            facility=SysLogHandler.LOG_DAEMON,
+        )
+    except OSError:
+        syslog_handler = SysLogHandler(
+            address=("localhost", 514),
+            facility=SysLogHandler.LOG_DAEMON,
+        )
+        # Attach the fallback first so the warning reaches syslog
+        syslog_handler.setFormatter(
+            logging.Formatter("hbc[%(process)d]: %(name)s %(levelname)s: %(message)s")
+        )
+        root.addHandler(syslog_handler)
+        root.setLevel(log_level)
+        logging.warning("/dev/log not found, using syslog UDP localhost:514")
+        return
+
+    syslog_handler.setFormatter(
+        logging.Formatter("hbc[%(process)d]: %(name)s %(levelname)s: %(message)s")
+    )
+    root.addHandler(syslog_handler)
+    root.setLevel(log_level)
+```
+
+- [ ] **Step 2: Update the daemon block in `main()`**
+
+In `hbd/client/main.py`, replace the entire `if args.daemon:` block (lines 664–675):
+
+```python
+    if args.daemon:
+        print("Daemonizing...")
+        daemonize()
+        _reconfigure_logging_for_daemon(log_level)
+        logging.info(f"hbc starting, sending heartbeat to {', '.join(args.hosts)}")
+```
+
+This removes the `import syslog`, `syslog.openlog()`, and `syslog.syslog()` calls (now handled by the logging system) and removes the no-op second `logging.basicConfig()` call.
+
+- [ ] **Step 3: Run existing test suite to confirm no regressions**
+
+```bash
+python -m pytest tests/test_plugin.py tests/test_nagios_runner.py -v
+```
+Expected: all tests still PASS.
+
+- [ ] **Step 4: Manual smoke test — verify syslog output in daemon mode**
+
+```bash
+# In one terminal, tail syslog
+sudo journalctl -f -t hbc
+
+# In another terminal, start hbc in daemon mode (replace HOST with a real or dummy host)
+python -m hbd.client.main -d -v localhost
+
+# Expected in journalctl output:
+#   hbc[<pid>]: hbc.main INFO: Starting hbc for <hostname> -> ['localhost']
+#   hbc[<pid>]: hbc.main INFO: hbc starting, sending heartbeat to localhost
+#   hbc[<pid>]: plugin.loader INFO: ...
+
+# Stop the daemon
+pkill -f "hbd.client.main"
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add hbd/client/main.py
+git commit -m "fix: reconfigure logging to syslog after daemonize() instead of no-op basicConfig"
+```

docs/superpowers/specs/2026-04-25-plugin-error-checking-design.md

@@ -0,0 +1,92 @@
+# Plugin Error Checking & Daemon Logging — Design Spec
+
+**Date:** 2026-04-25  
+**Scope:** hbc client — daemon mode logging, nagios_runner plugin robustness, PluginLoader messaging  
+**Files affected:** `hbd/client/main.py`, `hbd/client/plugins/nagios_runner.py`, `hbd/client/plugin.py`
+
+---
+
+## 1. Daemon Mode Logging
+
+### Problem
+In `main()`, `logging.basicConfig()` is called before `daemonize()` (establishing a StreamHandler to stderr), then called again after `daemonize()`. The second call is a no-op — Python ignores `basicConfig()` when handlers are already configured. After daemonization, stderr is redirected to `/dev/null`, so all subsequent log output is silently discarded.
+
+The existing `syslog.openlog()` / `syslog.syslog()` calls (lines 666–668) write a single startup message but do not integrate with the `logging` system, so plugin and connection log messages never reach syslog.
+
+### Fix
+After `daemonize()`, explicitly reconfigure the root logger:
+
+1. Remove all existing handlers (they now write to `/dev/null`).
+2. Add `logging.handlers.SysLogHandler(address='/dev/log', facility=LOG_DAEMON)`.
+3. Set formatter: `hbc[%(process)d]: %(name)s %(levelname)s: %(message)s`
+4. Preserve the `log_level` already determined from `-v`/`-x` CLI flags.
+
+Remove the redundant `syslog.openlog()` / `syslog.syslog()` calls — the logging system handles routing.
+
+**Fallback:** If `/dev/log` does not exist (containers, some BSDs), fall back to `SysLogHandler(address=('localhost', 514))`. Log one warning (to stderr, before handlers are replaced) so the operator knows.
+
+---
+
+## 2. Nagios Runner Improvements
+
+### 2a — Async Subprocess
+`_run_nagios_plugin()` is declared `async def` but calls `subprocess.run()` synchronously, blocking the event loop for the full command duration.
+
+**Fix:** Replace with `asyncio.create_subprocess_shell()` + `await proc.communicate()`. Enforce timeout with `asyncio.wait_for(..., timeout=self.timeout)` and catch `asyncio.TimeoutError`.
+
+### 2b — Stderr Capture
+Subprocess stderr is currently discarded (`capture_output=True` only captures stdout in the sync call; stderr content is lost).
+
+**Fix:** Pass `stderr=asyncio.subprocess.PIPE` to `create_subprocess_shell`. After `communicate()`, if stdout is empty but stderr has content, use stderr as the output message. If both have content, append stderr to the output for visibility.
+
+### 2c — Negative Return Codes
+A negative `returncode` means the process was killed by a signal (SIGKILL, OOM, etc.). The current code treats these as-is, which may produce unexpected status values.
+
+**Fix:** If `returncode < 0`, map to `NAGIOS_UNKNOWN` with message `"Process killed by signal {-returncode}"`.
+
+### 2d — Command Path Validation at Init
+`initialize()` currently only checks that the commands list is non-empty.
+
+**Fix:** For each command entry during `initialize()`:
+- Warn and skip the entry if `name` or `command` is missing.
+- Extract the executable (first whitespace-delimited token of the command string).
+- If the executable is an absolute path, check `os.path.isfile()` and `os.access(..., os.X_OK)`. Log a `WARNING` if either check fails.
+- Commands with relative paths or shell builtins are not checked (they may be on PATH) — just noted.
+- Validation warns only; all original entries in `self.commands` are retained and still attempted at collection time (where the existing missing-name/command guard already skips them). The plugin initializes successfully as long as the commands list is non-empty.
+
+---
+
+## 3. PluginLoader Messaging
+
+### Problem
+When `initialize()` returns `False`, the loader always logs:
+> `WARNING: Plugin X failed initialization, skipping`
+
+This is alarming when the real reason is simply "no commands configured". There is no API to distinguish "not configured" from "genuinely broken".
+
+### Fix
+Add an optional `skip_reason` attribute to `Plugin.__init__()` (defaults to `None`).
+
+In `PluginLoader.load_from_directory()`, after `initialize()` returns `False`:
+- If `plugin.skip_reason` is set → `logger.info(f"Plugin {plugin.name} skipped: {plugin.skip_reason}")`
+- If `plugin.skip_reason` is `None` → `logger.warning(f"Plugin {plugin.name} failed initialization, skipping")` (existing behaviour)
+
+In `NagiosRunnerPlugin.initialize()`, when no commands are configured:
+```python
+self.skip_reason = "no commands configured (add nagios_runner.commands to config)"
+return False
+```
+
+Genuine failures (exceptions) continue to go through the existing `except` block in the loader, logging at `ERROR` with traceback — unchanged.
+
+---
+
+## Decisions
+
+| Topic | Decision |
+|---|---|
+| Daemon log destination | syslog only (LOG_DAEMON facility) |
+| Syslog fallback | localhost:514 UDP if `/dev/log` absent |
+| Nagios result log level | INFO for all statuses (OK/WARNING/CRITICAL/UNKNOWN) |
+| Invalid command handling at init | Warn and continue; still attempt at collection time |
+| PluginLoader API change | `skip_reason` attribute on Plugin base class, checked by loader |

hbd/Plan.md

@@ -1,9 +0,0 @@
-Plan
-
-Heartbeat is a client/server based network monitor and host observer.  hbd, the server portion receives heartbeat and state messages from clients and maintaines state and hisgtory of the informations it receives.
-
-hbc, the client portion gathers information on various aspects of the
-system it is running on, and sends it to hbd. Initially this info is basic, like OS make and version, hardware info (CPU type, memory and disks), fileystem info and some resource info. hbc/hbd support a plugin system to extend the info gathered and stored.
-
-hbd also can send notification based on missed hbc updates, and on violation of pre-set limits for various state paramaters.
-

hbd/__init__.py

@@ -14,4 +14,4 @@ Install options:
 """
 
 __all__ = ["__version__"]
-__version__ = "5.0.6"
+__version__ = "5.1.12"

hbd/client/__init__.py

@@ -1,3 +1,3 @@
 """HeartBeat Client (hbc) - System monitoring client."""
 
-__version__ = "5.0.5"
+from hbd import __version__

hbd/client/config.py

@@ -2,6 +2,9 @@
 
 import logging
 import os
+import logging
+
+logger = logging.getLogger(__name__)
 
 try:
     import yaml
@@ -30,18 +33,19 @@ def load_config(path=None):
     If YAML is not available or the file does not exist, defaults are returned.
     
     Args:
-        path: Path to YAML config file (default: ~/.hb.yaml)
+        path: Path to YAML config file (default: ~/.hbc.yaml)
         
     Returns:
         Dictionary with configuration
     """
     cfg = CLIENT_DEFAULTS.copy()
     if not path:
-        # default path (~/.hb.yaml)
+        # default path (~/.hbc.yaml)
-        path = os.path.join(os.path.expanduser("~"), ".hb.yaml")
+        path = os.path.join(os.path.expanduser("~"), ".hbc.yaml")
 
     if os.path.exists(path):
         if yaml:
+            logger.info("Loading configuration from %s", path)
             with open(path) as fh:
                 data = yaml.safe_load(fh)
             # Merge YAML data with defaults
@@ -50,5 +54,5 @@ def load_config(path=None):
                 cfg[k] = v
         else:
             # yaml not installed: do not attempt to parse; user must ensure defaults
-            pass
+            logger.warning("PyYAML not available - cannot load config from %s, using defaults", path)
     return cfg

hbd/client/main.py

@@ -14,7 +14,7 @@ import signal
 import socket
 import sys
 import time
-from hashlib import md5
+from logging.handlers import SysLogHandler
 from pathlib import Path
 from typing import Dict, List, Optional
 
@@ -55,6 +55,7 @@ class AsyncConnection:
         
         self.transport: Optional[asyncio.DatagramTransport] = None
         self.protocol: Optional[asyncio.DatagramProtocol] = None
+        self._dead = False
 
         self.logger = logging.getLogger(f"hbc.conn.{addr}")
     
@@ -92,6 +93,9 @@ class AsyncConnection:
             msg: Message dictionary
             msg_id: Message ID (HTB, PLG, etc.)
         """
+        if self._dead:
+            return
+
         if not self.transport:
             await self.open()
 
@@ -166,7 +170,9 @@ class HeartbeatProtocol(asyncio.DatagramProtocol):
     
     def error_received(self, exc):
         """Handle protocol errors."""
-        self.logger.error(f"Protocol error: {exc}")
+        self.logger.warning(f"Protocol error on {self.connection.addr}: {exc} — dropping connection")
+        self.connection._dead = True
+        self.connection.close()
 
 
 async def handle_command(conn: AsyncConnection, msg: dict):
@@ -203,48 +209,45 @@ async def handle_command(conn: AsyncConnection, msg: dict):
     await conn.sendto(response)
 
 
-async def handle_update(conn: AsyncConnection, msg: dict):
+async def handle_update(conn: AsyncConnection, _msg: dict):  # pyright: ignore[reportUnusedParameter]
-    """Handle self-update from server."""
+    """Handle self-update by running hb_install.sh."""
-    import codecs
     import shutil
 
     logger = logging.getLogger("hbc.update")
 
-    try:
+    installer = shutil.which("hb_install.sh")
-        code = codecs.decode(msg["code"], "base64").decode()
+    if installer is None:
-        csum = msg["csum"]
+        candidate = Path(sys.argv[0]).parent / "hb_install.sh"
-    except Exception as e:
+        if candidate.exists():
-        error = f"Missing code/csum: {e}"
+            installer = str(candidate)
+
+    if installer is None:
+        error = "hb_install.sh not found in PATH or alongside hbc"
         logger.error(error)
         await conn.sendto({"service": "update", "msg": error})
         return
 
-    # Verify checksum
+    logger.info(f"Running installer: {installer}")
-    m = md5()
+    try:
-    m.update(code.encode())
+        proc = await asyncio.create_subprocess_exec(
-    if m.hexdigest() != csum:
+            installer, "client",
-        error = "Checksum mismatch"
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.STDOUT,
+        )
+        out, _ = await asyncio.wait_for(proc.communicate(), timeout=120)
+    except asyncio.TimeoutError:
+        error = "Installer timed out"
+        logger.error(error)
+        await conn.sendto({"service": "update", "msg": error})
+        return
+    except Exception as e:
+        error = f"Installer failed: {e}"
         logger.error(error)
         await conn.sendto({"service": "update", "msg": error})
         return
 
-    # Backup current file
+    if proc.returncode != 0:
-    fn = sys.argv[0]
+        error = f"Installer exited {proc.returncode}: {out.decode().strip()}"
-    ofn = f"{fn}.sav"
-    try:
-        shutil.copy2(fn, ofn)
-    except Exception as e:
-        error = f"Backup failed: {e}"
-        logger.error(error)
-        await conn.sendto({"service": "update", "msg": error})
-        return
-    
-    # Write new code
-    try:
-        with open(fn, "w") as fh:
-            fh.write(code)
-    except Exception as e:
-        error = f"Write failed: {e}"
         logger.error(error)
         await conn.sendto({"service": "update", "msg": error})
         return
@@ -586,6 +589,36 @@ def daemonize(
     os.dup2(se.fileno(), sys.stderr.fileno())
 
 
+def _reconfigure_logging_for_daemon(log_level: int) -> None:
+    """Replace StreamHandlers (now writing to /dev/null) with a SysLogHandler."""
+    root = logging.getLogger()
+    for handler in root.handlers[:]:
+        root.removeHandler(handler)
+        handler.close()
+
+    use_udp_fallback = not os.path.exists("/dev/log")
+
+    if use_udp_fallback:
+        syslog_handler = SysLogHandler(
+            address=("localhost", 514),
+            facility=SysLogHandler.LOG_DAEMON,
+        )
+    else:
+        syslog_handler = SysLogHandler(
+            address="/dev/log",
+            facility=SysLogHandler.LOG_DAEMON,
+        )
+
+    syslog_handler.setFormatter(
+        logging.Formatter("hbc[%(process)d]: %(name)s %(levelname)s: %(message)s")
+    )
+    root.addHandler(syslog_handler)
+    root.setLevel(log_level)
+
+    if use_udp_fallback:
+        logging.warning("/dev/log not found, using syslog UDP localhost:514")
+
+
 def build_parser():
     """Build argument parser."""
     parser = argparse.ArgumentParser(
@@ -644,13 +677,10 @@ def main(argv=None):
     parser = build_parser()
     args = parser.parse_args(argv)
     
-    # Load config
-    config = load_config(args.configfile)
-    
     # Setup logging
-    log_level = logging.INFO
+    log_level = logging.WARNING
     if args.verbose:
-        log_level = logging.DEBUG
+        log_level = logging.INFO
     if args.debug:
         log_level = logging.DEBUG
     
@@ -660,19 +690,15 @@ def main(argv=None):
         datefmt="%Y-%m-%d %H:%M:%S"
     )
 
+    # Load config
+    config = load_config(args.configfile)
+    
     # Daemonize if requested
     if args.daemon:
         print("Daemonizing...")
-        import syslog
-        syslog.openlog("hbc", syslog.LOG_PID, syslog.LOG_DAEMON)
-        syslog.syslog(syslog.LOG_INFO, f"Starting heartbeat to {', '.join(args.hosts)}")
         daemonize()
-        
+        _reconfigure_logging_for_daemon(log_level)
-        # Reconfigure logging for syslog
+        logging.info(f"hbc starting, sending heartbeat to {', '.join(args.hosts)}")
-        logging.basicConfig(
-            level=log_level,
-            format="hbc[%(process)d]: %(name)s %(levelname)s: %(message)s"
-        )
     
     # Run async main
     try:

hbd/client/plugin.py

@@ -29,6 +29,7 @@ class Plugin(ABC):
         description: Human-readable description
         interval: Collection interval in seconds (0 for InfoPlugin = collect once)
         enabled: Whether plugin is active (can be disabled via config)
+        skip_reason: Set by plugin before returning False from initialize(); causes loader to log INFO instead of WARNING.
     """
     
     name: str = ""
@@ -46,6 +47,7 @@ class Plugin(ABC):
         self.config = config or {}
         self.logger = logging.getLogger(f"plugin.{self.name}")
         self._initialized = False
+        self.skip_reason: Optional[str] = None
         
     @abstractmethod
     async def initialize(self) -> bool:
@@ -311,7 +313,11 @@ class PluginLoader:
             return 0
         
         loaded_count = 0
-        plugin_config = config or {}
+        raw_config = config or {}
+        # Per-plugin config lives under the 'plugins' key or at top-level.
+        # CLIENT_DEFAULTS seeds "plugins": {} so the key always exists; check
+        # both the subdict and top-level so that either layout in .hbc.yaml works.
+        plugins_subconfig = raw_config.get("plugins", {})
         
         # Scan for Python files
         for plugin_file in directory.glob("*.py"):
@@ -356,14 +362,20 @@ class PluginLoader:
                     
                     self.logger.debug(f"Found plugin class: {name}")
                     
-                    # Instantiate plugin with config
+                    # Instantiate plugin with config — check plugins subdict first,
-                    plugin_instance_config = plugin_config.get(obj.name, {})
+                    # then top-level keys (e.g. nagios_runner: ... at root of config).
+                    plugin_instance_config = plugins_subconfig.get(obj.name) or raw_config.get(obj.name, {})
                     plugin = obj(config=plugin_instance_config)
                     
                     # Initialize plugin
                     try:
                         initialized = await plugin.initialize()
                         if not initialized:
+                            if plugin.skip_reason:
+                                self.logger.info(
+                                    f"Plugin {plugin.name} skipped: {plugin.skip_reason}"
+                                )
+                            else:
                                 self.logger.warning(
                                     f"Plugin {plugin.name} failed initialization, skipping"
                                 )

hbd/client/plugins/nagios_runner.py

@@ -21,8 +21,10 @@ nagios_runner:
 ```
 """
 
+import asyncio
+import os
 import re
-import subprocess
+import shlex
 from typing import Any, Dict, List, Optional, Tuple
 
 from hbd.client.plugin import MonitorPlugin
@@ -52,7 +54,6 @@ class NagiosRunnerPlugin(MonitorPlugin):
         interval: Collection interval in seconds (default: 300)
         commands: List of command definitions with 'name' and 'command' keys
         timeout: Command execution timeout in seconds (default: 30)
-        shell: Whether to execute commands via shell (default: True)
 
     Example:
         nagios_runner:
@@ -76,15 +77,8 @@ class NagiosRunnerPlugin(MonitorPlugin):
         # Extract configuration
         self.commands: List[Dict[str, str]] = config.get("commands", []) if config else []
         self.timeout: int = config.get("timeout", 30) if config else 30
-        self.shell: bool = config.get("shell", True) if config else True
         self.interval = config.get("interval", 300) if config else 300
     
-        # Validate commands
-        if not self.commands:
-            self.logger.warning(
-                "No Nagios commands configured. Add 'nagios_runner.commands' to config."
-            )
-    
     async def initialize(self) -> bool:
         """Initialize the Nagios runner plugin.
 
@@ -94,7 +88,7 @@ class NagiosRunnerPlugin(MonitorPlugin):
         self.logger.info(f"Initializing {self.name} plugin")
 
         if not self.commands:
-            self.logger.error("No Nagios commands configured")
+            self.skip_reason = "no commands configured (add nagios_runner.commands to config)"
             return False
 
         self.logger.info(f"Configured to run {len(self.commands)} Nagios plugin(s)")
@@ -102,6 +96,29 @@ class NagiosRunnerPlugin(MonitorPlugin):
             name = cmd_config.get("name", "unnamed")
             self.logger.info(f"  - {name}: {cmd_config.get('command', 'N/A')}")
 
+        # Validate absolute command paths early
+        for cmd_config in self.commands:
+            name = cmd_config.get("name", "unnamed")
+            command = cmd_config.get("command", "")
+            if not command:
+                continue
+            try:
+                tokens = shlex.split(command)
+            except ValueError:
+                continue  # malformed command string; skip validation
+            if not tokens:
+                continue
+            exe = tokens[0]
+            if os.path.isabs(exe):
+                if not os.path.isfile(exe):
+                    self.logger.warning(
+                        f"Command '{name}': executable not found: {exe}"
+                    )
+                elif not os.access(exe, os.X_OK):
+                    self.logger.warning(
+                        f"Command '{name}': executable not executable: {exe}"
+                    )
+
         return True
     
     async def _collect_metrics(self) -> Dict[str, Any]:
@@ -141,7 +158,7 @@ class NagiosRunnerPlugin(MonitorPlugin):
                     for metric_name, metric_value in perfdata.items():
                         results[f"{name}_{metric_name}"] = metric_value
                 
-                self.logger.debug(
+                self.logger.info(
                     f"Executed {name}: {STATUS_NAMES.get(status_code, 'UNKNOWN')} - {output[:50]}"
                 )
                 
@@ -163,46 +180,49 @@ class NagiosRunnerPlugin(MonitorPlugin):
         self,
         command: str
     ) -> Tuple[int, str, Dict[str, Any]]:
-        """Execute a Nagios plugin and parse its output.
+        """Execute a Nagios plugin and parse its output."""
-        
-        Args:
-            command: Command string to execute
-            
-        Returns:
-            Tuple of (status_code, output_message, performance_data_dict)
-        """
         try:
-            # Run command
+            proc = await asyncio.create_subprocess_shell(
-            result = subprocess.run(
                 command,
-                shell=self.shell,
+                stdout=asyncio.subprocess.PIPE,
-                capture_output=True,
+                stderr=asyncio.subprocess.PIPE,
-                timeout=self.timeout,
-                text=True
             )
+            try:
+                stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                    proc.communicate(), timeout=self.timeout
+                )
+            except asyncio.TimeoutError:
+                proc.kill()
+                await proc.communicate()
+                self.logger.error(f"Command timed out: {command}")
+                return NAGIOS_UNKNOWN, f"Command timed out after {self.timeout}s", {}
 
-            status_code = result.returncode
+            status_code = proc.returncode
-            output = result.stdout.strip()
+
+            if status_code < 0:
+                return NAGIOS_UNKNOWN, f"Process killed by signal {-status_code}", {}
 
-            # Nagios plugins can return codes > 3, treat as UNKNOWN
             if status_code > 3:
                 status_code = NAGIOS_UNKNOWN
 
-            # Parse performance data
+            stdout = stdout_bytes.decode(errors="replace").strip()
-            perfdata = self._parse_perfdata(output)
+            stderr = stderr_bytes.decode(errors="replace").strip()
 
-            # Extract just the status message (before the pipe if present)
+            # Parse perfdata from stdout before mixing in stderr
-            if '|' in output:
+            perfdata = self._parse_perfdata(stdout)
-                output_msg = output.split('|')[0].strip()
+
+            # Build status message
+            status_part = stdout.split('|')[0].strip() if '|' in stdout else stdout
+
+            if not stdout and stderr:
+                output_msg = stderr
+            elif stdout and stderr:
+                output_msg = f"{status_part} [stderr: {stderr}]"
             else:
-                output_msg = output
+                output_msg = status_part
 
             return status_code, output_msg, perfdata
 
-        except subprocess.TimeoutExpired:
-            self.logger.error(f"Command timed out: {command}")
-            return NAGIOS_UNKNOWN, f"Command timed out after {self.timeout}s", {}
-        
         except Exception as e:
             self.logger.error(f"Error executing command: {e}")
             return NAGIOS_UNKNOWN, f"Execution error: {str(e)}", {}

hbd/client/plugins/os_info.py

@@ -48,6 +48,7 @@ class OSInfoPlugin(InfoPlugin):
             Dictionary with OS details
         """
         try:
+            from hbd import __version__ as hbc_version
             data = {
                 "system": platform.system(),  # e.g., "Linux", "Darwin", "Windows"
                 "node": platform.node(),  # hostname
@@ -58,6 +59,8 @@ class OSInfoPlugin(InfoPlugin):
                 "architecture": platform.architecture()[0],  # e.g., "64bit"
                 "python_version": platform.python_version(),
                 "python_implementation": platform.python_implementation(),
+                "hbc_version": hbc_version,
+                "hbc_type": "full",
             }
             
             # Add Linux-specific distribution info

hbd/client/plugins/ping_monitor.py

@@ -0,0 +1,151 @@
+"""Ping Monitor Plugin for Heartbeat.
+
+Pings one or more hosts and reports round-trip time.  Results are sent as
+plugin metrics so the server-side threshold system can raise WARNING/CRITICAL
+alerts using the same RTT threshold configuration format used for heartbeat RTT.
+
+Example configuration in ~/.hbc.yaml (or the plugins section of ~/.hb.yaml):
+
+```yaml
+plugins:
+  ping_monitor:
+    interval: 60          # ping every 60 seconds (default)
+    count: 3              # ICMP packets per ping run (default 3)
+    timeout: 5            # seconds before a host is considered unreachable (default 5)
+    hosts:
+      8.8.8.8:
+        warning: 20.0     # ms
+        critical: 100.0   # ms
+      192.168.1.1:
+        warning: 5.0
+        critical: 20.0
+```
+
+Reported metrics per host (metric key uses the hostname with dots/colons replaced
+by underscores so it is a valid identifier):
+
+  ping.<hostname>.rtt_avg   – average RTT in ms  (float, or inf if unreachable)
+  ping.<hostname>.rtt_min   – minimum RTT in ms
+  ping.<hostname>.rtt_max   – maximum RTT in ms
+  ping.<hostname>.loss      – packet loss percentage (0–100)
+
+Server-side threshold config example:
+
+```yaml
+threshold_configs:
+  default:
+    thresholds:
+      ping_monitor:
+        8_8_8_8_rtt_avg:
+          warning: 20.0
+          critical: 100.0
+```
+"""
+
+import asyncio
+import re
+import sys
+from typing import Any, Dict, Optional
+
+from hbd.client.plugin import MonitorPlugin
+
+
+def _host_key(host: str) -> str:
+    """Convert a hostname/IP to a safe metric key (replace . and : with _)."""
+    return re.sub(r"[^a-zA-Z0-9_]", "_", host)
+
+
+class PingMonitorPlugin(MonitorPlugin):
+    """Ping one or more configured hosts and report RTT metrics."""
+
+    name = "ping_monitor"
+    version = "1.0.0"
+    description = "ICMP ping latency monitoring"
+    interval = 60
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        super().__init__(config)
+        cfg = config or {}
+        self.interval = cfg.get("interval", 60)
+        self.count = int(cfg.get("count", 3))
+        self.timeout = int(cfg.get("timeout", 5))
+        # hosts: dict of {hostname: {warning: x, critical: y}} or list of hostnames
+        raw_hosts = cfg.get("hosts", {})
+        if isinstance(raw_hosts, list):
+            self.hosts = {h: {} for h in raw_hosts}
+        else:
+            self.hosts = dict(raw_hosts)
+
+    async def initialize(self) -> bool:
+        if not self.hosts:
+            self.logger.warning("ping_monitor: no hosts configured, plugin disabled")
+            return False
+        self.logger.info(
+            "ping_monitor initialized: %d host(s), interval=%ds, count=%d, timeout=%ds",
+            len(self.hosts), self.interval, self.count, self.timeout,
+        )
+        return True
+
+    async def _ping(self, host: str) -> Dict[str, float]:
+        """Run a system ping command and return rtt_min/avg/max/loss."""
+        if sys.platform == "win32":
+            cmd = ["ping", "-n", str(self.count), "-w", str(self.timeout * 1000), host]
+        else:
+            cmd = ["ping", "-c", str(self.count), "-W", str(self.timeout), host]
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, _ = await asyncio.wait_for(
+                proc.communicate(),
+                timeout=self.timeout * self.count + 2,
+            )
+            output = stdout.decode(errors="replace")
+        except (asyncio.TimeoutError, FileNotFoundError, OSError) as e:
+            self.logger.warning("ping_monitor: ping failed for %s: %s", host, e)
+            return {"rtt_min": float("inf"), "rtt_avg": float("inf"),
+                    "rtt_max": float("inf"), "loss": 100.0}
+
+        # Parse packet loss
+        loss = 100.0
+        loss_match = re.search(r"(\d+(?:\.\d+)?)\s*%\s*packet\s*loss", output)
+        if loss_match:
+            loss = float(loss_match.group(1))
+
+        # Parse rtt min/avg/max — Linux: "rtt min/avg/max/mdev = x/x/x/x ms"
+        #                          macOS: "round-trip min/avg/max/stddev = x/x/x/x ms"
+        rtt_match = re.search(
+            r"(?:rtt|round-trip)\s+min/avg/max/\S+\s*=\s*([\d.]+)/([\d.]+)/([\d.]+)",
+            output,
+        )
+        if rtt_match:
+            return {
+                "rtt_min": float(rtt_match.group(1)),
+                "rtt_avg": float(rtt_match.group(2)),
+                "rtt_max": float(rtt_match.group(3)),
+                "loss": loss,
+            }
+
+        # Host unreachable or all packets lost
+        return {"rtt_min": float("inf"), "rtt_avg": float("inf"),
+                "rtt_max": float("inf"), "loss": loss}
+
+    async def _collect_metrics(self) -> Dict[str, Any]:
+        data: Dict[str, Any] = {}
+        tasks = {host: asyncio.create_task(self._ping(host)) for host in self.hosts}
+        for host, task in tasks.items():
+            try:
+                result = await task
+            except Exception as e:
+                self.logger.error("ping_monitor: error pinging %s: %s", host, e)
+                result = {"rtt_min": float("inf"), "rtt_avg": float("inf"),
+                          "rtt_max": float("inf"), "loss": 100.0}
+            key = _host_key(host)
+            for metric, value in result.items():
+                data[f"{key}_{metric}"] = value
+            status = "unreachable" if result["loss"] == 100.0 else f"{result['rtt_avg']:.1f}ms"
+            self.logger.debug("ping_monitor: %s -> %s", host, status)
+        return data

hbd/common/__init__.py

@@ -1,3 +1,3 @@
 """Common utilities shared between hbc and hbd."""
 
-__version__ = "5.0.5"
+from hbd import __version__

hbd/common/proto.py

@@ -52,11 +52,16 @@ def decode_value(val: str) -> Any:
         except Exception:
             return val[1:]  # Return as string without @
     
-    # Try numeric evaluation (original behavior)
+    # Try numeric conversion (avoid eval to prevent SyntaxWarnings on version strings)
     if val[0].isdigit() or (val[0] == '-' and len(val) > 1 and val[1].isdigit()):
         try:
-            return eval(val)
+            return int(val)
-        except Exception:
+        except ValueError:
+            pass
+        try:
+            return float(val)
+        except ValueError:
+            pass
         return val
     
     return val

hbd/server/__init__.py

@@ -1,3 +1,3 @@
 """HeartBeat Daemon (hbd) - Server/daemon component."""
 
-__version__ = "5.0.5"
+from hbd import __version__

hbd/server/cli.py

@@ -1,6 +1,8 @@
 """Command line interface for hbd package."""
 
 import argparse
+import getpass
+import sys
 
 from .config import load_config
 from .main import run as run_server
@@ -14,26 +16,272 @@ def build_parser():
         description="HeartBeatDaemon - Wait for heartbeat messages and act on them (or their absence)",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    parser.add_argument(
+
-        "-c", "--config", dest="configfile", help="Config file path (YAML)"
+    subparsers = parser.add_subparsers(dest="command")
-    )
+
-    parser.add_argument(
+    # --- serve (default) ---
-        "-f", "--foreground", action="store_true", help="Run in foreground"
+    serve_p = subparsers.add_parser("serve", help="Start the hbd server (default)")
-    )
+    serve_p.add_argument("-c", "--config", dest="configfile", help="Config file path (YAML)")
+    serve_p.add_argument("-f", "--foreground", action="store_true", help="Run in foreground")
+    serve_p.add_argument("-v", "--verbose", action="store_true", help="Verbose output")
+    serve_p.add_argument("-p", "--pushsrv", dest="pushsrv", choices=PUSHSRVS,
+                         help="Push service to use")
+    serve_p.add_argument("-x", "--debug", action="count", default=0, help="Increase debug level")
+
+    # Legacy top-level flags (no subcommand) — kept for backward compatibility
+    parser.add_argument("-c", "--config", dest="configfile", help="Config file path (YAML)")
+    parser.add_argument("-f", "--foreground", action="store_true", help="Run in foreground")
     parser.add_argument("-v", "--verbose", action="store_true", help="Verbose output")
-    parser.add_argument(
+    parser.add_argument("-p", "--pushsrv", dest="pushsrv", choices=PUSHSRVS,
-        "-p", "--pushsrv", dest="pushsrv", choices=PUSHSRVS, help="Push service to use"
+                        help="Push service to use")
+    parser.add_argument("-x", "--debug", action="count", default=0, help="Increase debug level")
+
+    # --- passwd ---
+    passwd_p = subparsers.add_parser(
+        "passwd",
+        help="Generate a password hash for use in the config file",
     )
-    parser.add_argument(
+    passwd_p.add_argument(
-        "-x", "--debug", action="count", default=0, help="Increase debug level"
+        "username",
+        nargs="?",
+        help="Username (informational only, for display)",
     )
+
+    # --- notify ---
+    notify_p = subparsers.add_parser(
+        "notify",
+        help="Send a test message via a configured notification channel",
+    )
+    notify_p.add_argument("-c", "--config", dest="configfile", help="Config file path (YAML)")
+    notify_p.add_argument(
+        "channel",
+        help="Channel name as defined in notification_channels",
+    )
+    notify_p.add_argument(
+        "message",
+        nargs="?",
+        default="Test notification from hbd",
+        help="Message body (default: 'Test notification from hbd')",
+    )
+    notify_p.add_argument(
+        "--level",
+        default="WARNING",
+        choices=["INFO", "WARNING", "CRITICAL", "RECOVER"],
+        help="Notification level (default: WARNING)",
+    )
+    notify_p.add_argument(
+        "--title",
+        default=None,
+        help="Notification title (default: '[LEVEL] test')",
+    )
+
+    # --- stop ---
+    stop_p = subparsers.add_parser("stop", help="Stop the running hbd instance")
+    stop_p.add_argument("-c", "--config", dest="configfile", help="Config file path (YAML)")
+
+    # --- reload ---
+    reload_p = subparsers.add_parser("reload", help="Reload configuration (SIGHUP)")
+    reload_p.add_argument("-c", "--config", dest="configfile", help="Config file path (YAML)")
+
+    # --- restart ---
+    restart_p = subparsers.add_parser("restart", help="Restart the running hbd instance")
+    restart_p.add_argument("-c", "--config", dest="configfile", help="Config file path (YAML)")
+    restart_p.add_argument("-f", "--foreground", action="store_true", help="Run in foreground after restart")
+    restart_p.add_argument("-v", "--verbose", action="store_true", help="Verbose output after restart")
+
     return parser
 
 
+def cmd_passwd(args):
+    """Interactive password hash generator."""
+    from .users import hash_password
+
+    username = args.username or ""
+    prompt = f"New password for {username}: " if username else "New password: "
+    while True:
+        pw = getpass.getpass(prompt)
+        if not pw:
+            print("Password must not be empty.", file=sys.stderr)
+            continue
+        pw2 = getpass.getpass("Confirm password: ")
+        if pw != pw2:
+            print("Passwords do not match, try again.", file=sys.stderr)
+            continue
+        break
+
+    hashed = hash_password(pw)
+    if username:
+        print(f"\nAdd the following to your config under users: -> {username}:")
+    else:
+        print("\nPassword hash (paste into config file under the user's 'password' key):")
+    print(f"  password: {hashed}")
+
+
+def cmd_notify(args):
+    """Send a test message via a single notification channel."""
+    from .config import load_config
+    from .notify import Notification, _dispatch_to_channel, setup
+
+    config = load_config(args.configfile)
+    setup(config)
+
+    channels = config.get("notification_channels", {})
+    if args.channel not in channels:
+        available = ", ".join(channels.keys()) if channels else "(none)"
+        print(f"Error: channel '{args.channel}' not found in notification_channels.", file=sys.stderr)
+        print(f"Available channels: {available}", file=sys.stderr)
+        sys.exit(1)
+
+    channel_cfg = channels[args.channel]
+    level = args.level.upper()
+    title = args.title or f"[{level}] test"
+    base_url = config.get("base_url", "").rstrip("/")
+
+    notif = Notification(
+        title=title,
+        body=args.message,
+        level=level,
+        url=f"{base_url}/plugins" if base_url else "",
+    )
+
+    import asyncio
+    from .notify import _send_matrix_async, _send_sms_voipms_async, _DRIVERS
+    ch_type = channel_cfg.get("type", "")
+    print(f"Sending via {args.channel} ({ch_type}): {title} — {args.message}")
+
+    if ch_type == "matrix":
+        ok = asyncio.run(_send_matrix_async(channel_cfg, notif))
+    elif ch_type == "sms_voipms":
+        ok = asyncio.run(_send_sms_voipms_async(channel_cfg, notif))
+    else:
+        driver = _DRIVERS.get(ch_type)
+        if driver is None:
+            print(f"Error: unknown channel type '{ch_type}'", file=sys.stderr)
+            sys.exit(1)
+        ok = driver(channel_cfg, notif)
+
+    if ok:
+        print("OK")
+    else:
+        print("FAILED — check logs for details", file=sys.stderr)
+        sys.exit(1)
+
+
+def _read_pid(configfile) -> int | None:
+    """Return the PID from the pidfile, or None if not found / not running."""
+    import os
+    config = load_config(configfile)
+    pidfile = config.get("pidfile", "")
+    if not pidfile:
+        print("Error: no pidfile configured.", file=sys.stderr)
+        return None
+    try:
+        with open(pidfile) as f:
+            pid = int(f.read().strip())
+        # Verify process is actually running
+        os.kill(pid, 0)
+        return pid
+    except FileNotFoundError:
+        print(f"PID file not found ({pidfile}). Is hbd running?", file=sys.stderr)
+        return None
+    except ProcessLookupError:
+        print(f"PID file exists but process {pid} is not running.", file=sys.stderr)
+        return None
+    except Exception as e:
+        print(f"Error reading pidfile: {e}", file=sys.stderr)
+        return None
+
+
+def cmd_stop(args):
+    import os, signal as _signal, time
+    pid = _read_pid(args.configfile)
+    if pid is None:
+        sys.exit(1)
+    print(f"Stopping hbd (pid {pid})...")
+    os.kill(pid, _signal.SIGTERM)
+    # Wait up to 10 s for the process to exit
+    for _ in range(20):
+        time.sleep(0.5)
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            print("hbd stopped.")
+            return
+    print("Warning: hbd did not stop within 10 seconds.", file=sys.stderr)
+    sys.exit(1)
+
+
+def cmd_reload(args):
+    import os, signal as _signal
+    pid = _read_pid(args.configfile)
+    if pid is None:
+        sys.exit(1)
+    print(f"Sending SIGHUP to hbd (pid {pid})...")
+    os.kill(pid, _signal.SIGHUP)
+    print("Reload signal sent.")
+
+
+def cmd_restart(args):
+    import os, signal as _signal, time, subprocess
+    pid = _read_pid(args.configfile)
+    if pid is not None:
+        print(f"Stopping hbd (pid {pid})...")
+        os.kill(pid, _signal.SIGTERM)
+        for _ in range(20):
+            time.sleep(0.5)
+            try:
+                os.kill(pid, 0)
+            except ProcessLookupError:
+                print("hbd stopped.")
+                break
+        else:
+            print("Warning: hbd did not stop within 10 seconds.", file=sys.stderr)
+            sys.exit(1)
+    else:
+        print("hbd does not appear to be running — starting fresh.")
+
+    # Re-launch hbd with the same config
+    cmd = [sys.executable, "-m", "hbd.server.cli", "serve"]
+    if args.configfile:
+        cmd += ["-c", args.configfile]
+    if getattr(args, "foreground", False):
+        cmd += ["-f"]
+    if getattr(args, "verbose", False):
+        cmd += ["-v"]
+
+    if getattr(args, "foreground", False):
+        # Run in foreground — replace current process
+        os.execv(sys.executable, cmd)
+    else:
+        subprocess.Popen(cmd, start_new_session=True)
+        print("hbd restarted.")
+
+
 def main(argv=None):
     parser = build_parser()
     args = parser.parse_args(argv)
 
+    if args.command == "passwd":
+        cmd_passwd(args)
+        return
+
+    if args.command == "notify":
+        cmd_notify(args)
+        return
+
+    if args.command == "stop":
+        cmd_stop(args)
+        return
+
+    if args.command == "reload":
+        cmd_reload(args)
+        return
+
+    if args.command == "restart":
+        cmd_restart(args)
+        return
+
+    # Default: run the server (supports both `hbd serve ...` and `hbd ...`)
     config = load_config(args.configfile)
 
     # Apply CLI overrides

hbd/server/config.py

@@ -16,24 +16,26 @@ SERVER_DEFAULTS = {
     "hbd_host": "",             # Bind address (empty = all interfaces)
 
     # Persistence
-    "pickfile": "/tmp/hb.pick",
+    "pickfile": os.path.join(os.path.expanduser("~"), ".hb.pick"),  # File to store host state between restarts
+    "pidfile": os.path.join(os.path.expanduser("~"), ".hb.pid"),    # PID file for stop/restart/reload
 
     # Logging
-    "logfile": "/var/log/heartbeat.log",
+    "logfile": os.path.join(os.path.expanduser("~"), ".hb.log"),
-    "logfmt": "text",           # text or msg or json
-    
     # Notification channels
     "notification_channels": {},  # Named channels with type and credentials
-    "default_notification_channels": [],  # Default channels if host doesn't specify
+    "base_url": "",               # Base URL for notification links (e.g. https://hbd.example.com)
 
     # Monitoring settings
     "interval": 20,             # Expected heartbeat interval (for server checks)
     "grace": 2,                 # Grace multiplier (interval * grace = timeout)
     "threshold_renotify_interval": 3600,  # Seconds between threshold re-notifications
 
+    # User management
+    "users": {},                # username -> {full_name, avatar, password, admin, notification_channels}
+    "default_owner": None,      # Username that owns hosts with no explicit owner
+
     # Host management
-    "hosts": {},                # New unified host definitions (optional)
+    "hosts": {},                # Unified host definitions
-    "watchhosts": [],           # Hosts to monitor and notify about (legacy)
     "dyndnshosts": [],          # Hosts with dynamic DNS (legacy)
     "drophosts": [],            # Hosts to ignore
     "dyndomains": ["wrede.org"],
@@ -65,6 +67,38 @@ SERVER_DEFAULTS = {
     "thresholds": {},
 }
 
+THRESHOLD_DEFAULTS = {
+    'thresholds': {
+        'cpu_monitor': {
+            'cpu_percent': {
+                'warning': 80.0, 
+                'critical': 90.0
+                }
+            },
+            'memory_monitor': {
+                'percent': {
+                    'warning': 85.0,
+                    'critical': 95.0
+                }
+            },
+            'disk_monitor': {
+                'partitions': {
+                    '/': {
+                        'percent': {
+                            'warning': 85.0,
+                            'critical': 90.0
+                        }
+                    }
+                }
+            },
+            'rtt': {
+                'warning': 200,
+                'critical': 250.0,
+                'count': 3  # Optional: number of consecutive breaches before alerting
+            }
+        }
+    }
+
 
 def load_config(path=None):
     """Load configuration from a YAML file and merge with server defaults.
@@ -182,34 +216,18 @@ class ReloadableConfig:
 
 
 def get_watchhosts(config):
-    """Extract watchhosts from config, supporting both new and legacy formats.
+    """Extract watched hostnames from config (hosts with watch: true).
-    
-    Args:
-        config: Configuration dictionary
 
     Returns:
         List of hostnames to watch
     """
     watchhosts = []
-    
+    hosts_config = config.get("hosts", {})
-    # New format: hosts section with watch attribute
-    if "hosts" in config:
-        hosts_config = config["hosts"]
     if isinstance(hosts_config, dict):
         for host_name, host_attrs in hosts_config.items():
             if isinstance(host_attrs, dict) and host_attrs.get("watch", False):
                 watchhosts.append(host_name)
-    
+    return watchhosts
-    # Legacy format: watchhosts list
-    if "watchhosts" in config:
-        legacy_watchhosts = config.get("watchhosts", [])
-        if isinstance(legacy_watchhosts, (list, set)):
-            watchhosts.extend(legacy_watchhosts)
-        elif isinstance(legacy_watchhosts, dict):
-            # Old dict format: {"host1": {attrs}, "host2": {attrs}}
-            watchhosts.extend(legacy_watchhosts.keys())
-    
-    return list(set(watchhosts))  # Remove duplicates
 
 
 def get_dyndnshosts(config):
@@ -241,100 +259,62 @@ def get_dyndnshosts(config):
 
 
 def get_host_config(config, hostname):
-    """Get configuration for a specific host.
+    """Get configuration for a specific host from the hosts section.
-    
-    Args:
-        config: Configuration dictionary
-        hostname: Host name
 
     Returns:
         Dictionary with host attributes or empty dict
     """
-    if "hosts" in config:
     hosts_config = config.get("hosts", {})
     if isinstance(hosts_config, dict) and hostname in hosts_config:
-            return hosts_config[hostname] if isinstance(hosts_config[hostname], dict) else {}
+        val = hosts_config[hostname]
-    
+        return val if isinstance(val, dict) else {}
-    # Check legacy watchhosts for notification settings
-    if "watchhosts" in config:
-        watchhosts = config.get("watchhosts", {})
-        if isinstance(watchhosts, dict) and hostname in watchhosts:
-            legacy_attrs = watchhosts[hostname]
-            if isinstance(legacy_attrs, dict):
-                # Convert legacy format to new format
-                return {
-                    "watch": True,
-                    "notify": legacy_attrs.get("notify"),
-                    "notify_src": legacy_attrs.get("src"),
-                }
-    
     return {}
 
 
-def get_notification_channels_for_host(config, hostname):
+# ---------------------------------------------------------------------------
-    """Get notification channels configured for a specific host.
+# User / host-access helpers
+# ---------------------------------------------------------------------------
 
-    Args:
+def get_default_owner(config) -> str | None:
-        config: Configuration dictionary
+    """Return the configured default_owner username, or the first admin user, or None."""
-        hostname: Host name
+    explicit = config.get("default_owner")
-        
+    if explicit:
-    Returns:
+        return explicit
-        List of channel names to use for this host
+    # Fall back to first admin user found in config
-    """
+    users_cfg = config.get("users", {})
-    host_config = get_host_config(config, hostname)
+    if isinstance(users_cfg, dict):
-    
+        for username, attrs in users_cfg.items():
-    # Check if host specifies notification channels
+            if isinstance(attrs, dict) and attrs.get("admin", False):
-    channels = host_config.get("notification_channels", [])
+                return username
-    if channels:
-        if isinstance(channels, str):
-            return [channels]
-        elif isinstance(channels, list):
-            return channels
-    
-    # Fall back to default channels
-    default_channels = config.get("default_notification_channels", [])
-    if default_channels:
-        if isinstance(default_channels, str):
-            return [default_channels]
-        elif isinstance(default_channels, list):
-            return default_channels
-    
-    # No channels configured, return empty list (will use legacy global config)
-    return []
-
-
-def get_channel_config(config, channel_name):
-    """Get configuration for a specific notification channel.
-    
-    Args:
-        config: Configuration dictionary
-        channel_name: Name of the notification channel
-        
-    Returns:
-        Dictionary with channel configuration or None if not found
-    """
-    channels = config.get("notification_channels", {})
-    if isinstance(channels, dict) and channel_name in channels:
-        return channels[channel_name]
     return None
 
 
-def get_notification_channels_config(config, hostname):
+def get_host_access(config, hostname) -> dict:
-    """Get list of notification channel configurations for a host.
+    """Return the access dict for *hostname*: owner, managers, monitors.
 
-    Args:
+    Falls back to default_owner for hosts without an explicit owner.
-        config: Configuration dictionary
-        hostname: Host name
 
     Returns:
-        List of (channel_name, channel_config) tuples
+        {
+            "owner": str | None,
+            "managers": list[str],
+            "monitors": list[str],
+        }
     """
-    channel_names = get_notification_channels_for_host(config, hostname)
+    host_cfg = get_host_config(config, hostname)
 
-    channels = []
+    owner = host_cfg.get("owner") or get_default_owner(config)
-    for channel_name in channel_names:
-        channel_config = get_channel_config(config, channel_name)
-        if channel_config and channel_config.get("type"):
-            channels.append((channel_name, channel_config))
 
-    return channels
+    managers = host_cfg.get("managers", [])
+    if isinstance(managers, str):
+        managers = [managers]
+
+    monitors = host_cfg.get("monitors", [])
+    if isinstance(monitors, str):
+        monitors = [monitors]
+
+    return {
+        "owner": owner,
+        "managers": list(managers),
+        "monitors": list(monitors),
+    }

hbd/server/hbdclass.py

@@ -189,7 +189,7 @@ class Connection:
             except Exception:
                 pass
             self.addr = addr
-            Connection.htab[addr] = self.host.nameconnection_count
+            Connection.htab[addr] = self.host.name
             if self.host.isDynDns():
                 Host.dnsQ.put((self.host.name, self.addr))
         return r
@@ -297,6 +297,10 @@ class Host:
         self.plugin_retention = 100  # Keep last N samples per plugin
         # Alert state tracking: {metric_path: AlertState}
         self.alert_states = {}
+        # User access control
+        self.owner: str | None = None       # username of owner
+        self.managers: list = []            # usernames with manager role
+        self.monitors: list = []            # usernames with monitor role
 
     def statedict(self):
         d = {}
@@ -413,6 +417,19 @@ class Host:
         ddict["alert_critical_unacked"] = critical_unacked
         ddict["alert_critical_acked"] = critical_acked
 
+        # User access
+        ddict["owner"] = getattr(self, "owner", None)
+        ddict["managers"] = list(getattr(self, "managers", []))
+        ddict["monitors"] = list(getattr(self, "monitors", []))
+
+        # hbc version from latest os_info plugin data
+        hbc_version = None
+        latest_os = self.get_latest_plugin_data("os_info")
+        if latest_os:
+            _, os_data = latest_os
+            hbc_version = os_data.get("hbc_version")
+        ddict["hbc_version"] = hbc_version
+
         return ddict
 
     def jsons(self):
@@ -458,6 +475,13 @@ class Host:
             self.plugin_retention = 100
         if not hasattr(self, "alert_states"):
             self.alert_states = {}
+        # User access fields (added in user-management feature)
+        if not hasattr(self, "owner"):
+            self.owner = None
+        if not hasattr(self, "managers"):
+            self.managers = []
+        if not hasattr(self, "monitors"):
+            self.monitors = []
 
         pass
 
@@ -517,6 +541,32 @@ class Host:
         """
         return self.plugin_data
 
+    # ------------------------------------------------------------------
+    # User-role helpers
+    # ------------------------------------------------------------------
+
+    def apply_access(self, owner, managers, monitors):
+        """Set owner/managers/monitors on this host (called from config load)."""
+        self.owner = owner
+        self.managers = list(managers)
+        self.monitors = list(monitors)
+
+    def is_owner(self, username: str) -> bool:
+        return self.owner == username
+
+    def is_manager(self, username: str) -> bool:
+        return username in self.managers or self.is_owner(username)
+
+    def is_monitor(self, username: str) -> bool:
+        return username in self.monitors or self.is_manager(username)
+
+    def access_dict(self) -> dict:
+        return {
+            "owner": self.owner,
+            "managers": list(self.managers),
+            "monitors": list(self.monitors),
+        }
+
     hostfields_long = [
         "name",
         "IPv4.addr",

hbd/server/http.py

@@ -1,7 +1,11 @@
 """HTTP server implementation using aiohttp and jinja2."""
 
 import asyncio
+import datetime
 import json
+import platform
+import socket
+import sys
 import time
 import urllib.parse
 import os
@@ -10,6 +14,9 @@ from aiohttp import web
 import jinja2
 from . import data
 from . import notify as notify_mod
+from . import settings as settings_mod
+from . import users as users_mod
+from . import ws as ws_mod
 
 logger = logging.getLogger(__name__)
 
@@ -20,6 +27,78 @@ def _render_template(html_str: str, **context) -> str:
     return tmpl.render(**context)
 
 
+# ---------------------------------------------------------------------------
+# Auth helpers
+# ---------------------------------------------------------------------------
+
+SESSION_COOKIE = "hbd_session"
+
+
+def _get_token(request) -> str:
+    """Extract session token from Bearer header, X-Auth-Token header, or cookie."""
+    auth = request.headers.get("Authorization", "")
+    if auth.lower().startswith("bearer "):
+        return auth[7:].strip()
+    header_token = request.headers.get("X-Auth-Token", "").strip()
+    if header_token:
+        return header_token
+    return request.cookies.get(SESSION_COOKIE, "")
+
+
+def _current_user(request):
+    """Return the authenticated User, or None when auth is not enabled."""
+    if not users_mod.users_enabled():
+        return None  # unauthenticated mode — all access allowed
+    return users_mod.get_session_user(_get_token(request))
+
+
+def _require_auth(request):
+    """Return (user, None) or (None, error Response)."""
+    if not users_mod.users_enabled():
+        return None, None
+    user = users_mod.get_session_user(_get_token(request))
+    if user is None:
+        return None, web.json_response({"error": "Unauthorized"}, status=401)
+    return user, None
+
+
+def _require_auth_redirect(request):
+    """Like _require_auth but returns a redirect to /login for browser requests."""
+    if not users_mod.users_enabled():
+        return None, None
+    user = users_mod.get_session_user(_get_token(request))
+    if user is None:
+        raise web.HTTPFound("/login")
+    return user, None
+
+
+def _can_view_host(user, host) -> bool:
+    """Return True if *user* may see *host* (monitor or higher, or no auth)."""
+    if user is None:
+        return True
+    if user.admin:
+        return True
+    return host.is_monitor(user.username)
+
+
+def _can_operate_host(user, host) -> bool:
+    """Manager-level: queue commands, DNS, upgrade."""
+    if user is None:
+        return True
+    if user.admin:
+        return True
+    return host.is_manager(user.username)
+
+
+def _can_own_host(user, host) -> bool:
+    """Owner-level: drop host, transfer ownership."""
+    if user is None:
+        return True
+    if user.admin:
+        return True
+    return host.is_owner(user.username)
+
+
 async def start(
     host: str,
     port: int,
@@ -36,8 +115,10 @@ async def start(
     This function is intended to be awaited inside the main asyncio event loop.
     """
     get_now = get_now or (lambda: time.time())
+    _start_epoch = time.time()
 
-    async def index(request):
+    async def old_index(request):
+        _require_auth_redirect(request)
         res = []
         res.append('<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">')
         res.append("<html>")
@@ -62,7 +143,15 @@ async def start(
         return web.Response(text=body, content_type="text/html")
 
     async def api_hosts(request):
-        lst = [hbdclass.Host.hosts[h].jsons() for h in hbdclass.Host.hosts]
+        user, err = _require_auth(request)
+        if err:
+            return err
+        hosts = [
+            hbdclass.Host.hosts[h]
+            for h in hbdclass.Host.hosts
+            if _can_view_host(user, hbdclass.Host.hosts[h])
+        ]
+        lst = [h.jsons() for h in hosts]
         return web.json_response(json.loads("[" + ",".join(lst) + "]"))
 
     async def api_messages(request):
@@ -70,6 +159,9 @@ async def start(
         return web.json_response(lst)
 
     async def cmd(request):
+        user, err = _require_auth(request)
+        if err:
+            return err
         qa = request.rel_url.query
         uname = qa.get("h")
         ucmd = qa.get("c")
@@ -77,57 +169,73 @@ async def start(
             return web.Response(status=400, text="need h= and c= arguments")
         if uname not in hbdclass.Host.hosts:
             return web.Response(status=400, text=f"h={uname} not found")
-        hbdclass.Host.hosts[uname].cmds.append(
+        host = hbdclass.Host.hosts[uname]
-            ("CMD", {"cmd": urllib.parse.unquote(ucmd)})
+        if not _can_operate_host(user, host):
-        )
+            return web.json_response({"error": "Forbidden"}, status=403)
+        host.cmds.append(("CMD", {"cmd": urllib.parse.unquote(ucmd)}))
         return web.Response(text=f"cmd {uname} queued")
 
     async def drop(request):
+        user, err = _require_auth(request)
+        if err:
+            return err
         qa = request.rel_url.query
         uname = qa.get("h")
         if not uname:
             return web.Response(status=400, text="need h= argument")
         if uname not in hbdclass.Host.hosts:
             return web.Response(status=400, text=f"h={uname} not found")
+        host = hbdclass.Host.hosts[uname]
+        if not _can_own_host(user, host):
+            return web.json_response({"error": "Forbidden"}, status=403)
         eventlog(uname, "INFO", "dropped")
         del hbdclass.Host.hosts[uname]
         return web.Response(text="Done")
 
     async def register(request):
+        user, err = _require_auth(request)
+        if err:
+            return err
         qa = request.rel_url.query
         uname = qa.get("h")
         if not uname:
             return web.Response(status=400, text="need h= argument")
         if uname not in hbdclass.Host.hosts:
             return web.Response(status=400, text=f"h={uname} not found")
-        ll = hbdclass.Host.hosts[uname].registerDns()
+        host = hbdclass.Host.hosts[uname]
+        if not _can_operate_host(user, host):
+            return web.json_response({"error": "Forbidden"}, status=403)
+        ll = host.registerDns()
         eventlog(uname, "INFO", ll)
         return web.Response(text=str(ll))
 
     async def update(request):
+        user, err = _require_auth(request)
+        if err:
+            return err
         qa = request.rel_url.query
         uname = urllib.parse.unquote(qa.get("h", ""))
-        ucode = qa.get("c")
+        if not uname:
-        if not ucode or not uname:
+            return web.Response(status=400, text="need h= argument")
-            return web.Response(status=400, text="need h= and c= arguments")
         if uname != "All" and uname not in hbdclass.Host.hosts:
             return web.Response(status=400, text=f"h={uname} not found")
-        if uname != "All":
+        names = [uname] if uname != "All" else list(hbdclass.Host.hosts)
-            names = [uname]
-        else:
-            names = [n for n in hbdclass.Host.hosts]
         out = []
         for n in names:
-            err = None
+            host = hbdclass.Host.hosts[n]
+            if not _can_operate_host(user, host):
+                out.append(f"update skipped for {n}: Forbidden")
+                continue
+            op_err = None
             try:
-                r = {"csum": None, "code": ucode}
+                host.cmds.append(("UPD", {}))
-                hbdclass.Host.hosts[n].cmds.append(("UPD", r))
             except Exception as e:
-                err = str(e)
+                op_err = str(e)
-            out.append(f"update started for {n}: {err if err else 'OK'}")
+            out.append(f"update started for {n}: {op_err if op_err else 'OK'}")
         return web.Response(text="\n".join(out))
 
     async def live(request):
+        current_user, _ = _require_auth_redirect(request)
         # render template from hbd/templates/live.html using Jinja2
         # Resolve templates directory relative to the hbd package
         pkg_dir = os.path.dirname(__file__)
@@ -135,11 +243,12 @@ async def start(
         env = jinja2.Environment(loader=jinja2.FileSystemLoader(templates_dir))
         host = config.get("hb_host", "localhost")
         extra_scripts = config.get("http_extra_scripts", "")
-        host = request.host.split(":")[0]
+        host = request.host  # includes port if non-standard
-        if config.get("wss_port"):
+        forwarded_proto = request.headers.get("X-Forwarded-Proto", "")
-            heartbeat_ws_url = f"wss://{host}:{config['wss_port']}/hbd"
+        is_secure = request.secure or forwarded_proto.lower() == "https"
-        else:
+        scheme = "wss" if is_secure else "ws"
-            heartbeat_ws_url = f"ws://{host}:{config.get('ws_port', 50005)}/hbd"
+        heartbeat_ws_url = f"{scheme}://{host}/ws"
+        from hbd import __version__ as hbd_version
         tmpl = env.get_template("live.html")
         body = tmpl.render(
             title="Heartbeat",
@@ -147,10 +256,13 @@ async def start(
             request=request,
             heartbeat_ws_url=heartbeat_ws_url,
             extra_scripts=extra_scripts,
+            hbd_version=hbd_version,
             hosts=[
                 hbdclass.Host.hosts[h].stateinfo() for h in sorted(hbdclass.Host.hosts)
             ],
             messages=data.msgs[-30:],
+            current_user=current_user.to_dict() if current_user else None,
+            active_page="live",
         )
         return web.Response(text=body, content_type="text/html")
 
@@ -185,15 +297,17 @@ async def start(
 
     async def api_host_plugins(request):
         """Get all plugin data for a specific host."""
+        user, err = _require_auth(request)
+        if err:
+            return err
         hostname = request.match_info.get("hostname")
         
         if hostname not in hbdclass.Host.hosts:
-            return web.json_response(
+            return web.json_response({"error": f"Host '{hostname}' not found"}, status=404)
-                {"error": f"Host '{hostname}' not found"},
-                status=404
-            )
 
         host = hbdclass.Host.hosts[hostname]
+        if not _can_view_host(user, host):
+            return web.json_response({"error": "Forbidden"}, status=403)
 
         # Get plugin data with most recent sample for each plugin
         plugins_summary = {}
@@ -214,16 +328,18 @@ async def start(
 
     async def api_host_plugin_detail(request):
         """Get detailed data for a specific plugin on a host."""
+        user, err = _require_auth(request)
+        if err:
+            return err
         hostname = request.match_info.get("hostname")
         plugin_name = request.match_info.get("plugin_name")
 
         if hostname not in hbdclass.Host.hosts:
-            return web.json_response(
+            return web.json_response({"error": f"Host '{hostname}' not found"}, status=404)
-                {"error": f"Host '{hostname}' not found"},
-                status=404
-            )
 
         host = hbdclass.Host.hosts[hostname]
+        if not _can_view_host(user, host):
+            return web.json_response({"error": "Forbidden"}, status=403)
         
         # Get limit from query parameter
         limit = request.rel_url.query.get("limit", "10")
@@ -259,15 +375,17 @@ async def start(
 
     async def api_host_alerts(request):
         """Get alert states for a specific host."""
+        user, err = _require_auth(request)
+        if err:
+            return err
         hostname = request.match_info.get("hostname")
 
         if hostname not in hbdclass.Host.hosts:
-            return web.json_response(
+            return web.json_response({"error": f"Host '{hostname}' not found"}, status=404)
-                {"error": f"Host '{hostname}' not found"},
-                status=404
-            )
 
         host = hbdclass.Host.hosts[hostname]
+        if not _can_view_host(user, host):
+            return web.json_response({"error": "Forbidden"}, status=403)
         
         # Get alert states
         alerts = []
@@ -287,9 +405,14 @@ async def start(
 
     async def api_all_alerts(request):
         """Get all active alerts across all hosts."""
+        user, err = _require_auth(request)
+        if err:
+            return err
         all_alerts = []
 
         for hostname, host in hbdclass.Host.hosts.items():
+            if not _can_view_host(user, host):
+                continue
             if threshold_checker:
                 active_alerts = threshold_checker.get_active_alerts(host.alert_states)
             else:
@@ -326,6 +449,9 @@ async def start(
     
     async def api_acknowledge_alert(request):
         """Acknowledge an alert to stop reminder notifications."""
+        user, err = _require_auth(request)
+        if err:
+            return err
         try:
             data = await request.json()
         except Exception:
@@ -350,6 +476,8 @@ async def start(
             )
         
         host = hbdclass.Host.hosts[hostname]
+        if not _can_view_host(user, host):
+            return web.json_response({"error": "Forbidden"}, status=403)
 
         if metric_path not in host.alert_states:
             return web.json_response(
@@ -373,14 +501,17 @@ async def start(
 
     async def plugins_page(request):
         """Render the plugin metrics visualization page."""
+        current_user, _ = _require_auth_redirect(request)
         pkg_dir = os.path.dirname(__file__)
         templates_dir = config.get("templates_dir", os.path.join(pkg_dir, "templates"))
         env = jinja2.Environment(loader=jinja2.FileSystemLoader(templates_dir))
 
-        # Collect all hosts with plugin data
+        # Collect all hosts with plugin data (filtered by visibility)
         hosts_with_plugins = []
         for hostname in sorted(hbdclass.Host.hosts.keys()):
             host = hbdclass.Host.hosts[hostname]
+            if not _can_view_host(current_user, host):
+                continue
             if host.plugin_data:
                 hosts_with_plugins.append({
                     "name": hostname,
@@ -389,14 +520,17 @@ async def start(
 
         tmpl = env.get_template("plugins.html")
         body = tmpl.render(
-            title="Plugin Metrics - Heartbeat",
+            title="Host Overview - Heartbeat",
-            header="Plugin Metrics",
+            header="Host Overview",
             hosts=hosts_with_plugins,
+            current_user=current_user.to_dict() if current_user else None,
+            active_page="plugins",
         )
         return web.Response(text=body, content_type="text/html")
 
     async def alerts_page(request):
         """Render the alerts dashboard page."""
+        current_user, _ = _require_auth_redirect(request)
         pkg_dir = os.path.dirname(__file__)
         templates_dir = config.get("templates_dir", os.path.join(pkg_dir, "templates"))
         env = jinja2.Environment(loader=jinja2.FileSystemLoader(templates_dir))
@@ -405,18 +539,364 @@ async def start(
         body = tmpl.render(
             title="Alerts Dashboard - Heartbeat",
             header="Alerts Dashboard",
+            current_user=current_user.to_dict() if current_user else None,
+            active_page="alerts",
+        )
+        return web.Response(text=body, content_type="text/html")
+
+    # -------------------------------------------------------------------------
+    # Auth endpoints
+    # -------------------------------------------------------------------------
+
+    async def api_login(request):
+        """POST /api/0/auth/login  {username, password} -> {token}
+        Also sets an hbd_session cookie for browser clients.
+        """
+        if not users_mod.users_enabled():
+            return web.json_response({"error": "Auth not configured"}, status=404)
+        try:
+            body = await request.json()
+        except Exception:
+            return web.json_response({"error": "Invalid JSON"}, status=400)
+        username = body.get("username", "")
+        password = body.get("password", "")
+        user = users_mod.authenticate(username, password)
+        if user is None:
+            return web.json_response({"error": "Invalid credentials"}, status=401)
+        token = users_mod.create_session(username)
+        resp = web.json_response({"token": token, "username": username})
+        resp.set_cookie(
+            SESSION_COOKIE,
+            token,
+            max_age=users_mod.SESSION_TTL,
+            httponly=True,
+            samesite="Lax",
+        )
+        return resp
+
+    async def login_page(request):
+        """GET /login — show login form; POST /login — process and redirect."""
+        if not users_mod.users_enabled():
+            raise web.HTTPFound("/")
+
+        error = ""
+        if request.method == "POST":
+            form = await request.post()
+            username = form.get("username", "")
+            password = form.get("password", "")
+            user = users_mod.authenticate(username, password)
+            if user:
+                token = users_mod.create_session(username)
+                redirect_to = request.rel_url.query.get("next", "/")
+                resp = web.HTTPFound(redirect_to)
+                resp.set_cookie(
+                    SESSION_COOKIE,
+                    token,
+                    max_age=users_mod.SESSION_TTL,
+                    httponly=True,
+                    samesite="Lax",
+                )
+                raise resp
+            error = "Invalid username or password."
+
+        html = f"""<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Heartbeat — Login</title>
+  <style>
+    body {{ font-family: sans-serif; background: #f5f5f5; display: flex;
+            justify-content: center; align-items: center; height: 100vh; margin: 0; }}
+    .box {{ background: #fff; padding: 2em 2.5em; border-radius: 8px;
+             box-shadow: 0 2px 12px rgba(0,0,0,.15); min-width: 300px; }}
+    h2 {{ margin: 0 0 1.2em; color: #333; font-size: 1.4em; }}
+    label {{ display: block; margin-bottom: .3em; font-size: .9em; color: #555; }}
+    input {{ width: 100%; padding: .5em .7em; border: 1px solid #ccc;
+              border-radius: 4px; font-size: 1em; box-sizing: border-box; }}
+    button {{ margin-top: 1.2em; width: 100%; padding: .6em; background: #0066cc;
+               color: #fff; border: none; border-radius: 4px; font-size: 1em; cursor: pointer; }}
+    button:hover {{ background: #0055aa; }}
+    .error {{ color: #c00; font-size: .9em; margin-bottom: .8em; }}
+    .field {{ margin-bottom: .9em; }}
+  </style>
+</head>
+<body>
+  <div class="box">
+    <h2>Heartbeat</h2>
+    {'<p class="error">' + error + '</p>' if error else ''}
+    <form method="post">
+      <div class="field"><label>Username</label><input name="username" autofocus></div>
+      <div class="field"><label>Password</label><input name="password" type="password"></div>
+      <button type="submit">Sign in</button>
+    </form>
+  </div>
+</body>
+</html>"""
+        return web.Response(text=html, content_type="text/html")
+
+    async def web_logout(request):
+        """GET /logout — clear session cookie and redirect to /login."""
+        token = request.cookies.get(SESSION_COOKIE, "")
+        users_mod.delete_session(token)
+        resp = web.HTTPFound("/login")
+        resp.del_cookie(SESSION_COOKIE)
+        raise resp
+
+    async def api_logout(request):
+        """POST /api/0/auth/logout"""
+        token = _get_token(request)
+        users_mod.delete_session(token)
+        resp = web.json_response({"success": True})
+        resp.del_cookie(SESSION_COOKIE)
+        return resp
+
+    # -------------------------------------------------------------------------
+    # User endpoints
+    # -------------------------------------------------------------------------
+
+    async def api_user_avatar(request):
+        """GET /api/0/users/{username}/avatar — serve a local avatar file.
+
+        Only reachable when the user's avatar config value starts with '/'.
+        Falls back to 404 for external URLs (the browser fetches those directly).
+        """
+        user, err = _require_auth(request)
+        if err:
+            return err
+        username = request.match_info.get("username")
+        target_user = users_mod.get_user(username)
+        if target_user is None:
+            return web.Response(status=404, text="User not found")
+        if not target_user.avatar_is_local():
+            return web.Response(status=404, text="No local avatar configured")
+        path = target_user.avatar
+        if not os.path.isfile(path):
+            return web.Response(status=404, text="Avatar file not found")
+        # Infer content-type from extension
+        ext = os.path.splitext(path)[1].lower()
+        mime = {
+            ".png": "image/png",
+            ".jpg": "image/jpeg",
+            ".jpeg": "image/jpeg",
+            ".gif": "image/gif",
+            ".webp": "image/webp",
+            ".svg": "image/svg+xml",
+        }.get(ext, "application/octet-stream")
+        return web.FileResponse(path=path, headers={"Content-Type": mime})
+
+    async def api_users(request):
+        """GET /api/0/users — admin only."""
+        user, err = _require_auth(request)
+        if err:
+            return err
+        if users_mod.users_enabled() and (user is None or not user.admin):
+            return web.json_response({"error": "Forbidden"}, status=403)
+        return web.json_response([u.to_dict() for u in users_mod.users.values()])
+
+    async def api_user_self(request):
+        """GET /api/0/users/me — own profile."""
+        user, err = _require_auth(request)
+        if err:
+            return err
+        if user is None:
+            return web.json_response({"error": "Auth not configured"}, status=404)
+        return web.json_response(user.to_dict())
+
+    # -------------------------------------------------------------------------
+    # Host access endpoints
+    # -------------------------------------------------------------------------
+
+    async def api_host_access_get(request):
+        """GET /api/0/hosts/{hostname}/access"""
+        user, err = _require_auth(request)
+        if err:
+            return err
+        hostname = request.match_info.get("hostname")
+        if hostname not in hbdclass.Host.hosts:
+            return web.json_response({"error": f"Host '{hostname}' not found"}, status=404)
+        host = hbdclass.Host.hosts[hostname]
+        if not _can_view_host(user, host):
+            return web.json_response({"error": "Forbidden"}, status=403)
+        return web.json_response(host.access_dict())
+
+    async def api_host_access_put(request):
+        """PUT /api/0/hosts/{hostname}/access  — owner or admin only.
+
+        Body: {owner?: str, managers?: [str], monitors?: [str]}
+        """
+        user, err = _require_auth(request)
+        if err:
+            return err
+        hostname = request.match_info.get("hostname")
+        if hostname not in hbdclass.Host.hosts:
+            return web.json_response({"error": f"Host '{hostname}' not found"}, status=404)
+        host = hbdclass.Host.hosts[hostname]
+        if not _can_own_host(user, host):
+            return web.json_response({"error": "Forbidden"}, status=403)
+        try:
+            body = await request.json()
+        except Exception:
+            return web.json_response({"error": "Invalid JSON"}, status=400)
+
+        if "owner" in body:
+            host.owner = body["owner"] or None
+        if "managers" in body:
+            host.managers = list(body["managers"])
+        if "monitors" in body:
+            host.monitors = list(body["monitors"])
+
+        return web.json_response(host.access_dict())
+
+    # -------------------------------------------------------------------------
+    # User profile page
+    # -------------------------------------------------------------------------
+
+    async def profile_page(request):
+        """GET /profile — current user's settings and host access summary."""
+        current_user, _ = _require_auth_redirect(request)
+        pkg_dir = os.path.dirname(__file__)
+        templates_dir = config.get("templates_dir", os.path.join(pkg_dir, "templates"))
+        env = jinja2.Environment(loader=jinja2.FileSystemLoader(templates_dir))
+
+        # Build host access summary for this user.
+        # Merge live hosts with config-only hosts (not yet seen) so the profile
+        # reflects the config file immediately after a reload.
+        from . import config as config_mod
+        owned, managed, monitored = [], [], []
+        if current_user:
+            # Collect all known hostnames: live + configured
+            cfg_hostnames = set(config.get("hosts", {}).keys())
+            live_hostnames = set(hbdclass.Host.hosts.keys())
+            all_hostnames = sorted(cfg_hostnames | live_hostnames)
+
+            for hostname in all_hostnames:
+                live_host = hbdclass.Host.hosts.get(hostname)
+                if live_host is not None:
+                    # Use live object — it has apply_access already called
+                    is_own = live_host.is_owner(current_user.username)
+                    is_mgr = not is_own and live_host.is_manager(current_user.username)
+                    is_mon = not is_own and not is_mgr and live_host.is_monitor(current_user.username)
+                else:
+                    # Config-only host — read access directly from config
+                    access = config_mod.get_host_access(config, hostname)
+                    is_own = access["owner"] == current_user.username
+                    is_mgr = current_user.username in access["managers"]
+                    is_mon = current_user.username in access["monitors"]
+
+                if is_own:
+                    owned.append(hostname)
+                elif is_mgr:
+                    managed.append(hostname)
+                elif is_mon:
+                    monitored.append(hostname)
+
+
+        # Resolve notification channel configs for display
+        notif_channels = []
+        if current_user:
+            for ch_name in (current_user.notification_channels or []):
+                ch_cfg = config.get("notification_channels", {}).get(ch_name, {})
+                notif_channels.append({"name": ch_name, "type": ch_cfg.get("type", "")})
+
+        tmpl = env.get_template("profile.html")
+        body = tmpl.render(
+            title="Profile - Heartbeat",
+            header="My Profile",
+            current_user=current_user.to_dict() if current_user else None,
+            owned_hosts=owned,
+            managed_hosts=managed,
+            monitored_hosts=monitored,
+            notification_channels=notif_channels,
+            active_page="profile",
+        )
+        return web.Response(text=body, content_type="text/html")
+
+    # -------------------------------------------------------------------------
+    # About page
+    # -------------------------------------------------------------------------
+
+    async def about_page(request):
+        """GET /about — version, runtime, and project information."""
+        current_user, _ = _require_auth_redirect(request)
+        pkg_dir = os.path.dirname(__file__)
+        templates_dir = config.get("templates_dir", os.path.join(pkg_dir, "templates"))
+        env = jinja2.Environment(loader=jinja2.FileSystemLoader(templates_dir))
+        from hbd import __version__ as hbd_version
+
+        uptime_secs = int(time.time() - _start_epoch)
+        days, rem = divmod(uptime_secs, 86400)
+        hours, rem = divmod(rem, 3600)
+        mins, secs = divmod(rem, 60)
+        if days:
+            uptime_str = f"{days}d {hours}h {mins}m"
+        elif hours:
+            uptime_str = f"{hours}h {mins}m {secs}s"
+        else:
+            uptime_str = f"{mins}m {secs}s"
+
+        start_dt = datetime.datetime.fromtimestamp(_start_epoch)
+        start_time_str = start_dt.strftime("%Y-%m-%d %H:%M:%S")
+
+        tmpl = env.get_template("about.html")
+        body = tmpl.render(
+            title="About - Heartbeat",
+            header="About",
+            hbd_version=hbd_version,
+            python_version=f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro} ({platform.python_implementation()})",
+            server_hostname=socket.gethostname(),
+            start_epoch=int(_start_epoch),
+            start_time_str=start_time_str,
+            uptime_str=uptime_str,
+            host_count=len(hbdclass.Host.hosts),
+            current_user=current_user.to_dict() if current_user else None,
+            active_page="about",
+        )
+        return web.Response(text=body, content_type="text/html")
+
+    # -------------------------------------------------------------------------
+    # Settings page (admin only)
+    # -------------------------------------------------------------------------
+
+    async def settings_page(request):
+        """GET /settings — read-only view of the current server configuration."""
+        current_user, _ = _require_auth_redirect(request)
+        if current_user and not current_user.admin:
+            raise web.HTTPForbidden(reason="Admin access required")
+        pkg_dir = os.path.dirname(__file__)
+        templates_dir = config.get("templates_dir", os.path.join(pkg_dir, "templates"))
+        env = jinja2.Environment(loader=jinja2.FileSystemLoader(templates_dir))
+        tmpl = env.get_template("settings.html")
+        body = tmpl.render(
+            title="Settings - Heartbeat",
+            sections=settings_mod.get_settings_sections(config),
+            current_user=current_user.to_dict() if current_user else None,
+            active_page="settings",
         )
         return web.Response(text=body, content_type="text/html")
 
     app = web.Application()
     app.add_routes(
         [
-            web.get("/", index),
+            web.get("/", live),
+            web.get("/old", old_index),
+            # Auth
+            web.get("/login", login_page),
+            web.post("/login", login_page),
+            web.get("/logout", web_logout),
+            web.post("/api/0/auth/login", api_login),
+            web.post("/api/0/auth/logout", api_logout),
+            # Users
+            web.get("/api/0/users", api_users),
+            web.get("/api/0/users/me", api_user_self),
+            web.get("/api/0/users/{username}/avatar", api_user_avatar),
+            # Hosts
             web.get("/api/0/hosts", api_hosts),
             web.get("/api/0/messages", api_messages),
             web.get("/api/0/hosts/{hostname}/plugins", api_host_plugins),
             web.get("/api/0/hosts/{hostname}/plugins/{plugin_name}", api_host_plugin_detail),
             web.get("/api/0/hosts/{hostname}/alerts", api_host_alerts),
+            web.get("/api/0/hosts/{hostname}/access", api_host_access_get),
+            web.put("/api/0/hosts/{hostname}/access", api_host_access_put),
             web.get("/api/0/alerts", api_all_alerts),
             web.post("/api/0/alerts/acknowledge", api_acknowledge_alert),
             web.get("/c", cmd),
@@ -426,8 +906,12 @@ async def start(
             web.get("/live", live),
             web.get("/plugins", plugins_page),
             web.get("/alerts", alerts_page),
+            web.get("/about", about_page),
+            web.get("/profile", profile_page),
+            web.get("/settings", settings_page),
             web.get("/static/{path:.*}", static),
             web.get("/favicon.ico", favicon),
+            web.get("/ws", ws_mod.handler),
         ]
     )
 
@@ -436,8 +920,7 @@ async def start(
     site = web.TCPSite(runner, host, port)
     await site.start()
 
-    if verbose:
+    logger.info(f"HTTP server started on {host}:{port}")
-        print(f"HTTP server started on {host}:{port}")
 
     try:
         await asyncio.Future()

hbd/server/main.py

@@ -15,6 +15,7 @@ from . import hbdclass
 from . import ws as ws_mod
 from . import notify as notify_mod
 from . import data
+from . import users as users_mod
 
 logger = logging.getLogger(__name__)
 msg_to_websockets = ws_mod.broadcast
@@ -22,12 +23,13 @@ eventlog = notify_mod.eventlog
 
 # shared runtime collections and helpers
 
-def cleanup_function(config, hbdclass):
+def save_state(config, hbdclass):
-    """This function will be executed upon program exit."""
+    """Save current state to pickle file. Safe to call at any time."""
-    logger.info("Running cleanup function...")
     import pickle
+    import os
+    from . import users as users_mod
 
-    # Ensure all timer references are cleared before pickling
+    # Clear timer references before pickling (they can't be serialized)
     for hostname, host in list(hbdclass.Host.hosts.items()):
         for conn_type, conn in host.connections.items():
             if hasattr(conn, 'cancel_overdue_timer'):
@@ -40,13 +42,27 @@ def cleanup_function(config, hbdclass):
                 conn.timeout_duration = None
 
     pickfile = config.get("pickfile", "hbd.pickle")
+    tmpfile = pickfile + ".tmp"
 
-    pickf = open(pickfile, "wb")
+    try:
+        with open(tmpfile, "wb") as pickf:
             pick = pickle.Pickler(pickf)
             pick.dump(hbdclass.Host.hosts)
             pick.dump(data.msgs)
-    pickf.close()
+            pick.dump(users_mod.save_sessions())
+        os.replace(tmpfile, pickfile)
+    except Exception as e:
+        logger.error("Failed to save state: %s", e)
+        try:
+            os.unlink(tmpfile)
+        except Exception:
+            pass
 
+
+def cleanup_function(config, hbdclass):
+    """This function will be executed upon program exit."""
+    logger.info("Running cleanup function...")
+    save_state(config, hbdclass)
     logger.info("Cleanup complete.")
 
 
@@ -72,6 +88,19 @@ async def reload_configuration(config_obj, config_path, components):
         # Update notify module
         notify_mod.reload_config(new_config)
 
+        # Reload users
+        users_mod.load_users(new_config)
+
+        # Re-apply host attributes from updated config to all known hosts
+        from . import config as config_mod
+        dyndnshosts = config_mod.get_dyndnshosts(new_config)
+        watchhosts = config_mod.get_watchhosts(new_config)
+        for hostname, host in hbdclass.Host.hosts.items():
+            host.dyn = hostname in dyndnshosts
+            host.watched = hostname in watchhosts
+            access = config_mod.get_host_access(new_config, hostname)
+            host.apply_access(access["owner"], access["managers"], access["monitors"])
+
         # Reload threshold checker
         if 'threshold_checker' in components:
             components['threshold_checker'].reload(new_config)
@@ -103,6 +132,10 @@ async def reload_configuration(config_obj, config_path, components):
 
 
 async def _run_async(config, config_path=None):
+    from .config import ReloadableConfig
+    if not isinstance(config, ReloadableConfig):
+        config = ReloadableConfig(config, config_path)
+
     loop = asyncio.get_running_loop()
     shutdown_event = asyncio.Event()
     reload_event = asyncio.Event()
@@ -129,7 +162,7 @@ async def _run_async(config, config_path=None):
     from . import journal as journal_mod
     from . import threshold as threshold_mod
 
-    notify_mod.setup(config)
+    notify_mod.setup(config, loop=loop)
     
     # Initialize message journal
     msg_journal = journal_mod.get_journal(config)
@@ -160,31 +193,54 @@ async def _run_async(config, config_path=None):
             f"Warning: Could not reset IPV6_V6ONLY not supported or dual-stack is unavailable. Error: {e}"
         )
 
-    # 3. Bind to all interfaces (::) on a specific port
-
-    # UDP server endpoint (handler wired to handle_datagram with context)
     bind_addr = ("::", config.get("hb_port", 50003))
     sock.bind(bind_addr)
     logger.info("Starting UDP server on %s:%s", *bind_addr)
 
-    def udp_handler(msg, addr, transport):
+    # Try to enable kernel receive timestamps (Linux SO_TIMESTAMP).
+    # If supported, read datagrams via recvmsg() so RTT uses the kernel
+    # timestamp rather than the time.time() call after asyncio scheduling.
+    use_kernel_ts = udp.enable_kernel_timestamps(sock)
+    if use_kernel_ts:
+        logger.info("SO_TIMESTAMP enabled: using kernel receive timestamps for RTT")
+    else:
+        logger.info("SO_TIMESTAMP not available: using time.time() for RTT")
+
+    def udp_handler(msg, addr, transport, recv_ts=None):
         ctx = dict(
             config=config,
             hbdclass=hbdclass,
-            log=eventlog,
             msg_to_websockets=msg_to_websockets,
             msg_journal=msg_journal,
             threshold_checker=threshold_checker,
             DEBUG=config.get("debug", 0),
             verbose=config.get("verbose", False),
+            recv_ts=recv_ts,
         )
         udp.handle_datagram(msg, addr, transport, ctx)
 
+    if use_kernel_ts:
+        # recvmsg path: manage the socket ourselves with loop.add_reader()
+        sock.setblocking(False)
+        transport = udp.RecvmsgTransport(loop, sock)
+        reader = udp.make_recvmsg_reader(sock, udp_handler, transport)
+        loop.add_reader(sock.fileno(), reader)
+        protocol = None
+    else:
         transport, protocol = await loop.create_datagram_endpoint(
             lambda: udp.EchoServerProtocol(config=config, handler=udp_handler),
             sock=sock,
         )
 
+    # Restore connection timers for hosts loaded from pickle
+    restore_ctx = dict(
+        config=config,
+        hbdclass=hbdclass,
+        msg_to_websockets=msg_to_websockets,
+        threshold_checker=threshold_checker,
+    )
+    udp.restore_connection_timers(hbdclass, restore_ctx)
+
     # HTTP server (asyncio-based via aiohttp)
     try:
         http_task = asyncio.create_task(
@@ -217,45 +273,30 @@ async def _run_async(config, config_path=None):
     except Exception as e:
         logger.exception("dns worker failed to start: %s", e)
 
-    # Start the websocket servers as a background task
+    # Register WebSocket state — connections are now served through /ws on the HTTP port
-    if config.get("wss_port", None):
+    ws_task = None
-        ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    ws_mod.setup(
-        ssl_path = config.get("cert_path", "")
+        loop=loop,
-        wss_pem = ssl_path + config.get("wss_pem", "")
-        wss_key = ssl_path + config.get("wss_key", "")
-        try:
-            ssl_context.load_cert_chain(wss_pem, keyfile=wss_key)
-        except FileNotFoundError:
-            logger.error("error: missing SSL keys %s or %s", wss_pem, wss_key)
-            sys.exit(1)
-        logger.info(
-            "Starting secure WebSocket server on port %s with cert %s",
-            config.get("wss_port", None),
-            wss_pem,
-        )
-    else:
-        ssl_context = None
-
-    try:
-        ws_port = config.get("ws_port", 50005)
-        logger.info("Starting WebSocket server on port %s", ws_port)
-        ws_task = asyncio.create_task(
-            ws_mod.start(
-                host=config.get("hbd_host", ""),
-                ws_port=ws_port,
-                wss_port=config.get("wss_port", None),
-                ssl_context=ssl_context,
         get_hosts=lambda: [
             hbdclass.Host.hosts[h].stateinfo()
             for h in sorted(hbdclass.Host.hosts)
         ],
-#                get_msgs=lambda: msgs,
+        verbose=config.get("verbose", False),
-                config=config,
     )
-        )
+    logger.info("WebSocket handler registered on /ws (HTTP port %s)", config.get("hbd_port", 50004))
-        logger.info("WebSocket task started")
+
-    except Exception as e:
+    # Periodic autosave task
-        logger.exception("websocket server failed to start: %s", e)
+    autosave_interval = config.get("autosave_interval", 300)  # default: 5 minutes
+
+    async def autosave_task():
+        while True:
+            await asyncio.sleep(autosave_interval)
+            logger.debug("Autosaving state...")
+            save_state(config, hbdclass)
+            logger.debug("Autosave complete (%d hosts)", len(hbdclass.Host.hosts))
+
+    autosave = asyncio.create_task(autosave_task())
+    logger.info("Autosave task started (interval: %ds)", autosave_interval)
 
     # Main event loop - monitor shutdown and reload events
     try:
@@ -304,7 +345,7 @@ async def _run_async(config, config_path=None):
         except Exception as e:
             logger.warning("Error closing UDP transport: %s", e)
 
-        tasks_to_cancel = [http_task, ws_task]
+        tasks_to_cancel = [http_task, autosave]
         for task in tasks_to_cancel:
             if task:
                 try:
@@ -355,6 +396,13 @@ async def _run_async(config, config_path=None):
         except Exception as e:
             logger.warning("Error stopping DNS worker: %s", e)
 
+        # Save state (hosts + sessions) on clean shutdown
+        try:
+            save_state(config, hbdclass)
+            logger.info("State saved on shutdown")
+        except Exception as e:
+            logger.warning("Error saving state on shutdown: %s", e)
+
         logger.info("All tasks cancelled")
 
 
@@ -363,6 +411,7 @@ def load_pickled_hosts(config, hbdclass):
     import os
     import pickle
     from . import config as config_mod
+    from . import users as users_mod
 
     pickfile = config.get("pickfile", "hbd.pickle")
     dyndnshosts = config_mod.get_dyndnshosts(config)
@@ -376,6 +425,10 @@ def load_pickled_hosts(config, hbdclass):
         try:
             hbdclass.Host.hosts = pick.load()
             data.msgs = pick.load()
+            try:
+                users_mod.load_sessions(pick.load())
+            except Exception:
+                pass  # older pickle without sessions — fine
             pickf.close()
         except Exception as e:
             logger.exception("load pickled failed: %s", e)
@@ -385,6 +438,10 @@ def load_pickled_hosts(config, hbdclass):
             hbdclass.Host.hosts[h].dyn = h in dyndnshosts
             hbdclass.Host.hosts[h].watched = h in watchhosts
             hbdclass.Host.hosts[h].fixup()
+            access = config_mod.get_host_access(config, h)
+            hbdclass.Host.hosts[h].apply_access(
+                access["owner"], access["managers"], access["monitors"]
+            )
         for h in drophosts:
             if h in hbdclass.Host.hosts:
                 del hbdclass.Host.hosts[h]
@@ -406,12 +463,26 @@ def run(config, config_path=None):
     """
     import os
 
-    logging.basicConfig(
+    log_level = logging.WARNING
-        level=logging.DEBUG if config.get("debug", 0) > 0 else logging.INFO
+    if config.get("verbose", False):
-    )
+        log_level = logging.INFO
+    if config.get("debug", 0) > 0:
+        log_level = logging.DEBUG
+    logging.basicConfig(level=log_level)
     load_pickled_hosts(config, hbdclass)
 
     notify_mod.initlog(logfile=config.get("logfile", "messages.log"))
+    users_mod.load_users(config)
+
+    # Write pidfile
+    pidfile = config.get("pidfile", "")
+    if pidfile:
+        try:
+            with open(pidfile, "w") as f:
+                f.write(str(os.getpid()))
+        except Exception as e:
+            logger.warning("Failed to write pidfile %s: %s", pidfile, e)
+
     eventlog(None, "INFO", f"hbd version {__version__} starting up")
     
     if config_path:
@@ -434,6 +505,12 @@ def run(config, config_path=None):
         logger.info("hbd shutdown complete")
         eventlog(None, "INFO", f"hbd version {__version__} shutdown")
         notify_mod.closelog()
+        # Remove pidfile
+        if pidfile:
+            try:
+                os.unlink(pidfile)
+            except Exception:
+                pass
         # Explicitly close the loop
         try:
             # Cancel all remaining tasks

hbd/server/notify.py

@@ -1,37 +1,100 @@
-"""Notification helpers: email, pushover, mattermost, signal and dispatcher."""
+"""Notification helpers: email, pushover, matrix, mattermost, signal, sms and dispatcher.
 
+Channel types supported:
+  pushover      - Pushover app notifications
+  email         - SMTP email
+  matrix        - Matrix (via matrix-nio)
+  mattermost    - Mattermost webhook
+  signal        - Signal via signal-cli subprocess
+  sms_voipms    - SMS via voip.ms REST API
+
+Each channel can specify ``min_level: WARNING|CRITICAL`` (default: WARNING).
+
+Notifications are dispatched to the owner + managers of the host, each via
+their own ``notification_channels`` list.  When no users are configured the
+server runs silently (no notifications sent).
+"""
+
+import asyncio
 import logging
-from typing import Optional
-import http.client
-import urllib.parse
-import subprocess
 import smtplib
+import subprocess
 import time
 import sys
+from dataclasses import dataclass, field
+from typing import Optional
+
 from . import data
 from . import ws as ws_mod
-from . import main as main_mod
 
-DEFAULT_PUSHPROVIDERS = ["all", "pushover", "mattermost", "signal"]
-msg_to_websockets = ws_mod.broadcast
-
-# module-level configuration set via setup()
-_config = {}
 logger = logging.getLogger(__name__)
 
+msg_to_websockets = ws_mod.broadcast
+
+# Module-level state set via setup()
+_config: dict = {}
+
+# Tracks which channels fired a WARNING/CRITICAL per host.
+# {host_name: set of channel_names}  — used to route RECOVER to the same channels.
+_alerted_channels: dict = {}
+
 logf = None
 
+
+# ---------------------------------------------------------------------------
+# Level ordering
+# ---------------------------------------------------------------------------
+
+_LEVEL_ORDER = {"RECOVER": 0, "INFO": 0, "WARNING": 1, "CRITICAL": 2}
+
+def _level_value(level: str) -> int:
+    return _LEVEL_ORDER.get(level.upper(), 0)
+
+
+# ---------------------------------------------------------------------------
+# Notification dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Notification:
+    """Structured notification payload."""
+    title: str          # e.g. "[CRITICAL] webserver01"
+    body: str           # detail message
+    level: str          # RECOVER | WARNING | CRITICAL | INFO
+    url: str = ""       # link to plugin metrics page
+
+
+# ---------------------------------------------------------------------------
+# Module setup
+# ---------------------------------------------------------------------------
+
+def setup(cfg: dict, loop: Optional[asyncio.AbstractEventLoop] = None):
+    """Initialize notifier from configuration dict."""
+    global _config
+    _config = dict(cfg)
+
+
+def reload_config(cfg: dict):
+    """Reload notification configuration on SIGHUP."""
+    global _config
+    _config = dict(cfg)
+    logger.info("Notification configuration reloaded")
+
+
+# ---------------------------------------------------------------------------
+# Event log (websocket + file + in-memory)
+# ---------------------------------------------------------------------------
+
 def initlog(logfile):
     global logf
     try:
         logf = open(logfile, "a+")
     except Exception as e:
-        import sys
-
         print("cannot open logfile %s, using STDERR: %s" % (logfile, e))
         logf = sys.stderr
     return logf
 
+
 def closelog():
     global logf
     if logf and logf != sys.stderr:
@@ -40,6 +103,7 @@ def closelog():
         except Exception:
             pass
 
+
 def eventlog(host, lvl, m, service=None):
     ts = time.time()
     s = f"{time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(ts))} {lvl} "
@@ -56,91 +120,29 @@ def eventlog(host, lvl, m, service=None):
             logger.warning("failed to write to logfile: %s", e)
     msg_to_websockets("message", s)
 
-def setup(cfg: dict):
-    """Initialize notifier defaults from a configuration dict."""
-    global _config
-    _config = dict(cfg)
 
+# ---------------------------------------------------------------------------
+# Low-level channel drivers
+# ---------------------------------------------------------------------------
 
-def reload_config(cfg: dict):
+def _send_pushover(channel_cfg: dict, notif: Notification) -> bool:
-    """Reload notification configuration.
+    import http.client
-    
+    import urllib.parse
-    This function updates the module-level notification configuration
+    token = channel_cfg.get("token", "")
-    during runtime config reloads.
+    user = channel_cfg.get("user", "")
-    
+    if not token or not user:
-    Args:
+        logger.warning("pushover: missing token or user")
-        cfg: New configuration dictionary
-    """
-    global _config
-    _config = dict(cfg)
-    logger.info("Notification configuration reloaded")
-
-
-def send_email(toaddrs, smtpserver, sender, subject, body, debug=0):
-    """Send a plain email via SMTP. Returns True on success."""
-    try:
-        smtpport = _config.get("smtpport", 587)
-        server = smtplib.SMTP(smtpserver, smtpport)
-        if debug > 0:
-            server.set_debuglevel(1)
-        if smtpport == 587:
-            server.starttls()
-            server.ehlo()
-            smtpuser = _config.get("smtpuser", None)
-            smtppassword = _config.get("smtppassword", None)
-            if smtpuser and smtppassword:
-                server.login(smtpuser, smtppassword)
-        server.sendmail(sender, toaddrs, body)
-    except Exception as e:
-        logger.warning("email send failed: %s", e)
-        try:
-            server.quit()
-        except Exception:
-            pass
         return False
-    try:
+    params: dict = {"token": token, "user": user, "title": notif.title, "message": notif.body}
-        server.quit()
+    if notif.url:
-    except Exception:
+        params["url"] = notif.url
-        pass
+        params["url_title"] = "Plugin metrics"
-    return True
-
-
-def email(subject: str, msg: str, debug: int = 0) -> bool:
-    """Convenience wrapper exposed to the rest of the application.
-
-    Uses module-level configuration to supply recipient list, smtp server
-    and sender address.
-    """
-    toaddrs = _config.get("toemail")
-    fromemail = _config.get("fromemail")
-    smtpserver = _config.get("smtpserver")
-    if not toaddrs or not fromemail or not smtpserver:
-        logger.warning(
-            "email config incomplete: toemail=%s, fromemail=%s, smtpserver=%s",
-            toaddrs,
-            fromemail,
-            smtpserver,
-        )
-        return False
-    date = time.strftime("%a, %d %b %Y %H:%M:%S %z", time.localtime())
-    body = "To: %s\nFrom: %s\nSubject: %s\nDate: %s\n\n%s" % (
-        toaddrs[0] if toaddrs else "",
-        fromemail,
-        subject,
-        date,
-        msg,
-    )
-    return send_email(toaddrs, smtpserver, fromemail, subject, body, debug=debug)
-
-
-def pushover(token: str, user: str, msg: str, debug: int = 0) -> bool:
-    """Send message via Pushover API."""
     conn = http.client.HTTPSConnection("api.pushover.net:443")
     try:
         conn.request(
             "POST",
             "/1/messages.json",
-            urllib.parse.urlencode({"token": token, "user": user, "message": msg}),
+            urllib.parse.urlencode(params),
             {"Content-type": "application/x-www-form-urlencoded"},
         )
         r = conn.getresponse()
@@ -151,176 +153,331 @@ def pushover(token: str, user: str, msg: str, debug: int = 0) -> bool:
         return False
 
 
-def pushmattermost(
+def _send_email(channel_cfg: dict, notif: Notification) -> bool:
-    host: str,
+    recipients = channel_cfg.get("recipients", [])
-    token: str,
+    sender = channel_cfg.get("sender", "")
-    channel: str,
+    smtp_server = channel_cfg.get("smtp_server", "")
-    msg: str,
+    smtp_port = channel_cfg.get("smtp_port", 587)
-    username: str = "hbd",
+    smtp_user = channel_cfg.get("smtp_user")
-    icon: Optional[str] = None,
+    smtp_password = channel_cfg.get("smtp_password")
-    debug: int = 0,
-) -> bool:
-    """Send a message to Mattermost via simple webhook driver if available.
 
-    This helper tries to import mattermostdriver.Driver and uses webhooks if present.
+    if not recipients or not sender or not smtp_server:
-    If the import fails it returns False.
+        logger.warning("email: missing recipients, sender, or smtp_server")
-    """
+        return False
+
+    date = time.strftime("%a, %d %b %Y %H:%M:%S %z", time.localtime())
+    body_text = notif.body
+    if notif.url:
+        body_text += f"\n\n{notif.url}"
+    raw = "To: %s\nFrom: %s\nSubject: %s\nDate: %s\n\n%s" % (
+        recipients[0] if isinstance(recipients, list) else recipients,
+        sender,
+        notif.title,
+        date,
+        body_text,
+    )
+    try:
+        server = smtplib.SMTP(smtp_server, smtp_port)
+        if smtp_port == 587:
+            server.starttls()
+            server.ehlo()
+            if smtp_user and smtp_password:
+                server.login(smtp_user, smtp_password)
+        server.sendmail(sender, recipients, raw)
+        server.quit()
+        return True
+    except Exception as e:
+        logger.warning("email send failed: %s", e)
+        try:
+            server.quit()
+        except Exception:
+            pass
+        return False
+
+
+def _send_mattermost(channel_cfg: dict, notif: Notification) -> bool:
     try:
         from mattermostdriver import Driver
-    except Exception:
+    except ImportError:
+        logger.error("mattermostdriver not installed")
         return False
+    host = channel_cfg.get("host", "")
+    token = channel_cfg.get("token", "")
+    channel = channel_cfg.get("channel", "")
+    if not host or not token or not channel:
+        logger.warning("mattermost: missing host, token, or channel")
+        return False
+    text = f"**{notif.title}**\n{notif.body}"
+    if notif.url:
+        text += f"\n[Plugin metrics]({notif.url})"
     ses = {"url": host, "scheme": "http", "basepath": "/api/v4", "port": 8065}
     mm = Driver(ses)
-    payload = {"text": msg, "channel": channel, "username": username}
+    payload: dict = {"text": text, "channel": channel, "username": channel_cfg.get("username", "hbd")}
+    icon = channel_cfg.get("icon")
     if icon:
         payload["icon_url"] = icon
     try:
         rc = mm.webhooks.call_webhook(token, payload)
-        logger.debug("mattermost rc: %s", rc)
         return bool(rc is None or rc == "")
     except Exception as e:
         logger.error("mattermost error: %s", e)
         return False
 
 
-def pushsignal(
+def _send_signal(channel_cfg: dict, notif: Notification) -> bool:
-    signal_cli_bin: str, user: str, recipient: str, msg: str, debug: int = 0
+    cli = channel_cfg.get("cli_path", "/usr/local/bin/signal-cli")
-) -> bool:
+    user = channel_cfg.get("user", "")
-    """Send a message via signal-cli (requires local installation).
+    recipient = channel_cfg.get("recipient", "")
-
+    if not user or not recipient:
-    Uses subprocess to call signal-cli. Returns True if the command succeeded.
+        logger.warning("signal: missing user or recipient")
-    """
+        return False
-    CLI = [signal_cli_bin, "-u", user, "send", "-m", msg, recipient]
+    msg = f"{notif.title}\n{notif.body}"
-    logger.debug("signal cli: %s", CLI)
+    if notif.url:
-    try:
+        msg += f"\n{notif.url}"
-        res = subprocess.run(CLI, capture_output=True)
+    try:
-        if res.returncode != 0:
+        res = subprocess.run([cli, "-u", user, "send", "-m", msg, recipient], capture_output=True)
-            logger.error("signal failed: %s".res.stderr.decode())
+        if res.returncode != 0:
+            logger.error("signal failed: %s", res.stderr.decode())
             return False
-        logger.debug("signal sent: %s", res.stdout.decode())
         return True
     except Exception as e:
         logger.exception("signal exception: %s", e)
         return False
 
 
-def _dispatch_to_channel(channel_name: str, channel_config: dict, msg: str, debug: int = 0) -> bool:
+async def _send_sms_voipms_async(channel_cfg: dict, notif: Notification) -> bool:
-    """Dispatch a message to a specific notification channel.
+    """Send SMS via voip.ms REST API using multipart form-data POST."""
+    import json
+    import aiohttp
 
-    Args:
+    api_user = channel_cfg.get("api_user", "")
-        channel_name: Name of the channel (for logging)
+    api_password = channel_cfg.get("api_password", "")
-        channel_config: Channel configuration dictionary with 'type' and type-specific fields
+    did = channel_cfg.get("did", "")
-        msg: Message to send
+    dst = channel_cfg.get("dst", "")
-        debug: Debug level
+    if not api_user or not api_password or not did or not dst:
-        
+        logger.warning("sms_voipms: missing api_user, api_password, did, or dst")
-    Returns:
-        True if notification sent successfully, False otherwise
-    """
-    channel_type = channel_config.get("type")
-    
-    if channel_type == "pushover":
-        return pushover(
-            channel_config.get("token", ""),
-            channel_config.get("user", ""),
-            msg,
-            debug=debug
-        )
-    
-    elif channel_type == "email":
-        # Build email from channel config
-        recipients = channel_config.get("recipients", [])
-        sender = channel_config.get("sender", "")
-        smtp_server = channel_config.get("smtp_server", "")
-        smtp_port = channel_config.get("smtp_port", 587)
-        smtp_user = channel_config.get("smtp_user")
-        smtp_password = channel_config.get("smtp_password")
-        
-        if not recipients or not sender or not smtp_server:
-            logger.warning(
-                "Email channel '%s' missing required fields: recipients=%s, sender=%s, smtp_server=%s",
-                channel_name, recipients, sender, smtp_server
-            )
         return False
 
-        # Temporarily update _config for email() function
+    # SMS body: title + body, truncated to 160 chars
-        old_config = dict(_config)
+    text = f"{notif.title}: {notif.body}"
-        _config["toemail"] = recipients
+    if len(text) > 160:
-        _config["fromemail"] = sender
+        text = text[:157] + "..."
-        _config["smtpserver"] = smtp_server
-        _config["smtpport"] = smtp_port
-        if smtp_user:
-            _config["smtpuser"] = smtp_user
-        if smtp_password:
-            _config["smtppassword"] = smtp_password
 
-        result = email("Heartbeat notification", msg, debug=debug)
+    form_data = {
+        "api_username": api_user,
+        "api_password": api_password,
+        "method": "sendSMS",
+        "did": did,
+        "dst": dst,
+        "message": text,
+    }
 
-        # Restore config
+    try:
-        _config.clear()
+        async with aiohttp.ClientSession() as session:
-        _config.update(old_config)
+            with aiohttp.MultipartWriter("form-data") as mp:
-        
+                for key, value in form_data.items():
-        return result
+                    part = mp.append(value)
-    
+                    part.set_content_disposition("form-data", name=key)
-    elif channel_type == "signal":
+            async with session.post("https://voip.ms/api/v1/rest.php", data=mp) as resp:
-        return pushsignal(
+                body = await resp.text()
-            channel_config.get("cli_path", "/usr/local/bin/signal-cli"),
+                if resp.status != 200:
-            channel_config.get("user", ""),
+                    logger.error("sms_voipms HTTP %s: %s", resp.status, body)
-            channel_config.get("recipient", ""),
+                    return False
-            msg,
+                result = json.loads(body)
-            debug=debug
+                if result.get("status") == "success":
-        )
+                    return True
-    
+                logger.error("sms_voipms error: %s", result.get("status"))
-    elif channel_type == "mattermost":
+                return False
-        return pushmattermost(
+    except Exception as e:
-            channel_config.get("host", ""),
+        logger.error("sms_voipms exception: %s", e)
-            channel_config.get("token", ""),
-            channel_config.get("channel", ""),
-            msg,
-            username=channel_config.get("username", "hbd"),
-            icon=channel_config.get("icon"),
-            debug=debug
-        )
-    
-    else:
-        logger.warning("Unknown channel type '%s' for channel '%s'", channel_type, channel_name)
         return False
 
 
-def pushmsg_for_host(hostname: str, msg: str, debug: int = 0) -> dict:
-    """Send notification for a specific host using its configured channels.
 
-    This function looks up the host's notification channels from the config
-    and sends the message to those channels.
 
-    Args:
+async def _send_matrix_async(channel_cfg: dict, notif: Notification) -> bool:
-        hostname: Name of the host to send notification for
+    """Send a Matrix message using matrix-nio."""
-        msg: Message to send
+    try:
-        debug: Debug level
+        from nio import AsyncClient, RoomMessageText  # noqa: F401
+    except ImportError:
+        logger.error("matrix-nio not installed; pip install matrix-nio")
+        return False
 
-    Returns:
+    from nio import AsyncClient
-        Dictionary of results per channel: {"channel_name": True/False}
+    homeserver = channel_cfg.get("homeserver", "")
+    access_token = channel_cfg.get("access_token", "")
+    room_id = channel_cfg.get("room_id", "")
+    if not homeserver or not access_token or not room_id:
+        logger.warning("matrix: missing homeserver, access_token, or room_id")
+        return False
+
+    text = f"{notif.title}\n{notif.body}"
+    if notif.url:
+        text += f"\n{notif.url}"
+    html = f"<strong>{notif.title}</strong><br>{notif.body}"
+    if notif.url:
+        html += f'<br><a href="{notif.url}">Plugin metrics</a>'
+
+    client = AsyncClient(homeserver)
+    client.access_token = access_token
+    try:
+        from nio import RoomSendResponse
+        content = {
+            "msgtype": "m.text",
+            "body": text,
+            "format": "org.matrix.custom.html",
+            "formatted_body": html,
+        }
+        resp = await client.room_send(room_id, "m.room.message", content)
+        if hasattr(resp, "event_id"):
+            return True
+        logger.error("matrix send failed: %s", resp)
+        return False
+    except Exception as e:
+        logger.error("matrix exception: %s", e)
+        return False
+    finally:
+        await client.close()
+
+
+# ---------------------------------------------------------------------------
+# Channel dispatcher  (all async — sync drivers run in a thread executor)
+# ---------------------------------------------------------------------------
+
+# Sync drivers kept for `hbd notify` CLI usage (asyncio.run wraps them there).
+_DRIVERS = {
+    "pushover": _send_pushover,
+    "email": _send_email,
+    "mattermost": _send_mattermost,
+    "signal": _send_signal,
+}
+
+_TIMEOUT = 15  # seconds per channel send
+
+
+async def _dispatch_to_channel(channel_name: str, channel_cfg: dict, notif: Notification) -> bool:
+    """Send *notif* to a single named channel, honouring min_level."""
+    level = notif.level.upper()
+    if level != "RECOVER":
+        min_level = channel_cfg.get("min_level", "WARNING").upper()
+        if _level_value(level) < _level_value(min_level):
+            logger.debug(
+                "channel '%s': skipping level %s (min_level=%s)", channel_name, level, min_level
+            )
+            return True  # filtered intentionally
+
+    ch_type = channel_cfg.get("type", "")
+    try:
+        if ch_type == "matrix":
+            return await asyncio.wait_for(_send_matrix_async(channel_cfg, notif), timeout=_TIMEOUT)
+        if ch_type == "sms_voipms":
+            return await asyncio.wait_for(_send_sms_voipms_async(channel_cfg, notif), timeout=_TIMEOUT)
+        sync_driver = _DRIVERS.get(ch_type)
+        if sync_driver is None:
+            logger.warning("unknown channel type '%s' for channel '%s'", ch_type, channel_name)
+            return False
+        return await asyncio.wait_for(
+            asyncio.to_thread(sync_driver, channel_cfg, notif), timeout=_TIMEOUT
+        )
+    except asyncio.TimeoutError:
+        logger.error("channel '%s' timed out after %ds", channel_name, _TIMEOUT)
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Central dispatch function
+# ---------------------------------------------------------------------------
+
+def _build_url(host_name: str) -> str:
+    base_url = _config.get("base_url", "").rstrip("/")
+    if not base_url:
+        return ""
+    return f"{base_url}/plugins#{host_name}"
+
+
+async def send_notification(host_name: str, notif: Notification) -> dict:
+    """Dispatch *notif* to all managers/owner of *host_name*.
+
+    Looks up the host's owner + managers, resolves each user's
+    notification_channels, and dispatches.  Silently does nothing if
+    no users are configured.
+
+    Returns a dict of {channel_name: bool} results.
     """
-    from . import config as config_mod
+    from . import users as users_mod
+    from . import hbdclass
 
-    # Get notification channels for this host
+    if not users_mod.users_enabled():
-    channels = config_mod.get_notification_channels_config(_config, hostname)
-    
-    if not channels:
-        logger.warning("No notification channels configured for host '%s'", hostname)
         return {}
 
-    # Dispatch to each channel
+    # Collect recipient usernames: owner + managers
-    results = {}
+    host = hbdclass.Host.hosts.get(host_name)
-    for channel_name, channel_config in channels:
+    if host is None:
+        logger.debug("send_notification: host '%s' not found", host_name)
+        return {}
+
+    recipients: set[str] = set()
+    owner = getattr(host, "owner", None)
+    if owner:
+        recipients.add(owner)
+    for m in getattr(host, "managers", []):
+        recipients.add(m)
+
+    if not recipients:
+        logger.debug("send_notification: no owner/managers for '%s'", host_name)
+        return {}
+
+    # Fill url if not already set
+    if not notif.url:
+        notif.url = _build_url(host_name)
+
+    global_channels: dict = _config.get("notification_channels", {})
+    results: dict = {}
+    level = notif.level.upper()
+    is_alert = level in ("WARNING", "CRITICAL")
+    is_recover = level in ("RECOVER",)
+
+    # For RECOVER: send to every channel that previously fired an alert for this host,
+    # regardless of that channel's min_level.
+    if is_recover and host_name in _alerted_channels:
+        for channel_name in list(_alerted_channels[host_name]):
+            channel_cfg = global_channels.get(channel_name)
+            if not channel_cfg:
+                continue
             try:
-            success = _dispatch_to_channel(channel_name, channel_config, msg, debug=debug)
+                ok = await _dispatch_to_channel(channel_name, channel_cfg, notif)
-            results[channel_name] = success
+                results[channel_name] = ok
-            if success:
+                if ok:
-                logger.info("Notification sent to channel '%s': %s", channel_name, msg)
+                    logger.info("recover sent to channel '%s': %s", channel_name, notif.title)
-            else:
-                logger.warning("Failed to send notification to channel '%s'", channel_name)
             except Exception as e:
-            logger.error("Error sending to channel '%s': %s", channel_name, e)
+                logger.error("error sending recover to channel '%s': %s", channel_name, e)
+        del _alerted_channels[host_name]
+        return results
+
+    for username in recipients:
+        user = users_mod.get_user(username)
+        if user is None:
+            logger.debug("send_notification: user '%s' not found", username)
+            continue
+        for channel_name in user.notification_channels:
+            if channel_name in results:
+                continue
+            channel_cfg = global_channels.get(channel_name)
+            if not channel_cfg:
+                logger.warning("channel '%s' not defined in notification_channels", channel_name)
+                results[channel_name] = False
+                continue
+            try:
+                ok = await _dispatch_to_channel(channel_name, channel_cfg, notif)
+                results[channel_name] = ok
+                if ok:
+                    logger.info("notification sent to channel '%s': %s", channel_name, notif.title)
+                    if is_alert:
+                        _alerted_channels.setdefault(host_name, set()).add(channel_name)
+                else:
+                    logger.warning("failed to send notification to channel '%s'", channel_name)
+            except Exception as e:
+                logger.error("error sending to channel '%s': %s", channel_name, e)
                 results[channel_name] = False
 
     return results

hbd/server/settings.py

@@ -0,0 +1,328 @@
+"""Settings descriptor: maps config keys to display metadata.
+
+``get_settings_sections(config)`` returns an ordered list of sections, each
+containing a list of field descriptors.  The template iterates this structure
+generically, so adding editability later is a matter of:
+
+  1. Setting ``"editable": True`` on a field.
+  2. Adding the matching ``<input>``/``<select>`` in the template
+     (guided by ``"type"``).
+  3. Wiring a POST handler in http.py.
+
+Field descriptor keys
+---------------------
+key         str   Config key (for future form POST matching)
+label       str   Human-readable label
+description str   One-line help text shown below the value
+value       any   Sanitized display value (secrets replaced with "•••")
+type        str   One of: text | number | port | boolean | path | duration |
+                  list | secret | size | select
+editable    bool  Reserved for future use — currently always False
+sensitive   bool  True when the raw value must never be shown
+"""
+
+# Credential field names that should always be masked.
+_SECRET_KEYS = frozenset({
+    "password", "token", "user_key", "api_key", "secret",
+    "smtp_password", "smtp_user",
+})
+
+_CHANNEL_TYPE_LABELS = {
+    "pushover":   "Pushover",
+    "email":      "E-mail",
+    "signal":     "Signal",
+    "mattermost": "Mattermost",
+}
+
+
+def _mask(value):
+    """Return a masked placeholder for sensitive values."""
+    if not value:
+        return ""
+    return "•••"
+
+
+def _fmt_size(n):
+    """Format a byte count as a human-readable string."""
+    try:
+        n = int(n)
+    except (TypeError, ValueError):
+        return str(n)
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024:
+            return f"{n} {unit}"
+        n //= 1024
+    return f"{n} TB"
+
+
+def _fmt_duration(seconds):
+    """Format seconds into a human-readable duration string."""
+    try:
+        s = int(seconds)
+    except (TypeError, ValueError):
+        return str(seconds)
+    if s < 60:
+        return f"{s}s"
+    if s < 3600:
+        m, sec = divmod(s, 60)
+        return f"{m}m {sec}s" if sec else f"{m}m"
+    h, rem = divmod(s, 3600)
+    m = rem // 60
+    return f"{h}h {m}m" if m else f"{h}h"
+
+
+def _sanitize_channel(name, cfg):
+    """Return a sanitized copy of a notification channel config."""
+    result = {}
+    for k, v in cfg.items():
+        if k in _SECRET_KEYS:
+            result[k] = _mask(v)
+        elif isinstance(v, list):
+            result[k] = v
+        else:
+            result[k] = v
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def get_settings_sections(config: dict) -> list:
+    """Return ordered list of setting sections for the settings page.
+
+    Each section:
+        {
+            "title": str,
+            "description": str,
+            "fields": [ field_descriptor, ... ]
+        }
+
+    Each field_descriptor:
+        {
+            "key":         str,
+            "label":       str,
+            "description": str,
+            "value":       display_value,
+            "raw":         raw_config_value,   # None for sensitive
+            "type":        str,
+            "editable":    bool,
+            "sensitive":   bool,
+        }
+    """
+    def field(key, label, ftype, description="", editable=False, sensitive=False):
+        raw = config.get(key)
+        if sensitive:
+            display = _mask(raw)
+            raw_out = None
+        elif ftype == "size":
+            display = _fmt_size(raw)
+            raw_out = raw
+        elif ftype == "duration":
+            display = _fmt_duration(raw)
+            raw_out = raw
+        elif ftype == "boolean":
+            display = bool(raw)
+            raw_out = raw
+        elif ftype == "list":
+            val = raw or []
+            display = list(val) if not isinstance(val, list) else val
+            raw_out = display
+        else:
+            display = raw if raw is not None else ""
+            raw_out = raw
+        return {
+            "key": key,
+            "label": label,
+            "description": description,
+            "value": display,
+            "raw": raw_out,
+            "type": ftype,
+            "editable": editable,
+            "sensitive": sensitive,
+        }
+
+    # ---- Notification channels (complex, built separately) ----------------
+    notif_channels = []
+    for ch_name, ch_cfg in (config.get("notification_channels") or {}).items():
+        if not isinstance(ch_cfg, dict):
+            continue
+        ch_type = ch_cfg.get("type", "")
+        fields = []
+        for k, v in ch_cfg.items():
+            if k == "type":
+                continue
+            sensitive = k in _SECRET_KEYS
+            fields.append({
+                "key": k,
+                "label": k.replace("_", " ").title(),
+                "value": _mask(v) if sensitive else (
+                    ", ".join(v) if isinstance(v, list) else str(v)
+                ),
+                "sensitive": sensitive,
+            })
+        notif_channels.append({
+            "name": ch_name,
+            "type": ch_type,
+            "type_label": _CHANNEL_TYPE_LABELS.get(ch_type, ch_type.title()),
+            "fields": fields,
+        })
+
+    # ---- Users (show metadata only, never password hashes) ----------------
+    users_list = []
+    for username, attrs in (config.get("users") or {}).items():
+        if not isinstance(attrs, dict):
+            continue
+        users_list.append({
+            "username": username,
+            "full_name": attrs.get("full_name", ""),
+            "admin": bool(attrs.get("admin", False)),
+            "avatar": attrs.get("avatar", ""),
+            "notification_channels": attrs.get("notification_channels", []),
+        })
+
+    # ---- Hosts summary ----------------------------------------------------
+    hosts_list = []
+    for hname, hcfg in (config.get("hosts") or {}).items():
+        if not isinstance(hcfg, dict):
+            continue
+        hosts_list.append({
+            "name": hname,
+            "watch": bool(hcfg.get("watch", False)),
+            "dyndns": bool(hcfg.get("dyndns", False)),
+            "owner": hcfg.get("owner", ""),
+            "managers": hcfg.get("managers", []),
+            "monitors": hcfg.get("monitors", []),
+            "threshold_config": hcfg.get("threshold_config", ""),
+            "notification_channels": hcfg.get("notification_channels", []),
+        })
+
+    return [
+        {
+            "id": "network",
+            "title": "Network",
+            "description": "Ports and bind addresses for all server sockets.",
+            "fields": [
+                field("hb_port",  "Heartbeat UDP port",  "port",
+                      "UDP port the server listens on for heartbeat datagrams."),
+                field("hbd_host", "HTTP bind address",   "text",
+                      "Interface to bind the HTTP server to. Empty = all interfaces."),
+                field("hbd_port", "HTTP API port",       "port",
+                      "TCP port for the HTTP API and web UI."),
+                field("ws_port",  "WebSocket port",      "port",
+                      "TCP port for the plain WebSocket server."),
+                field("wss_port", "Secure WebSocket port", "port",
+                      "TCP port for WSS (TLS WebSocket). Leave empty to disable."),
+            ],
+        },
+        {
+            "id": "tls",
+            "title": "TLS / WebSocket Security",
+            "description": "Certificate paths used when wss_port is set.",
+            "fields": [
+                field("cert_path", "Certificate directory", "path",
+                      "Directory containing the TLS certificate and key files."),
+                field("wss_pem",   "Certificate file",     "text",
+                      "Filename of the TLS certificate chain (PEM format)."),
+                field("wss_key",   "Key file",             "text",
+                      "Filename of the TLS private key (PEM format)."),
+            ],
+        },
+        {
+            "id": "monitoring",
+            "title": "Monitoring",
+            "description": "Heartbeat timing and alert re-notification behaviour.",
+            "fields": [
+                field("interval",  "Heartbeat interval", "duration",
+                      "Expected time between heartbeat messages from each client."),
+                field("grace",     "Grace multiplier",   "number",
+                      "A host is marked overdue after interval × grace seconds of silence."),
+                field("threshold_renotify_interval", "Re-notify interval", "duration",
+                      "How often to re-send notifications for ongoing threshold alerts."),
+                field("autosave_interval", "Autosave interval", "duration",
+                      "How often the server saves its state to disk."),
+            ],
+        },
+        {
+            "id": "persistence",
+            "title": "Persistence & Logging",
+            "description": "State file and event log settings.",
+            "fields": [
+                field("pickfile", "State file",   "path",
+                      "Path to the pickle file used to persist host state across restarts."),
+                field("logfile",  "Event log",    "path",
+                      "Path to the event log file."),
+            ],
+        },
+        {
+            "id": "journal",
+            "title": "Message Journal",
+            "description": "All received heartbeat and plugin messages are journalled here.",
+            "fields": [
+                field("journal_enabled",     "Enabled",          "boolean",
+                      "Turn journalling on or off."),
+                field("journal_dir",         "Journal directory","path",
+                      "Directory where journal files are written."),
+                field("journal_file",        "Journal filename", "text",
+                      "Base filename for the journal (rotated copies get a numeric suffix)."),
+                field("journal_max_size",    "Max file size",    "size",
+                      "Rotate the journal when it exceeds this size."),
+                field("journal_max_backups", "Backup count",     "number",
+                      "Number of rotated journal files to keep."),
+            ],
+        },
+        {
+            "id": "dns",
+            "title": "Dynamic DNS",
+            "description": "nsupdate-based DNS registration for dynamic hosts.",
+            "fields": [
+                field("nsupdate_bin", "nsupdate binary", "path",
+                      "Full path to the nsupdate executable."),
+                field("dyndomains",   "Dynamic domains", "list",
+                      "DNS zones managed by nsupdate for dynamic hosts."),
+                field("drophosts",    "Drop hosts",      "list",
+                      "Hostnames to silently ignore — no state, no alerts."),
+            ],
+        },
+        {
+            "id": "users",
+            "title": "Users",
+            "description": "Accounts defined in the config file. Password hashes are never shown.",
+            "users": users_list,
+            "fields": [
+                field("default_owner", "Default owner", "text",
+                      "Username that owns hosts with no explicit owner. "
+                      "Falls back to the first admin user."),
+            ],
+        },
+        {
+            "id": "channels",
+            "title": "Notification Channels",
+            "description": "Named notification providers. Credentials are masked.",
+            "channels": notif_channels,
+            "fields": [
+                field("default_notification_channels", "Default channels", "list",
+                      "Channels used when a host does not specify its own."),
+            ],
+        },
+        {
+            "id": "hosts",
+            "title": "Hosts",
+            "description": "Host definitions loaded from the config file.",
+            "hosts": hosts_list,
+            "fields": [],
+        },
+        {
+            "id": "runtime",
+            "title": "Runtime",
+            "description": "Flags set at startup (require restart to change).",
+            "fields": [
+                field("foreground", "Foreground mode", "boolean",
+                      "Run in the foreground instead of daemonising."),
+                field("verbose",    "Verbose logging",  "boolean",
+                      "Enable verbose log output."),
+                field("debug",      "Debug level",      "number",
+                      "0 = off. Higher values increase log verbosity."),
+            ],
+        },
+    ]

hbd/server/static/style.css

@@ -140,3 +140,68 @@
       float: left;
   }
 
+/* ── Responsive / mobile ── */
+
+/* Suppress the global transition on mobile to avoid sluggish feel */
+@media (max-width: 640px) {
+  * { transition: none !important; }
+
+  html, body {
+    overflow: auto;
+    height: auto;
+    font-size: 16px;          /* prevent iOS auto-zoom on inputs */
+  }
+
+  /* Pages that use flex-column full-viewport layout need to relax on mobile */
+  body[style*="height: 100vh"],
+  body {
+    height: auto !important;
+    min-height: 100vh;
+  }
+
+  /* Containers: full width, no fixed heights */
+  .container {
+    max-width: 100% !important;
+    max-height: none !important;
+    overflow: visible !important;
+    padding: 8px !important;
+  }
+
+  /* Log section: fixed reasonable height instead of flex-grow */
+  .log-section {
+    flex: none !important;
+    max-height: 40vh !important;
+    overflow-y: auto !important;
+  }
+
+  /* Table section: allow vertical scroll, cap height */
+  .table-section {
+    max-height: 55vh !important;
+    overflow-y: auto !important;
+    overflow-x: auto !important;
+    padding: 8px !important;
+  }
+
+  /* Slightly larger tap targets in tables */
+  #ntable td, #ntable th {
+    padding: 4px 6px !important;
+    font-size: 0.82em !important;
+  }
+
+  /* Cards on plugin/alerts pages */
+  .host-card, .alert-card, .card {
+    padding: 10px !important;
+    margin-bottom: 8px !important;
+  }
+
+  /* Settings page tables */
+  table { width: 100%; }
+
+  h1 { font-size: 1.2em !important; }
+  h2 { font-size: 1em !important; }
+}
+
+/* Suppress nav-username text on very narrow screens — avatar/initials is enough */
+@media (max-width: 400px) {
+  .nav-username { display: none; }
+}

hbd/server/templates/about.html

@@ -0,0 +1,199 @@
+<!DOCTYPE html>
+<html>
+  {% include 'head.html' %}
+
+  <style>
+    html, body { overflow: visible; }
+
+    .container {
+      max-width: 700px;
+      margin: 0 auto;
+    }
+
+    h1 {
+      color: #333;
+      margin-bottom: 4px;
+      font-size: 1.5em;
+    }
+
+    .subtitle {
+      color: #666;
+      margin-bottom: 24px;
+      font-size: 0.9em;
+    }
+
+    .section {
+      background: #fff;
+      border-radius: 8px;
+      box-shadow: 0 1px 6px rgba(0,0,0,0.1);
+      padding: 20px 24px;
+      margin-bottom: 20px;
+    }
+
+    .section h2 {
+      font-size: 1em;
+      font-weight: 700;
+      color: #333;
+      margin: 0 0 16px;
+      padding-bottom: 10px;
+      border-bottom: 1px solid #eee;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+    }
+
+    .info-row {
+      display: flex;
+      align-items: baseline;
+      padding: 8px 0;
+      border-bottom: 1px solid #f5f5f5;
+      font-size: 0.9em;
+    }
+    .info-row:last-child { border-bottom: none; }
+
+    .info-label {
+      width: 160px;
+      flex-shrink: 0;
+      color: #666;
+      font-size: 0.88em;
+    }
+
+    .info-value {
+      color: #222;
+      word-break: break-all;
+    }
+
+    .info-value a {
+      color: #0066cc;
+      text-decoration: none;
+    }
+    .info-value a:hover { text-decoration: underline; }
+
+    .version-badge {
+      display: inline-block;
+      padding: 3px 12px;
+      background: #e8f0fe;
+      color: #1a73e8;
+      border-radius: 12px;
+      font-size: 0.85em;
+      font-weight: 600;
+      font-family: monospace;
+    }
+
+    .hb-logo {
+      font-size: 2.5em;
+      font-weight: 700;
+      color: #0066cc;
+      letter-spacing: -1px;
+      margin-bottom: 6px;
+    }
+
+    .hb-tagline {
+      color: #555;
+      font-size: 0.95em;
+    }
+
+    .logo-section {
+      display: flex;
+      align-items: center;
+      gap: 20px;
+      padding: 8px 0 4px;
+    }
+
+    .logo-text { flex: 1; }
+  </style>
+
+  <body>
+    {% include 'nav.html' %}
+
+    <div class="container">
+      <h1>{{ header }}</h1>
+      <p class="subtitle">Heartbeat monitoring system</p>
+
+      <div class="section">
+        <div class="logo-section">
+          <div class="logo-text">
+            <div class="hb-logo">Heartbeat</div>
+            <div class="hb-tagline">Lightweight host monitoring over UDP</div>
+          </div>
+          <span class="version-badge">v{{ hbd_version }}</span>
+        </div>
+      </div>
+
+      <div class="section">
+        <h2>Version</h2>
+        <div class="info-row">
+          <span class="info-label">Server version</span>
+          <span class="info-value">{{ hbd_version }}</span>
+        </div>
+        <div class="info-row">
+          <span class="info-label">Python</span>
+          <span class="info-value">{{ python_version }}</span>
+        </div>
+        <div class="info-row">
+          <span class="info-label">License</span>
+          <span class="info-value">MIT</span>
+        </div>
+      </div>
+
+      <div class="section">
+        <h2>Runtime</h2>
+        <div class="info-row">
+          <span class="info-label">Host</span>
+          <span class="info-value">{{ server_hostname }}</span>
+        </div>
+        <div class="info-row">
+          <span class="info-label">Started</span>
+          <span class="info-value">{{ start_time_str }}</span>
+        </div>
+        <div class="info-row">
+          <span class="info-label">Uptime</span>
+          <span class="info-value" id="uptime-value">{{ uptime_str }}</span>
+        </div>
+        <div class="info-row">
+          <span class="info-label">Hosts monitored</span>
+          <span class="info-value">{{ host_count }}</span>
+        </div>
+      </div>
+
+      <div class="section">
+        <h2>Contact &amp; Source</h2>
+        <div class="info-row">
+          <span class="info-label">Author</span>
+          <span class="info-value">Andreas Wrede</span>
+        </div>
+        <div class="info-row">
+          <span class="info-label">Email</span>
+          <span class="info-value"><a href="mailto:aew@wrede.ca">aew@wrede.ca</a></span>
+        </div>
+        <div class="info-row">
+          <span class="info-label">Repository</span>
+          <span class="info-value"><a href="https://git.wrede.ca/andreas/heartbeat" target="_blank" rel="noopener">git.wrede.ca/andreas/heartbeat</a></span>
+        </div>
+      </div>
+
+    </div>
+
+    <script>
+      (function() {
+        var startEpoch = {{ start_epoch }};
+        var el = document.getElementById('uptime-value');
+        if (!el) return;
+        function fmt(s) {
+          var d = Math.floor(s / 86400);
+          var h = Math.floor((s % 86400) / 3600);
+          var m = Math.floor((s % 3600) / 60);
+          var sec = s % 60;
+          if (d > 0) return d + 'd ' + h + 'h ' + m + 'm';
+          if (h > 0) return h + 'h ' + m + 'm ' + sec + 's';
+          return m + 'm ' + sec + 's';
+        }
+        function tick() {
+          var up = Math.floor(Date.now() / 1000 - startEpoch);
+          el.textContent = fmt(up);
+        }
+        tick();
+        setInterval(tick, 1000);
+      })();
+    </script>
+  </body>
+</html>

hbd/server/templates/alerts.html

@@ -3,44 +3,13 @@
   {% include 'head.html' %}
 
   <style>
-    body {
-      margin: 20px;
-      background: #f5f5f5;
-    }
-
-    .nav {
-      background: #fff;
-      padding: 15px;
-      margin-bottom: 20px;
-      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
-      border-radius: 4px;
-    }
-
-    .nav a {
-      margin-right: 20px;
-      text-decoration: none;
-      color: #0066cc;
-      font-weight: 500;
-    }
-
-    .nav a:hover {
-      text-decoration: underline;
-    }
-
-    .nav a.active {
-      color: #333;
-      font-weight: bold;
-    }
 
     .container {
       max-width: 1400px;
       margin: 0 auto;
     }
 
-    h1 {
+    h1 { color: #333; margin-bottom: 5px; margin-top: 15px; font-size: 1.5em; }
-      color: #333;
-      margin-bottom: 10px;
-    }
 
     .subtitle {
       color: #666;
@@ -48,55 +17,40 @@
     }
 
     .summary-cards {
-      display: grid;
+      display: flex;
-      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+      flex-wrap: wrap;
-      gap: 20px;
+      gap: 10px;
-      margin-bottom: 30px;
+      margin-bottom: 16px;
     }
 
     .summary-card {
       background: white;
-      border-radius: 8px;
+      border-radius: 6px;
-      padding: 20px;
+      padding: 6px 14px;
-      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+      box-shadow: 0 1px 4px rgba(0,0,0,0.1);
-      text-align: center;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      border-left: 4px solid #ddd;
     }
 
-    .summary-card.critical {
+    .summary-card.critical { border-left-color: #ea1e0f; }
-      border-left: 5px solid #f44336;
+    .summary-card.warning  { border-left-color: #ff9800; }
-    }
+    .summary-card.ok       { border-left-color: #4caf50; }
-
-    .summary-card.warning {
-      border-left: 5px solid #ff9800;
-    }
-
-    .summary-card.ok {
-      border-left: 5px solid #4caf50;
-    }
 
     .summary-number {
-      font-size: 3em;
+      font-size: 1.4em;
       font-weight: bold;
-      margin: 10px 0;
+      line-height: 1;
     }
 
-    .summary-number.critical {
+    .summary-number.critical { color: #ea1e0f; }
-      color: #f44336;
+    .summary-number.warning  { color: #ff9800; }
-    }
+    .summary-number.ok       { color: #4caf50; }
-
-    .summary-number.warning {
-      color: #ff9800;
-    }
-
-    .summary-number.ok {
-      color: #4caf50;
-    }
 
     .summary-label {
       color: #666;
-      text-transform: uppercase;
+      font-size: 0.85em;
-      font-size: 0.9em;
-      letter-spacing: 1px;
     }
 
     .filters {
@@ -155,7 +109,7 @@
     }
     
     .alert-item.acknowledged {
-      opacity: 0.6;
+      opacity: 0.8;
       background: #f0f0f0;
     }
 
@@ -327,11 +281,7 @@
   </style>
 
   <body>
-    <div class="nav">
+    {% include 'nav.html' %}
-      <a href="/live">Live Dashboard</a>
-      <a href="/plugins">Plugin Metrics</a>
-      <a href="/alerts" class="active">Alerts</a>
-    </div>
 
     <div class="container">
       <h1>{{ header }}</h1>

hbd/server/templates/head.html

@@ -1,7 +1,281 @@
 <head>
     <meta http-equiv="content-type" content="text/html; charset=utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="stylesheet" href="/static/style.css" type="text/css" />
     <link rel="icon" href="/static/images/favicon.ico" sizes="32x32" />
     <title>{{ title }}</title>
-    <script src="{{ extra_scripts }}"></script>
+    {% if extra_scripts %}<script src="{{ extra_scripts }}"></script>{% endif %}
+    <style>
+      /* ── Reset / shared baseline ── */
+      *, *::before, *::after { box-sizing: border-box; }
+      html {
+        font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
+        font-size: 14px;
+      }
+      body {
+        margin: 0;
+        padding: 10px;
+        padding-top: 60px;
+        background: #f5f5f5;
+      }
+      h1 { font-size: 1.5em; color: #333; margin: 0 0 5px; }
+      h2 { font-size: 1.1em; color: #333; margin: 0 0 8px; }
+      p  { margin: 0; }
+
+      /* Navigation bar — shared across all pages */
+      .nav {
+        position: fixed;
+        top: 0;
+        left: 0;
+        right: 0;
+        z-index: 200;
+        background: #fff;
+        padding: 6px 12px;
+        box-shadow: 0 2px 4px rgba(0,0,0,.1);
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        flex-wrap: wrap;
+        gap: 8px;
+      }
+      .nav-links { display: flex; align-items: center; flex-wrap: wrap; gap: 4px; }
+      .nav a {
+        margin-right: 20px;
+        text-decoration: none;
+        color: #0066cc;
+        font-weight: 500;
+        font-size: 0.9em;
+      }
+      .nav a:hover { text-decoration: underline; }
+      .nav a.active { color: #333; font-weight: bold; }
+      .nav-user {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        text-decoration: none;
+        color: #333;
+        font-size: 0.9em;
+        font-weight: 500;
+        padding: 4px 8px;
+        border-radius: 20px;
+        transition: background 0.15s;
+      }
+      .nav-user:hover { background: #f0f4ff; text-decoration: none; }
+      .nav-username {
+        max-width: 0;
+        overflow: hidden;
+        white-space: nowrap;
+        opacity: 0;
+        transition: max-width 0.2s ease, opacity 0.2s ease;
+      }
+      .nav-user:hover .nav-username {
+        max-width: 160px;
+        opacity: 1;
+      }
+      .nav-avatar {
+        width: 28px; height: 28px;
+        border-radius: 50%;
+        object-fit: cover;
+        flex-shrink: 0;
+      }
+      .nav-initials {
+        width: 28px; height: 28px;
+        border-radius: 50%;
+        background: #0066cc;
+        color: #fff;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        font-size: 0.75em;
+        font-weight: 700;
+        flex-shrink: 0;
+      }
+
+      /* ── Mobile nav: hamburger toggle ── */
+      .nav-hamburger {
+        display: none;
+        flex-direction: column;
+        justify-content: space-between;
+        width: 26px; height: 20px;
+        cursor: pointer;
+        flex-shrink: 0;
+        background: none;
+        border: none;
+        padding: 0;
+      }
+      .nav-hamburger span {
+        display: block;
+        height: 3px;
+        background: #555;
+        border-radius: 2px;
+      }
+
+      @media (max-width: 640px) {
+        .nav-hamburger { display: flex; }
+        .nav-links {
+          display: none;
+          width: 100%;
+          flex-direction: column;
+          align-items: flex-start;
+          padding-top: 8px;
+          border-top: 1px solid #eee;
+          order: 3;
+        }
+        .nav-links.nav-open { display: flex; }
+        .nav-links a { margin-right: 0; padding: 6px 0; font-size: 1em; }
+      }
+
+      /* Swiss railway clock — nav */
+      .nav-clock {
+        flex-shrink: 0;
+        line-height: 0;
+        margin-left: auto;
+        padding: 4px 4px 4px 0;
+        cursor: pointer;
+      }
+      #swiss-clock { display: block; }
+
+      /* Swiss railway clock — full-page overlay */
+      #clock-overlay {
+        display: none;
+        position: fixed;
+        inset: 0;
+        z-index: 9999;
+        background: #1a1a1a;
+        align-items: center;
+        justify-content: center;
+        cursor: pointer;
+      }
+      #clock-overlay.visible { display: flex; }
+      #swiss-clock-overlay { display: block; }
+    </style>
+    <script>
+    /* ── Swiss Federal Railway (SBB) clock ── */
+
+    /* Draw one frame of the clock onto any canvas element. */
+    function drawSwissClock(canvas) {
+      var SIZE = canvas.width;
+      var R = SIZE / 2;
+      var ctx = canvas.getContext('2d');
+      var now = new Date();
+      var h  = now.getHours() % 12;
+      var m  = now.getMinutes();
+      var s  = now.getSeconds();
+      var ms = now.getMilliseconds();
+
+      /* Seconds hand idles ~1.5 s at 12 before advancing (SBB behaviour) */
+      var sFrac = s + ms / 1000;
+      var sAngle = sFrac >= 58.5 ? 0 : (sFrac / 58.5) * Math.PI * 2;
+
+      ctx.clearRect(0, 0, SIZE, SIZE);
+
+      /* face */
+      ctx.beginPath();
+      ctx.arc(R, R, R - 1, 0, Math.PI * 2);
+      ctx.fillStyle = '#fff';
+      ctx.fill();
+      ctx.strokeStyle = '#333';
+      ctx.lineWidth = SIZE * 0.018;
+      ctx.stroke();
+
+      /* tick marks */
+      for (var i = 0; i < 60; i++) {
+        var a = (i / 60) * Math.PI * 2 - Math.PI / 2;
+        var isHour = (i % 5 === 0);
+        ctx.beginPath();
+        ctx.moveTo(R + Math.cos(a) * (isHour ? R * 0.72 : R * 0.88),
+                   R + Math.sin(a) * (isHour ? R * 0.72 : R * 0.88));
+        ctx.lineTo(R + Math.cos(a) * R * 0.94,
+                   R + Math.sin(a) * R * 0.94);
+        ctx.strokeStyle = '#222';
+        ctx.lineWidth = isHour ? SIZE * 0.027 : SIZE * 0.011;
+        ctx.lineCap = 'butt';
+        ctx.stroke();
+      }
+
+      /* hands */
+      function hand(angle, tip, tail, width, color) {
+        ctx.save();
+        ctx.translate(R, R);
+        ctx.rotate(angle);
+        ctx.beginPath();
+        ctx.moveTo(tail, 0);
+        ctx.lineTo(tip,  0);
+        ctx.strokeStyle = color;
+        ctx.lineWidth = width;
+        ctx.lineCap = 'square';
+        ctx.stroke();
+        ctx.restore();
+      }
+
+      hand((m + s / 60) / 60 * Math.PI * 2 - Math.PI / 2,
+           R * 0.88, -R * 0.12, SIZE * 0.027, '#222');           /* minute */
+      hand((h + m / 60) / 12 * Math.PI * 2 - Math.PI / 2,
+           R * 0.58, -R * 0.12, SIZE * 0.039, '#222');           /* hour   */
+      hand(sAngle - Math.PI / 2, R * 0.78, -R * 0.22,
+           SIZE * 0.013, '#e00');                                 /* second tail+tip */
+
+      /* round dot at tip of second hand */
+      var dotR = SIZE * 0.028;
+      ctx.save();
+      ctx.translate(R, R);
+      ctx.rotate(sAngle - Math.PI / 2);
+      ctx.beginPath();
+      ctx.arc(R * 0.78, 0, dotR, 0, Math.PI * 2);
+      ctx.fillStyle = '#e00';
+      ctx.fill();
+      ctx.restore();
+
+      /* centre cap */
+      ctx.beginPath();
+      ctx.arc(R, R, R * 0.04, 0, Math.PI * 2);
+      ctx.fillStyle = '#222';
+      ctx.fill();
+    }
+
+    /* Resize the overlay canvas to fit the viewport, keeping it square. */
+    function resizeOverlayClock() {
+      var oc = document.getElementById('swiss-clock-overlay');
+      if (!oc) return;
+      var size = Math.min(window.innerWidth, window.innerHeight) * 0.88;
+      size = Math.floor(size);
+      oc.width  = size;
+      oc.height = size;
+    }
+
+    /* Main tick — redraws both nav clock and (if visible) overlay clock. */
+    function clockTick() {
+      var nav = document.getElementById('swiss-clock');
+      if (nav) drawSwissClock(nav);
+      var overlay = document.getElementById('clock-overlay');
+      if (overlay && overlay.classList.contains('visible')) {
+        var oc = document.getElementById('swiss-clock-overlay');
+        if (oc) drawSwissClock(oc);
+      }
+      var delay = 100 - (Date.now() % 100);
+      setTimeout(clockTick, delay);
+    }
+
+    document.addEventListener('DOMContentLoaded', function() {
+      /* Start the shared tick loop */
+      clockTick();
+
+      /* Overlay toggle — clicking the nav clock opens it */
+      var navClock = document.querySelector('.nav-clock');
+      var overlay  = document.getElementById('clock-overlay');
+      if (navClock && overlay) {
+        navClock.addEventListener('click', function() {
+          resizeOverlayClock();
+          overlay.classList.add('visible');
+        });
+        overlay.addEventListener('click', function() {
+          overlay.classList.remove('visible');
+        });
+        window.addEventListener('resize', function() {
+          if (overlay.classList.contains('visible')) resizeOverlayClock();
+        });
+      }
+    });
+    </script>
+    <script src="static/sorttable.js"></script>
 </head>

hbd/server/templates/live.html

@@ -4,47 +4,48 @@
 
   <style>
     body {
-      margin: 10px;
+      display: flex;
-      background: #f5f5f5;
+      flex-direction: column;
+      height: 100vh;
       overflow: hidden;
     }
 
-    .nav {
+    @media (max-width: 640px) {
-      background: #fff;
+      body {
-      padding: 10px 15px;
+        height: auto;
-      margin-bottom: 10px;
+        min-height: 100vh;
-      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        overflow: auto;
-      border-radius: 4px;
+        flex-direction: column;
       }
-
+      .container {
-    .nav a {
+        max-height: none;
-      margin-right: 20px;
+        overflow: visible;
-      text-decoration: none;
-      color: #0066cc;
-      font-weight: 500;
-      font-size: 0.9em;
       }
-
+      .table-section {
-    .nav a:hover {
+        max-height: 55vh;
-      text-decoration: underline;
+      }
+      .log-section {
+        flex: none;
+        max-height: 40vh;
       }
-
-    .nav a.active {
-      color: #333;
-      font-weight: bold;
     }
 
     .container {
+      flex: 1;
+      min-height: 0;
       max-width: 1600px;
+      width: 100%;
       margin: 0 auto;
-      max-height: calc(100vh - 120px);
+      display: flex;
-      overflow-y: auto;
+      flex-direction: column;
-      padding-right: 10px;
+      gap: 15px;
+      overflow: hidden;
     }
 
     h1 {
       color: #333;
       margin-bottom: 5px;
+      margin-top: 15px; 
       font-size: 1.5em;
     }
 
@@ -75,14 +76,18 @@
       border-radius: 6px;
       padding: 15px;
       box-shadow: 0 1px 4px rgba(0,0,0,0.1);
+      overflow-x: auto;
+      overflow-y: auto;
+      max-height: 60vh;
     }
 
     .log-section {
+      flex: 1;
+      min-height: 0;
       background: white;
       border-radius: 6px;
       padding: 15px;
       box-shadow: 0 1px 4px rgba(0,0,0,0.1);
-      max-height: 400px;
       overflow-y: auto;
     }
 
@@ -96,7 +101,8 @@
     #ntable th {
       border: 1px solid #e0e0e0;
       text-align: left;
-      padding: 8px 10px;
+      padding: 2px 4px;
+      white-space: nowrap;
     }
 
     #ntable tr:nth-child(even) {
@@ -107,8 +113,24 @@
       background-color: #e3f2fd;
     }
 
+    #ntable tbody tr.row-warning {
+      background-color: #fff8c5;
+    }
+
+    #ntable tbody tr.row-critical {
+      background-color: #fde8e8;
+    }
+
+    #ntable tbody tr.row-warning:hover {
+      background-color: #fff0a0;
+    }
+
+    #ntable tbody tr.row-critical:hover {
+      background-color: #f9c8c8;
+    }
+
     #ntable th {
-      padding: 12px 10px;
+      padding: 6px 8px;
       background-color: #2196f3;
       color: white;
       font-weight: 600;
@@ -137,24 +159,20 @@
     }
 
     /* Scrollbar styling */
-    .container::-webkit-scrollbar,
     .log-section::-webkit-scrollbar {
       width: 8px;
     }
 
-    .container::-webkit-scrollbar-track,
     .log-section::-webkit-scrollbar-track {
       background: #f1f1f1;
       border-radius: 4px;
     }
 
-    .container::-webkit-scrollbar-thumb,
     .log-section::-webkit-scrollbar-thumb {
       background: #888;
       border-radius: 4px;
     }
 
-    .container::-webkit-scrollbar-thumb:hover,
     .log-section::-webkit-scrollbar-thumb:hover {
       background: #555;
     }
@@ -162,7 +180,7 @@
     /* Message styling */
     #messages {
       font-size: 0.85em;
-      line-height: 1.6;
+      line-height: 1.0;
     }
 
     #messages div {
@@ -224,15 +242,37 @@
     var nTable = document;
     var name_idx = {};
     var c = 0;
+    var HBD_VERSION = "{{ hbd_version }}";
+
+    function hostNameHtml(data) {
+      var nameHtml = data.name;
+      if (!data.hbc_version || data.hbc_version !== HBD_VERSION) {
+        nameHtml += ' 🥀';
+      }
+      return data.dyn ? '<b>' + nameHtml + '</b>' : nameHtml;
+    }
 
     function setup() {
       name_idx = {};
       nTable = document.getElementById("ntable");
       for (var i = 0, row; (row = nTable.rows[i]); i++) {
         if (i == 0) continue;
-        name = nTable.rows[i].cells[0].innerText;
+        var cell = nTable.rows[i].cells[0];
+        var name = cell.dataset.name || cell.innerText.replace(/\s*🥀\s*$/, '').trim();
         name_idx[name] = nTable.rows[i];
-        /* console.log("name_Id[" + name + "]: " + name_idx[name].innerText); */
+      }
+    }
+
+    function updateRowAlert(row, data) {
+      var criticalUnacked = data.alert_critical_unacked || 0;
+      var criticalAcked = data.alert_critical_acked || 0;
+      var warningUnacked = data.alert_warning_unacked || 0;
+      var warningAcked = data.alert_warning_acked || 0;
+      row.classList.remove('row-warning', 'row-critical');
+      if (criticalUnacked > 0 || criticalAcked > 0) {
+        row.classList.add('row-critical');
+      } else if (warningUnacked > 0 || warningAcked > 0) {
+        row.classList.add('row-warning');
       }
     }
 
@@ -270,11 +310,8 @@
       row.appendChild(c_ipv6state);
       row.appendChild(c_ipv6latency);
       row.appendChild(c_ipv6statets);
-      if (data.dyn) {
+      c_name.dataset.name = data.name;
-        c_name.innerHTML = "<b>" + data.name + "</b>";
+      c_name.innerHTML = hostNameHtml(data);
-      } else {
-        c_name.innerHTML = data.name;
-      }
       
       // Set alert counts in "x/y" format (unacked/acked)
       var warningUnacked = data.alert_warning_unacked || 0;
@@ -303,12 +340,31 @@
       var table = document.getElementById("ntablebody"); // find table to append to
       table.appendChild(row); // append row to table
       name_idx[c_name] = row;
+      updateRowAlert(row, data);
     }
 
     function formatTS(ts) {
-      const milliseconds = ts * 1000;
+      const now = new Date();
-      const dateObject = new Date(milliseconds);
+      const d = new Date(ts * 1000);
-      return dateObject.toLocaleString("de-DE");
+
+      const pad = n => String(n).padStart(2, '0');
+      const timeStr = `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+
+      // Same calendar day → show time only
+      if (d.toDateString() === now.toDateString()) {
+        return timeStr;
+      }
+
+      // Within 8 days → show "-X d hh:mm:ss"
+      const todayStart = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+      const dStart = new Date(d.getFullYear(), d.getMonth(), d.getDate());
+      const diffDays = Math.round((todayStart - dStart) / 86400000);
+      if (diffDays < 8) {
+        return `-${diffDays}d ${timeStr}`;
+      }
+
+      // Older → date only
+      return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
     }
 
     function update_table(data) {
@@ -317,6 +373,11 @@
         setup();
       }
       
+      // Update name cell (version indicator)
+      var nameCell = name_idx[data.name].cells[0];
+      nameCell.dataset.name = data.name;
+      nameCell.innerHTML = hostNameHtml(data);
+
       // Update warning and critical counts in "x/y" format (unacked/acked)
       var warningUnacked = data.alert_warning_unacked || 0;
       var warningAcked = data.alert_warning_acked || 0;
@@ -364,6 +425,7 @@
         name_idx[data.name].cells[4 + i * 4].innerHTML = state;
         name_idx[data.name].cells[5 + i * 4].innerHTML = latency;
       }
+      updateRowAlert(name_idx[data.name], data);
     }
 
     function WS_Connect() {
@@ -419,17 +481,15 @@
     WS_Connect();
   </script>
   <body>
-    <div class="nav">
+    {% include 'nav.html' %}
-      <a href="/live" class="active">Live Dashboard</a>
-      <a href="/plugins">Plugin Metrics</a>
-      <a href="/alerts">Alerts</a>
-    </div>
 
     {% include 'menu.html' %}
 
     <div class="container">
+      <div>
         <h1>{{ header }}</h1>
         <p class="subtitle">Real-time host monitoring and event log</p>
+      </div>
       
       <div class="table-section">
         <table id="ntable" class="sortable">
@@ -450,8 +510,8 @@
           </thead>
           <tbody id="ntablebody">
             {% for host in hosts %}
-            <tr>
+            <tr class="{% if host.alert_critical_unacked > 0 or host.alert_critical_acked > 0 %}row-critical{% elif host.alert_warning_unacked > 0 or host.alert_warning_acked > 0 %}row-warning{% endif %}">
-              <td>{{ host.name }}</td>
+              <td data-name="{{ host.name }}">{{ host.name }}{% if not host.hbc_version or host.hbc_version != hbd_version %} 🥀{% endif %}</td>
               <td style="text-align: center; color: #ff9800; font-weight: bold;">
                 {%- set warning_unacked = host.alert_warning_unacked -%}
                 {%- set warning_acked = host.alert_warning_acked -%}

hbd/server/templates/menu.html

@@ -1,3 +1,2 @@
 <!-- <label for="drawer-toggle" id="drawer-toggle-label"></label>
 s<header>{{ header }}</header> -->
-

hbd/server/templates/nav.html

@@ -0,0 +1,45 @@
+<div class="nav">
+  <button class="nav-hamburger" id="nav-hamburger-btn" aria-label="Menu" aria-expanded="false">
+    <span></span><span></span><span></span>
+  </button>
+  <div class="nav-links" id="nav-links">
+    <a href="/live"{% if active_page == "live" %} class="active"{% endif %}>Live Dashboard</a>
+    <a href="/plugins"{% if active_page == "plugins" %} class="active"{% endif %}>Host Overview</a>
+    <a href="/alerts"{% if active_page == "alerts" %} class="active"{% endif %}>Alerts</a>
+    {% if current_user and current_user.admin %}
+    <a href="/settings"{% if active_page == "settings" %} class="active"{% endif %}>Settings</a>
+    {% endif %}
+    <a href="/about"{% if active_page == "about" %} class="active"{% endif %}>About</a>
+  </div>
+  <div class="nav-clock" title="Click for full-screen clock">
+    <canvas id="swiss-clock" width="44" height="44"></canvas>
+  </div>
+  {% if current_user %}
+  <a href="/profile" class="nav-user{% if active_page == 'profile' %} active{% endif %}" title="{{ current_user.full_name or current_user.username }}">
+    {% if current_user.avatar %}
+    <img class="nav-avatar" src="{{ current_user.avatar_url }}" alt="{{ current_user.full_name or current_user.username }}">
+    {% else %}
+    <span class="nav-initials">{{ (current_user.full_name or current_user.username)[:1] | upper }}</span>
+    {% endif %}
+    <span class="nav-username">{{ current_user.full_name or current_user.username }}</span>
+  </a>
+  {% endif %}
+</div>
+
+<!-- Full-page clock overlay (click anywhere to dismiss) -->
+<div id="clock-overlay">
+  <canvas id="swiss-clock-overlay" width="400" height="400"></canvas>
+</div>
+
+<script>
+  (function() {
+    var btn = document.getElementById('nav-hamburger-btn');
+    var links = document.getElementById('nav-links');
+    if (btn && links) {
+      btn.addEventListener('click', function() {
+        var open = links.classList.toggle('nav-open');
+        btn.setAttribute('aria-expanded', open ? 'true' : 'false');
+      });
+    }
+  })();
+</script>

hbd/server/templates/profile.html

@@ -0,0 +1,330 @@
+<!DOCTYPE html>
+<html>
+  {% include 'head.html' %}
+
+  <style>
+    html, body { overflow: visible; }
+
+    .container {
+      max-width: 900px;
+      margin: 0 auto;
+    }
+
+    h1 {
+      color: #333;
+      margin-bottom: 4px;
+      font-size: 1.5em;
+    }
+
+    .subtitle {
+      color: #666;
+      margin-bottom: 24px;
+      font-size: 0.9em;
+    }
+
+    /* ---- Profile card ---- */
+    .profile-card {
+      background: #fff;
+      border-radius: 8px;
+      box-shadow: 0 1px 6px rgba(0,0,0,0.1);
+      padding: 28px 32px;
+      margin-bottom: 24px;
+      display: flex;
+      align-items: center;
+      gap: 28px;
+    }
+
+    .avatar-large {
+      width: 80px;
+      height: 80px;
+      border-radius: 50%;
+      object-fit: cover;
+      flex-shrink: 0;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.15);
+    }
+
+    .avatar-initials-large {
+      width: 80px;
+      height: 80px;
+      border-radius: 50%;
+      background: #0066cc;
+      color: #fff;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 2em;
+      font-weight: 700;
+      flex-shrink: 0;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.15);
+    }
+
+    .profile-info { flex: 1; }
+
+    .profile-name {
+      font-size: 1.4em;
+      font-weight: 700;
+      color: #222;
+      margin-bottom: 4px;
+    }
+
+    .profile-username {
+      font-size: 0.9em;
+      color: #666;
+      margin-bottom: 10px;
+    }
+
+    .badge {
+      display: inline-block;
+      padding: 2px 10px;
+      border-radius: 12px;
+      font-size: 0.78em;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.4px;
+    }
+
+    .badge-admin { background: #e8f0fe; color: #1a73e8; }
+    .badge-user  { background: #f1f3f4; color: #555; }
+
+    .profile-logout {
+      margin-top: 14px;
+    }
+
+    .btn-logout {
+      display: inline-block;
+      padding: 6px 16px;
+      border-radius: 4px;
+      background: #f44336;
+      color: #fff;
+      font-size: 0.85em;
+      font-weight: 500;
+      text-decoration: none;
+      transition: background 0.15s;
+    }
+    .btn-logout:hover { background: #d32f2f; text-decoration: none; }
+
+    /* ---- Section cards ---- */
+    .section {
+      background: #fff;
+      border-radius: 8px;
+      box-shadow: 0 1px 6px rgba(0,0,0,0.1);
+      padding: 20px 24px;
+      margin-bottom: 20px;
+    }
+
+    .section h2 {
+      font-size: 1em;
+      font-weight: 700;
+      color: #333;
+      margin: 0 0 16px;
+      padding-bottom: 10px;
+      border-bottom: 1px solid #eee;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+    }
+
+    /* ---- Settings rows ---- */
+    .settings-row {
+      display: flex;
+      align-items: baseline;
+      padding: 8px 0;
+      border-bottom: 1px solid #f5f5f5;
+      font-size: 0.9em;
+    }
+    .settings-row:last-child { border-bottom: none; }
+
+    .settings-label {
+      width: 180px;
+      flex-shrink: 0;
+      color: #666;
+      font-size: 0.88em;
+    }
+
+    .settings-value { color: #222; }
+
+    .settings-empty { color: #aaa; font-style: italic; }
+
+    /* ---- Host lists ---- */
+    .host-grid {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 8px;
+    }
+
+    .host-chip {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      padding: 4px 12px;
+      border-radius: 16px;
+      font-size: 0.85em;
+      font-weight: 500;
+      text-decoration: none;
+    }
+
+    .host-chip.owner   { background: #e8f5e9; color: #2e7d32; }
+    .host-chip.manager { background: #e3f2fd; color: #1565c0; }
+    .host-chip.monitor { background: #f3e5f5; color: #6a1b9a; }
+
+    .host-chip-dot {
+      width: 7px; height: 7px; border-radius: 50%;
+    }
+    .owner   .host-chip-dot { background: #2e7d32; }
+    .manager .host-chip-dot { background: #1565c0; }
+    .monitor .host-chip-dot { background: #6a1b9a; }
+
+    .no-hosts {
+      color: #aaa;
+      font-size: 0.9em;
+      font-style: italic;
+    }
+
+    /* ---- Notification channels ---- */
+    .channel-row {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      padding: 6px 0;
+      border-bottom: 1px solid #f5f5f5;
+      font-size: 0.9em;
+    }
+    .channel-row:last-child { border-bottom: none; }
+
+    .channel-type {
+      display: inline-block;
+      padding: 2px 8px;
+      border-radius: 10px;
+      font-size: 0.78em;
+      font-weight: 600;
+      text-transform: uppercase;
+      background: #f1f3f4;
+      color: #555;
+      min-width: 70px;
+      text-align: center;
+    }
+
+    .channel-name { color: #333; }
+  </style>
+
+  <body>
+    {% include 'nav.html' %}
+
+    <div class="container">
+      <h1>{{ header }}</h1>
+      <p class="subtitle">Your account settings and host access</p>
+
+      <!-- Profile card -->
+      <div class="profile-card">
+        {% if current_user and current_user.avatar %}
+        <img class="avatar-large" src="{{ current_user.avatar_url }}" alt="">
+        {% else %}
+        <div class="avatar-initials-large">
+          {{ ((current_user.full_name if current_user else '') or (current_user.username if current_user else '?'))[:1] | upper }}
+        </div>
+        {% endif %}
+
+        <div class="profile-info">
+          <div class="profile-name">{{ current_user.full_name if current_user and current_user.full_name else (current_user.username if current_user else '—') }}</div>
+          <div class="profile-username">@{{ current_user.username if current_user else '—' }}</div>
+          {% if current_user and current_user.admin %}
+          <span class="badge badge-admin">Admin</span>
+          {% else %}
+          <span class="badge badge-user">User</span>
+          {% endif %}
+          <div class="profile-logout">
+            <a href="/logout" class="btn-logout">Sign out</a>
+          </div>
+        </div>
+      </div>
+
+      <!-- Account settings -->
+      <div class="section">
+        <h2>Account</h2>
+        <div class="settings-row">
+          <span class="settings-label">Username</span>
+          <span class="settings-value">{{ current_user.username if current_user else '—' }}</span>
+        </div>
+        <div class="settings-row">
+          <span class="settings-label">Full name</span>
+          {% if current_user and current_user.full_name %}
+          <span class="settings-value">{{ current_user.full_name }}</span>
+          {% else %}
+          <span class="settings-empty">Not set</span>
+          {% endif %}
+        </div>
+        <div class="settings-row">
+          <span class="settings-label">Role</span>
+          <span class="settings-value">{{ 'Administrator' if current_user and current_user.admin else 'User' }}</span>
+        </div>
+        <div class="settings-row">
+          <span class="settings-label">Avatar</span>
+          {% if current_user and current_user.avatar %}
+          <span class="settings-value" style="word-break:break-all;">{{ current_user.avatar }}</span>
+          {% else %}
+          <span class="settings-empty">Not set (initials used)</span>
+          {% endif %}
+        </div>
+      </div>
+
+      <!-- Notification channels -->
+      <div class="section">
+        <h2>Notification Channels</h2>
+        {% if notification_channels %}
+        {% for ch in notification_channels %}
+        <div class="channel-row">
+          <span class="channel-type">{{ ch.type }}</span>
+          <span class="channel-name">{{ ch.name }}</span>
+        </div>
+        {% endfor %}
+        {% else %}
+        <span class="no-hosts">No personal notification channels configured.</span>
+        {% endif %}
+      </div>
+
+      <!-- Host access -->
+      <div class="section">
+        <h2>Host Access</h2>
+
+        <div class="settings-row" style="align-items: flex-start; padding-bottom: 14px;">
+          <span class="settings-label" style="padding-top: 2px;">Owner</span>
+          <div class="host-grid">
+            {% if owned_hosts %}
+            {% for h in owned_hosts %}
+            <span class="host-chip owner"><span class="host-chip-dot"></span>{{ h }}</span>
+            {% endfor %}
+            {% else %}
+            <span class="no-hosts">None</span>
+            {% endif %}
+          </div>
+        </div>
+
+        <div class="settings-row" style="align-items: flex-start; padding-bottom: 14px;">
+          <span class="settings-label" style="padding-top: 2px;">Manager</span>
+          <div class="host-grid">
+            {% if managed_hosts %}
+            {% for h in managed_hosts %}
+            <span class="host-chip manager"><span class="host-chip-dot"></span>{{ h }}</span>
+            {% endfor %}
+            {% else %}
+            <span class="no-hosts">None</span>
+            {% endif %}
+          </div>
+        </div>
+
+        <div class="settings-row" style="align-items: flex-start; padding-bottom: 4px;">
+          <span class="settings-label" style="padding-top: 2px;">Monitor</span>
+          <div class="host-grid">
+            {% if monitored_hosts %}
+            {% for h in monitored_hosts %}
+            <span class="host-chip monitor"><span class="host-chip-dot"></span>{{ h }}</span>
+            {% endfor %}
+            {% else %}
+            <span class="no-hosts">None</span>
+            {% endif %}
+          </div>
+        </div>
+      </div>
+
+    </div>
+  </body>
+</html>

hbd/server/templates/settings.html

@@ -0,0 +1,490 @@
+<!DOCTYPE html>
+<html>
+  {% include 'head.html' %}
+
+  <style>
+    html, body { overflow: visible; }
+
+    .container {
+      max-width: 960px;
+    }
+
+    h1 { color: #333; margin-bottom: 5px; margin-top: 15px; font-size: 1.5em; }
+    .subtitle { color: #666; margin-bottom: 24px; font-size: 0.9em; }
+
+    /* ---- Sidebar + content layout ---- */
+    .settings-layout {
+      display: flex;
+      gap: 24px;
+      align-items: flex-start;
+    }
+
+    .settings-sidebar {
+      width: 180px;
+      flex-shrink: 0;
+      position: sticky;
+      top: 60px;
+    }
+
+    .sidebar-nav a {
+      display: block;
+      padding: 6px 10px;
+      border-radius: 4px;
+      text-decoration: none;
+      font-size: 0.85em;
+      color: #444;
+      margin-bottom: 2px;
+      transition: background 0.1s, color 0.1s;
+    }
+    .sidebar-nav a:hover { background: #e8eaf6; color: #1a237e; }
+    .sidebar-nav a.active { background: #e3f2fd; color: #0066cc; font-weight: 600; }
+
+    .settings-main { flex: 1; min-width: 0; }
+
+    /* ---- Section card ---- */
+    .section {
+      background: #fff;
+      border-radius: 8px;
+      box-shadow: 0 1px 4px rgba(0,0,0,.08);
+      margin-bottom: 24px;
+      overflow: hidden;
+    }
+
+    .section-header {
+      padding: 14px 20px 12px;
+      border-bottom: 1px solid #eee;
+    }
+
+    .section-title {
+      font-size: 0.95em;
+      font-weight: 700;
+      color: #222;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+      margin: 0 0 3px;
+    }
+
+    .section-desc {
+      font-size: 0.82em;
+      color: #888;
+      margin: 0;
+    }
+
+    /* ---- Field rows ---- */
+    .field-row {
+      display: flex;
+      align-items: baseline;
+      padding: 10px 20px;
+      border-bottom: 1px solid #f5f5f5;
+      gap: 16px;
+    }
+    .field-row:last-child { border-bottom: none; }
+
+    .field-label {
+      width: 200px;
+      flex-shrink: 0;
+      font-size: 0.88em;
+      font-weight: 500;
+      color: #444;
+    }
+
+    .field-body { flex: 1; min-width: 0; }
+
+    .field-value {
+      font-size: 0.9em;
+      color: #222;
+      word-break: break-all;
+    }
+
+    .field-desc {
+      font-size: 0.78em;
+      color: #999;
+      margin-top: 2px;
+    }
+
+    /* ---- Value type renderers ---- */
+    .val-boolean {
+      display: inline-block;
+      padding: 2px 9px;
+      border-radius: 10px;
+      font-size: 0.8em;
+      font-weight: 600;
+    }
+    .val-boolean.on  { background: #e8f5e9; color: #2e7d32; }
+    .val-boolean.off { background: #fce4ec; color: #c62828; }
+
+    .val-masked {
+      font-family: monospace;
+      color: #bbb;
+      letter-spacing: 2px;
+    }
+
+    .val-list { display: flex; flex-wrap: wrap; gap: 5px; }
+    .val-tag {
+      display: inline-block;
+      padding: 2px 9px;
+      background: #e8eaf6;
+      color: #283593;
+      border-radius: 10px;
+      font-size: 0.8em;
+    }
+    .val-empty { color: #ccc; font-style: italic; font-size: 0.88em; }
+
+    /* ---- Users table ---- */
+    .mini-table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 0.875em;
+    }
+    .mini-table th {
+      background: #f5f5f5;
+      padding: 7px 12px;
+      text-align: left;
+      font-weight: 600;
+      color: #555;
+      font-size: 0.82em;
+      text-transform: uppercase;
+      letter-spacing: 0.4px;
+      border-bottom: 1px solid #e0e0e0;
+    }
+    .mini-table td {
+      padding: 7px 12px;
+      border-bottom: 1px solid #f0f0f0;
+      color: #333;
+      vertical-align: middle;
+    }
+    .mini-table tbody tr:last-child td { border-bottom: none; }
+    .mini-table tbody tr:hover { background: #fafafa; }
+
+    .badge {
+      display: inline-block;
+      padding: 1px 8px;
+      border-radius: 10px;
+      font-size: 0.75em;
+      font-weight: 600;
+    }
+    .badge-admin { background: #e8f0fe; color: #1a73e8; }
+    .badge-user  { background: #f1f3f4; color: #666; }
+
+    /* ---- Notification channels ---- */
+    .channel-card {
+      border: 1px solid #e8eaf6;
+      border-radius: 6px;
+      margin: 12px 20px;
+      overflow: hidden;
+    }
+
+    .channel-header {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      padding: 9px 14px;
+      background: #f8f9ff;
+      border-bottom: 1px solid #e8eaf6;
+    }
+
+    .channel-name-text { font-weight: 600; font-size: 0.9em; color: #222; }
+
+    .ch-type-badge {
+      padding: 2px 8px;
+      border-radius: 8px;
+      font-size: 0.75em;
+      font-weight: 600;
+      background: #e8eaf6;
+      color: #3949ab;
+    }
+
+    .channel-fields { padding: 6px 0; }
+
+    .channel-field {
+      display: flex;
+      padding: 5px 14px;
+      font-size: 0.85em;
+      border-bottom: 1px solid #f5f5f5;
+      gap: 12px;
+    }
+    .channel-field:last-child { border-bottom: none; }
+    .channel-field-label { width: 130px; flex-shrink: 0; color: #777; }
+    .channel-field-value { color: #333; word-break: break-all; }
+
+    /* ---- Hosts table ---- */
+    /* ---- Mobile: collapsible sidebar ---- */
+    .sidebar-toggle {
+      display: none;
+      width: 100%;
+      padding: 8px 12px;
+      background: #e8eaf6;
+      border: none;
+      border-radius: 6px;
+      font-size: 0.9em;
+      font-weight: 600;
+      color: #283593;
+      cursor: pointer;
+      text-align: left;
+      margin-bottom: 16px;
+    }
+    .sidebar-toggle::after { content: ' ▾'; float: right; }
+    .sidebar-toggle.open::after { content: ' ▴'; }
+
+    @media (max-width: 640px) {
+      .sidebar-toggle { display: block; }
+
+      .settings-layout { flex-direction: column; gap: 0; }
+
+      .settings-sidebar {
+        width: 100%;
+        position: static;
+        margin-bottom: 0;
+      }
+
+      .sidebar-nav {
+        display: none;
+        background: white;
+        border-radius: 6px;
+        box-shadow: 0 1px 4px rgba(0,0,0,.1);
+        margin-bottom: 16px;
+        padding: 4px 0;
+      }
+      .sidebar-nav.open { display: block; }
+      .sidebar-nav a { padding: 10px 16px; font-size: 1em; }
+
+      .field-row { flex-direction: column; gap: 4px; }
+      .field-label { width: 100%; font-size: 0.82em; color: #888; }
+    }
+    .host-bool { text-align: center; }
+    .dot-yes { color: #2e7d32; font-size: 1.1em; }
+    .dot-no  { color: #ddd;    font-size: 1.1em; }
+  </style>
+
+  <body>
+    {% include 'nav.html' %}
+
+    <div class="container">
+      <h1>Settings</h1>
+      <p class="subtitle">Current server configuration — read from the config file at startup.</p>
+
+      <div class="settings-layout">
+
+        <!-- Sidebar navigation -->
+        <nav class="settings-sidebar">
+          <button class="sidebar-toggle" id="sidebar-toggle" aria-expanded="false">Sections</button>
+          <div class="sidebar-nav" id="sidebar-nav">
+            {% for section in sections %}
+            <a href="#{{ section.id }}" onclick="closeSidebar()">{{ section.title }}</a>
+            {% endfor %}
+          </div>
+        </nav>
+
+        <!-- Main content -->
+        <div class="settings-main">
+          {% for section in sections %}
+          <div class="section" id="{{ section.id }}">
+            <div class="section-header">
+              <p class="section-title">{{ section.title }}</p>
+              {% if section.description %}<p class="section-desc">{{ section.description }}</p>{% endif %}
+            </div>
+
+            {# ---- Standard field rows ---- #}
+            {% for f in section.fields %}
+            <div class="field-row">
+              <div class="field-label">{{ f.label }}</div>
+              <div class="field-body">
+                {% if f.sensitive %}
+                  <div class="field-value"><span class="val-masked">••••••••</span></div>
+                {% elif f.type == "boolean" %}
+                  <div class="field-value">
+                    <span class="val-boolean {{ 'on' if f.value else 'off' }}">
+                      {{ 'Enabled' if f.value else 'Disabled' }}
+                    </span>
+                  </div>
+                {% elif f.type == "list" %}
+                  <div class="field-value">
+                    {% if f.value %}
+                    <span class="val-list">
+                      {% for item in f.value %}<span class="val-tag">{{ item }}</span>{% endfor %}
+                    </span>
+                    {% else %}
+                    <span class="val-empty">None</span>
+                    {% endif %}
+                  </div>
+                {% elif f.value is none or f.value == "" %}
+                  <div class="field-value"><span class="val-empty">Not set</span></div>
+                {% else %}
+                  <div class="field-value">{{ f.value }}</div>
+                {% endif %}
+                {% if f.description %}
+                <div class="field-desc">{{ f.description }}</div>
+                {% endif %}
+              </div>
+            </div>
+            {% endfor %}
+
+            {# ---- Users section ---- #}
+            {% if section.id == "users" and section.users %}
+            <div style="padding: 0 0 4px;">
+              <table class="mini-table">
+                <thead>
+                  <tr>
+                    <th>Username</th>
+                    <th>Full Name</th>
+                    <th>Role</th>
+                    <th>Avatar</th>
+                    <th>Channels</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {% for u in section.users %}
+                  <tr>
+                    <td><strong>{{ u.username }}</strong></td>
+                    <td>{{ u.full_name or '—' }}</td>
+                    <td>
+                      {% if u.admin %}
+                      <span class="badge badge-admin">Admin</span>
+                      {% else %}
+                      <span class="badge badge-user">User</span>
+                      {% endif %}
+                    </td>
+                    <td style="font-size:0.8em; color:#888;">
+                      {% if u.avatar %}{{ u.avatar }}{% else %}—{% endif %}
+                    </td>
+                    <td>
+                      {% if u.notification_channels %}
+                      <span class="val-list">
+                        {% for ch in u.notification_channels %}
+                        <span class="val-tag">{{ ch }}</span>
+                        {% endfor %}
+                      </span>
+                      {% else %}—{% endif %}
+                    </td>
+                  </tr>
+                  {% endfor %}
+                </tbody>
+              </table>
+            </div>
+            {% endif %}
+
+            {# ---- Notification channels section ---- #}
+            {% if section.id == "channels" %}
+            {% for ch in section.channels %}
+            <div class="channel-card">
+              <div class="channel-header">
+                <span class="channel-name-text">{{ ch.name }}</span>
+                <span class="ch-type-badge">{{ ch.type_label }}</span>
+              </div>
+              <div class="channel-fields">
+                {% for cf in ch.fields %}
+                <div class="channel-field">
+                  <span class="channel-field-label">{{ cf.label }}</span>
+                  <span class="channel-field-value">
+                    {% if cf.sensitive %}
+                    <span class="val-masked">••••••••</span>
+                    {% elif cf.value is iterable and cf.value is not string %}
+                    {{ cf.value | join(', ') }}
+                    {% else %}
+                    {{ cf.value }}
+                    {% endif %}
+                  </span>
+                </div>
+                {% endfor %}
+              </div>
+            </div>
+            {% endfor %}
+            {% if not section.channels %}
+            <div class="field-row"><span class="val-empty">No notification channels configured.</span></div>
+            {% endif %}
+            {% endif %}
+
+            {# ---- Hosts section ---- #}
+            {% if section.id == "hosts" %}
+            {% if section.hosts %}
+            <div style="overflow-x: auto;">
+              <table class="mini-table">
+                <thead>
+                  <tr>
+                    <th>Host</th>
+                    <th>Watch</th>
+                    <th>DynDNS</th>
+                    <th>Owner</th>
+                    <th>Threshold config</th>
+                    <th>Channels</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {% for h in section.hosts %}
+                  <tr>
+                    <td><strong>{{ h.name }}</strong></td>
+                    <td class="host-bool">
+                      <span class="{{ 'dot-yes' if h.watch else 'dot-no' }}">●</span>
+                    </td>
+                    <td class="host-bool">
+                      <span class="{{ 'dot-yes' if h.dyndns else 'dot-no' }}">●</span>
+                    </td>
+                    <td>{{ h.owner or '—' }}</td>
+                    <td>{{ h.threshold_config or '—' }}</td>
+                    <td>
+                      {% if h.notification_channels %}
+                      <span class="val-list">
+                        {% for ch in h.notification_channels %}
+                        <span class="val-tag">{{ ch }}</span>
+                        {% endfor %}
+                      </span>
+                      {% else %}—{% endif %}
+                    </td>
+                  </tr>
+                  {% endfor %}
+                </tbody>
+              </table>
+            </div>
+            {% else %}
+            <div class="field-row"><span class="val-empty">No hosts defined in config.</span></div>
+            {% endif %}
+            {% endif %}
+
+          </div>{# /section #}
+          {% endfor %}
+        </div>{# /settings-main #}
+      </div>{# /settings-layout #}
+    </div>{# /container #}
+
+    <script>
+      // Highlight sidebar link for the section currently in view
+      const sections = document.querySelectorAll('.section');
+      const navLinks = document.querySelectorAll('.sidebar-nav a');
+
+      const observer = new IntersectionObserver(entries => {
+        entries.forEach(entry => {
+          if (entry.isIntersecting) {
+            const id = entry.target.id;
+            navLinks.forEach(a => {
+              a.classList.toggle('active', a.getAttribute('href') === '#' + id);
+            });
+          }
+        });
+      }, { threshold: 0.25 });
+
+      sections.forEach(s => observer.observe(s));
+
+      // Collapsible sidebar on mobile
+      var sidebarToggle = document.getElementById('sidebar-toggle');
+      var sidebarNav = document.getElementById('sidebar-nav');
+      if (sidebarToggle && sidebarNav) {
+        sidebarToggle.addEventListener('click', function() {
+          var open = sidebarNav.classList.toggle('open');
+          sidebarToggle.classList.toggle('open', open);
+          sidebarToggle.setAttribute('aria-expanded', open ? 'true' : 'false');
+        });
+      }
+    </script>
+    <script>
+      function closeSidebar() {
+        var sidebarNav = document.getElementById('sidebar-nav');
+        var sidebarToggle = document.getElementById('sidebar-toggle');
+        if (sidebarNav) { sidebarNav.classList.remove('open'); }
+        if (sidebarToggle) {
+          sidebarToggle.classList.remove('open');
+          sidebarToggle.setAttribute('aria-expanded', 'false');
+        }
+      }
+    </script>
+  </body>
+</html>

hbd/server/threshold.py

@@ -14,6 +14,7 @@ import time
 from enum import Enum
 from typing import Dict, Any, Optional, Tuple, Callable
 from . import notify as notify_mod
+from .config import THRESHOLD_DEFAULTS
 
 logger = logging.getLogger(__name__)
 eventlog = notify_mod.eventlog
@@ -58,6 +59,8 @@ class AlertState:
         self.formatted_message = None  # Formatted display message for UI
         self.acknowledged = False  # Whether alert has been acknowledged
         self.acknowledged_at = None  # Timestamp when acknowledged
+        self.consecutive_count = 0  # Consecutive exceedances while still OK (for count gating)
+        self.pending_since: Optional[float] = None  # non-None while waiting out grace period before notifying
     
     def update(
         self, 
@@ -103,6 +106,7 @@ class AlertState:
             self.level = level
             self.since = now
             self.notification_count = 0
+            self.last_notification = None  # restart reminder interval on level change
             # Reset acknowledgment on state change
             if level != AlertLevel.OK:
                 # Only reset if changing to a different alert level
@@ -118,7 +122,10 @@ class AlertState:
         
         # Helper to sanitize numeric values for JSON (handle inf/nan)
         def sanitize_value(val):
-            if isinstance(val, float) and (math.isinf(val) or math.isnan(val)):
+            if isinstance(val, float):
+                if math.isinf(val):
+                    return "overdue"
+                if math.isnan(val):
                     return None
             return val
         
@@ -146,6 +153,12 @@ class AlertState:
         
         return result
     
+    def __setstate__(self, state):
+        """Restore from pickle, backfilling fields added after the pickle was written."""
+        self.__dict__.update(state)
+        if not hasattr(self, 'consecutive_count'):
+            self.consecutive_count = 0
+
     def acknowledge(self):
         """Acknowledge this alert to stop reminder notifications."""
         self.acknowledged = True
@@ -167,6 +180,7 @@ class ThresholdConfig:
         operator: str = ">",
         hysteresis: float = 0.0,
         enabled: bool = True,
+        count: int = 1,
     ):
         """
         Initialize threshold configuration.
@@ -178,6 +192,7 @@ class ThresholdConfig:
             operator: Comparison operator (>, >=, <, <=, ==, !=)
             hysteresis: Hysteresis percentage to prevent flapping (0.0-1.0)
             enabled: Whether this threshold is enabled
+            count: Number of consecutive exceedances required before alerting (default 1)
         """
         self.metric_path = metric_path
         self.warning = warning
@@ -185,6 +200,7 @@ class ThresholdConfig:
         self.enabled = enabled
         self.hysteresis = hysteresis
         self.display = display
+        self.count = max(1, int(count))
         
         # Parse operator
         try:
@@ -325,6 +341,7 @@ class ThresholdChecker:
         self.default_config = "default"
         
         self.renotify_interval = renotify_interval
+        self.grace_seconds: float = float(config.get("grace", 2))
         self.journal = journal
 
         # Parse configuration
@@ -357,6 +374,7 @@ class ThresholdChecker:
         self.threshold_configs.clear()
         self.thresholds.clear()
         self.host_config_mapping.clear()
+        self.grace_seconds = float(config.get("grace", 2))
 
         # Parse new configuration
         self._parse_config(config)
@@ -391,8 +409,28 @@ class ThresholdChecker:
             logger.info("No threshold configurations defined")
             return
 
-        # Parse each named configuration
+        # Build effective_defaults: THRESHOLD_DEFAULTS merged with the 'default' config (if present).
+        # All other configs inherit any metric not explicitly defined from effective_defaults.
+        effective_defaults: Dict[str, ThresholdConfig] = {}
+        for plugin_name, plugin_thresholds in THRESHOLD_DEFAULTS.get("thresholds", {}).items():
+            if isinstance(plugin_thresholds, dict):
+                self._parse_plugin_thresholds(plugin_name, plugin_thresholds, target_dict=effective_defaults)
+
+        if "default" in threshold_configs:
+            default_data = threshold_configs["default"]
+            if isinstance(default_data, dict) and "thresholds" in default_data:
+                for plugin_name, plugin_thresholds in default_data["thresholds"].items():
+                    if isinstance(plugin_thresholds, dict):
+                        self._parse_plugin_thresholds(plugin_name, plugin_thresholds, target_dict=effective_defaults)
+
+        self.threshold_configs["default"] = dict(effective_defaults)
+        logger.info("Registered 'default' threshold config with %d metrics", len(effective_defaults))
+
+        # Parse each named configuration, seeding it with effective_defaults first
         for config_name, config_data in threshold_configs.items():
+            if config_name == "default":
+                continue  # already handled above
+
             if not isinstance(config_data, dict):
                 logger.warning("Invalid threshold config '%s', skipping", config_name)
                 continue
@@ -402,7 +440,7 @@ class ThresholdChecker:
                 continue
 
             logger.info("Parsing threshold configuration: %s", config_name)
-            self.threshold_configs[config_name] = {}
+            self.threshold_configs[config_name] = dict(effective_defaults)
 
             thresholds_config = config_data["thresholds"]
             for plugin_name, plugin_thresholds in thresholds_config.items():
@@ -600,6 +638,7 @@ class ThresholdChecker:
         hysteresis = rtt_thresholds.get("hysteresis", 0.1)  # 10% default
         enabled = rtt_thresholds.get("enabled", True)
         display = rtt_thresholds.get("display")
+        count = rtt_thresholds.get("count", 1)
 
         if warning is None and critical is None:
             logger.warning("No RTT thresholds defined, skipping")
@@ -612,14 +651,16 @@ class ThresholdChecker:
             operator=operator,
             hysteresis=hysteresis,
             enabled=enabled,
-            display=display
+            display=display,
+            count=count,
         )
 
         target_dict[metric_path] = threshold
         logger.debug(
-            "Registered RTT threshold: warn=%s ms, crit=%s ms",
+            "Registered RTT threshold: warn=%s ms, crit=%s ms, count=%d",
             warning,
-            critical
+            critical,
+            count,
         )
     
     def get_thresholds_for_host(self, host_name: str) -> Dict[str, ThresholdConfig]:
@@ -692,6 +733,26 @@ class ThresholdChecker:
             alert_state.level
         )
 
+        # Apply consecutive-count gating: when currently OK, require threshold.count
+        # consecutive exceedances before escalating to WARNING/CRITICAL.
+        if new_level == AlertLevel.OK:
+            # Value is fine (or recovered) — reset the pending counter immediately.
+            alert_state.consecutive_count = 0
+        elif alert_state.level == AlertLevel.OK and new_level != AlertLevel.OK:
+            # First time we exceed while still OK: count up.
+            alert_state.consecutive_count += 1
+            if alert_state.consecutive_count < threshold.count:
+                logger.debug(
+                    "RTT threshold exceeded %d/%d consecutive times for %s on %s",
+                    alert_state.consecutive_count,
+                    threshold.count,
+                    metric_path,
+                    host_name,
+                )
+                return None
+            # Count reached — fire the alert and reset the counter.
+            alert_state.consecutive_count = 0
+
         # Determine which threshold was exceeded
         threshold_value = None
         if new_level == AlertLevel.CRITICAL and threshold.critical is not None:
@@ -702,15 +763,10 @@ class ThresholdChecker:
         # Update state and check for changes
         old_level = alert_state.level
         if alert_state.update(new_level, value, threshold_value, threshold.operator.value):
-            # For check_value, we don't have full plugin data, pass None
+            self._apply_grace(host_name, alert_state, metric_path, old_level, new_level, value, threshold, None)
-            lvl, message, formatted_msg = self._trigger_notification(host_name, metric_path, old_level, new_level, value, threshold, None)
-            # Update alert state with formatted message
-            alert_state.formatted_message = formatted_msg
-            self._send_notification(host_name, lvl, message, metric_path, old_level, new_level, value)
             return (old_level, new_level)
         elif new_level != AlertLevel.OK:
-            # Check if we should re-notify
+            self._check_pending_or_renotify(host_name, alert_state, metric_path, value, threshold, None)
-            self._check_renotify(host_name, alert_state, metric_path, value, threshold, None)
 
         return None
     def check_plugin_data(
@@ -769,13 +825,9 @@ class ThresholdChecker:
             old_level = alert_state.level
             if alert_state.update(new_level, value, threshold_value, threshold.operator.value):
                 state_changes.append((metric_path, old_level, new_level, value))
-                lvl, message, formatted_msg = self._trigger_notification(host_name, metric_path, old_level, new_level, value, threshold, data)
+                self._apply_grace(host_name, alert_state, metric_path, old_level, new_level, value, threshold, data)
-                # Update alert state with formatted message
-                alert_state.formatted_message = formatted_msg
-                self._send_notification(host_name, lvl, message, metric_path, old_level, new_level, value)
             elif new_level != AlertLevel.OK:
-                # Check if we should re-notify
+                self._check_pending_or_renotify(host_name, alert_state, metric_path, value, threshold, data)
-                self._check_renotify(host_name, alert_state, metric_path, value, threshold, data)
 
         # Check nested metrics (e.g., partition data in disk_monitor)
         self._check_nested_metrics(
@@ -838,20 +890,9 @@ class ThresholdChecker:
                     old_level = alert_state.level
                     if alert_state.update(new_level, value, threshold_value, threshold.operator.value):
                         state_changes.append((metric_path, old_level, new_level, value))
-                        lvl, message, formatted_msg = self._trigger_notification(
+                        self._apply_grace(host_name, alert_state, metric_path, old_level, new_level, value, threshold, data)
-                            host_name,
-                            metric_path,
-                            old_level,
-                            new_level,
-                            value,
-                            threshold,
-                            data  # Pass full plugin data for format string
-                        )
-                        # Update alert state with formatted message
-                        alert_state.formatted_message = formatted_msg
-                        self._send_notification(host_name, lvl, message, metric_path, old_level, new_level, value)
                     elif new_level != AlertLevel.OK:
-                        self._check_renotify(host_name, alert_state, metric_path, value, threshold, data)
+                        self._check_pending_or_renotify(host_name, alert_state, metric_path, value, threshold, data)
     
     def _trigger_notification(
         self,
@@ -884,48 +925,50 @@ class ThresholdChecker:
         # Format operator symbol
         op_symbol = threshold.operator.value
         
+        # Use a display-friendly value (inf is the sentinel for "overdue")
+        import math
+        display_value = "overdue" if isinstance(value, float) and math.isinf(value) else value
+
         # Format message
         if new_level == AlertLevel.OK:
-            lvl = "RECOVERED" 
+            lvl = "RECOVER"
-            message = f"{metric_path} = {value} ({old_level.name} -> OK)"
+            message = f"{metric_path} = {display_value} ({old_level.name} -> OK)"
         elif new_level == AlertLevel.WARNING:
             lvl = "WARNING"
             if threshold_value is not None:
-                # Use display format string
                 threshold_info = self._format_display(
                     threshold.display,
-                    value=value,
+                    value=display_value,
                     threshold_value=threshold_value,
                     op_symbol=op_symbol,
                     plugin_data=plugin_data
                 )
-                message = f"{metric_path} = {value} {threshold_info}"
+                message = f"{metric_path} = {display_value} {threshold_info}"
             else:
-                message = f"{metric_path} = {value}"
+                message = f"{metric_path} = {display_value}"
         elif new_level == AlertLevel.CRITICAL:
             lvl = "CRITICAL"
             if threshold_value is not None:
-                # Use display format string
                 threshold_info = self._format_display(
                     threshold.display,
-                    value=value,
+                    value=display_value,
                     threshold_value=threshold_value,
                     op_symbol=op_symbol,
                     plugin_data=plugin_data
                 )
-                message = f"{metric_path} = {value} {threshold_info}"
+                message = f"{metric_path} = {display_value} {threshold_info}"
             else:
-                message = f"{metric_path} = {value}"
+                message = f"{metric_path} = {display_value}"
         else:
             lvl = "UNKNOWN"
-            message = f"{metric_path} = {value}"
+            message = f"{metric_path} = {display_value}"
         
         # Return the formatted threshold info for storing in AlertState
         formatted_threshold_msg = None
         if threshold_value is not None and new_level != AlertLevel.OK:
             formatted_threshold_msg = self._format_display(
                 threshold.display,
-                value=value,
+                value=display_value,
                 threshold_value=threshold_value,
                 op_symbol=op_symbol,
                 plugin_data=plugin_data
@@ -944,12 +987,14 @@ class ThresholdChecker:
         value: Any,
     ):
         """Send notification and log to journal/eventlog."""
-        # Send notification using host-specific channels
+        asyncio.get_event_loop().create_task(notify_mod.send_notification(
-        try:
+            host_name,
-            notify_mod.pushmsg_for_host(host_name, f"{lvl}: {host_name} - {message}")
+            notify_mod.Notification(
-            logger.info("Notification sent: %s", message)
+                title=f"[{lvl}] {host_name}",
-        except Exception as e:
+                body=message,
-            logger.error("Failed to send notification: %s", e)
+                level=lvl,
+            ),
+        ))
         
         # Log to journal
         if self.journal is not None:
@@ -1018,6 +1063,74 @@ class ThresholdChecker:
             )
             return f"(threshold: {op_symbol} {threshold_value})"
     
+    def _apply_grace(
+        self,
+        host_name: str,
+        alert_state: AlertState,
+        metric_path: str,
+        old_level: AlertLevel,
+        new_level: AlertLevel,
+        value: Any,
+        threshold: ThresholdConfig,
+        plugin_data: Optional[Dict[str, Any]],
+    ) -> None:
+        """Handle a state-change transition with grace-period logic.
+
+        Transitioning INTO alert: defers the notification for grace_seconds.
+        Transitioning TO OK:
+          - Still in grace window (pending_since set): suppresses both the alert
+            and the recovery — the spike never warranted a page.
+          - Past grace: fires the RECOVER notification normally.
+        """
+        lvl, message, formatted_msg = self._trigger_notification(
+            host_name, metric_path, old_level, new_level, value, threshold, plugin_data
+        )
+        alert_state.formatted_message = formatted_msg
+
+        if new_level == AlertLevel.OK:
+            if alert_state.pending_since is not None:
+                logger.info(
+                    "Alert suppressed (recovered within %.0fs grace): %s on %s",
+                    self.grace_seconds, metric_path, host_name,
+                )
+                alert_state.pending_since = None
+            else:
+                self._send_notification(host_name, lvl, message, metric_path, old_level, new_level, value)
+        else:
+            alert_state.pending_since = time.time()
+            logger.debug(
+                "Alert deferred (%.0fs grace): %s on %s = %s",
+                self.grace_seconds, metric_path, host_name, value,
+            )
+
+    def _check_pending_or_renotify(
+        self,
+        host_name: str,
+        alert_state: AlertState,
+        metric_path: str,
+        value: Any,
+        threshold: ThresholdConfig,
+        plugin_data: Optional[Dict[str, Any]],
+    ) -> None:
+        """Called when alert level is unchanged and non-OK.
+
+        If a deferred notification is pending and grace_seconds have elapsed,
+        fires it now. Otherwise falls through to normal reminder logic.
+        """
+        if alert_state.pending_since is not None:
+            if time.time() - alert_state.pending_since >= self.grace_seconds:
+                lvl, message, formatted_msg = self._trigger_notification(
+                    host_name, metric_path, AlertLevel.OK, alert_state.level, value, threshold, plugin_data
+                )
+                alert_state.formatted_message = formatted_msg
+                self._send_notification(
+                    host_name, lvl, message, metric_path, AlertLevel.OK, alert_state.level, value
+                )
+                alert_state.pending_since = None
+            # else: still within grace window, do nothing
+        else:
+            self._check_renotify(host_name, alert_state, metric_path, value, threshold, plugin_data)
+
     def _check_renotify(
         self,
         host_name: str,
@@ -1037,7 +1150,7 @@ class ThresholdChecker:
             threshold: Threshold configuration
             plugin_data: Optional dictionary of all plugin data fields
         """
-        if alert_state.level == AlertLevel.OK:
+        if alert_state.level != AlertLevel.CRITICAL:
             return
 
         # Skip reminders if alert has been acknowledged
@@ -1078,14 +1191,17 @@ class ThresholdChecker:
             else:
                 message = f"REMINDER ({alert_state.level.name}): {host_name} - {metric_path} = {value} (ongoing for {int(now - alert_state.since)}s)"
             
-            # Send re-notification using host-specific channels
+            asyncio.get_event_loop().create_task(notify_mod.send_notification(
-            try:
+                host_name,
-                notify_mod.pushmsg_for_host(host_name, message)
+                notify_mod.Notification(
+                    title=f"[REMINDER/{alert_state.level.name}] {host_name}",
+                    body=message,
+                    level=alert_state.level.name,
+                ),
+            ))
             alert_state.last_notification = now
             alert_state.notification_count += 1
             logger.info("Re-notification sent: %s", message)
-            except Exception as e:
-                logger.error("Failed to send re-notification: %s", e)
     
     def get_active_alerts(self, alert_states: Dict[str, AlertState]) -> list:
         """

hbd/server/udp.py

@@ -1,9 +1,14 @@
 """UDP listener and datagram processing."""
 
 import asyncio
+import socket
+import struct
+import time
 import zlib
 import logging
 
+from platform import system as platform_system
+
 from ..common.proto import stodict, oldmtodict
 from ..common.utils import dur
 from . import notify as notify_mod
@@ -11,6 +16,108 @@ from . import notify as notify_mod
 logger = logging.getLogger(__name__)
 eventlog = notify_mod.eventlog
 
+# SO_TIMESTAMP: kernel attaches a struct timeval to each received datagram.
+# Supported on Linux, FreeBSD, and macOS.  The constant is not exposed by
+# Python's socket module on all platforms 
+platform = platform_system()
+if platform == "Darwin":
+    _SO_TIMESTAMP = 1024  # SO_TIMESTAMP on macOS (not in Python's socket module)
+elif platform == "Linux":
+    _SO_TIMESTAMP = 29  # Linux value (not in older Python versions)
+elif platform == "FreeBSD":
+     _SO_TIMESTAMP = 32  # FreeBSD value (not in older Python versions)
+else:
+    logger.warning("SO_TIMESTAMP may not be supported on this platform (%s)", platform)
+    _SO_TIMESTAMP = None
+
+# struct timeval uses two native C longs: tv_sec and tv_usec
+_TIMEVAL = struct.Struct('@ll')
+
+
+def enable_kernel_timestamps(sock) -> bool:
+    """Try to enable SO_TIMESTAMP on *sock*.
+
+    Returns True if the kernel will supply receive timestamps, False otherwise
+    (unsupported platform, older kernel, or insufficient permissions).
+    """
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, _SO_TIMESTAMP, 1)
+        return True
+    except OSError:
+        return False
+
+
+def _extract_kernel_ts(ancdata) -> float | None:
+    """Parse recvmsg ancillary data and return the kernel receive time.
+
+    Returns seconds as a float, or None if no SO_TIMESTAMP cmsg is present.
+    """
+    for cmsg_level, cmsg_type, cmsg_data in ancdata:
+        if cmsg_level == socket.SOL_SOCKET and cmsg_type == _SO_TIMESTAMP:
+            if len(cmsg_data) >= _TIMEVAL.size:
+                sec, usec = _TIMEVAL.unpack_from(cmsg_data)
+                return sec + usec * 1e-6
+    return None
+
+
+class RecvmsgTransport:
+    """Thin wrapper used when SO_TIMESTAMP is active (add_reader path).
+
+    Exposes the same sendto() / close() interface as asyncio's DatagramTransport
+    so the rest of the code does not need to know which path is in use.
+    """
+    def __init__(self, loop, sock):
+        self._loop = loop
+        self._sock = sock
+
+    def sendto(self, data, addr):
+        try:
+            self._sock.sendto(data, addr)
+        except Exception as e:
+            logger.debug("sendto failed: %s", e)
+
+    def close(self):
+        try:
+            self._loop.remove_reader(self._sock.fileno())
+        except Exception:
+            pass
+        try:
+            self._sock.close()
+        except Exception:
+            pass
+
+
+def make_recvmsg_reader(sock, handler, transport):
+    """Return a callback suitable for loop.add_reader().
+
+    Reads one datagram per call using recvmsg() so that kernel timestamps in
+    the ancillary data are accessible.  Falls back to time.time() if the
+    cmsg is missing.
+
+    handler(msg, addr, transport, kernel_ts) – same signature as udp_handler
+    in main.py with the optional kernel_ts argument.
+    """
+    BUFSIZE = 65536
+    ANCBUFSIZE = 128  # enough for one struct timespec cmsg
+
+    def _read():
+        try:
+            data, ancdata, _, addr = sock.recvmsg(BUFSIZE, ANCBUFSIZE)
+        except BlockingIOError:
+            return
+        except OSError as e:
+            logger.warning("recvmsg error: %s", e)
+            return
+        try:
+            kernel_ts = _extract_kernel_ts(ancdata)
+            msg = parse_message(data)
+            if msg:
+                handler(msg, addr, transport, kernel_ts)
+        except Exception:
+            logger.exception("Error processing datagram from %s", addr)
+
+    return _read
+
 
 class EchoServerProtocol(asyncio.DatagramProtocol):
     def __init__(self, config=None, handler=None):
@@ -61,6 +168,125 @@ def dicttos(ID, d):
     return opk
 
 
+DROPOVERDUE = 7 * 24 * 3600  # seconds before an overdue host becomes UNKNOWN
+
+
+def _set_connectivity_alert(host, afam, level_name):
+    """Update (or clear) a connectivity alert_state entry for a host/address-family.
+
+    level_name is "CRITICAL", "WARNING", or "OK".  "OK" removes the entry so
+    that recovered hosts don't clutter the Alerts Dashboard.
+    """
+    from .threshold import AlertState, AlertLevel
+    metric_path = f"connectivity.{afam}"
+    level = getattr(AlertLevel, level_name, AlertLevel.OK)
+    if level == AlertLevel.OK:
+        host.alert_states.pop(metric_path, None)
+        return
+    if metric_path not in host.alert_states:
+        host.alert_states[metric_path] = AlertState(metric_path)
+    state = host.alert_states[metric_path]
+    state.update(level, level_name)
+
+
+def _make_timer_callbacks(uname, host, ctx):
+    """Return (on_overdue, on_unknown) async callbacks for connection timer logic.
+
+    Captured values are bound at call time so callbacks are safe to use in loops.
+    """
+    msg_to_websockets = ctx.get("msg_to_websockets")
+    threshold_checker = ctx.get("threshold_checker")
+    cfg = ctx.get("config", {})
+
+    async def on_unknown(connection):
+        connection.newstate(connection.__class__.UNKNOWN, connection.lastbeat)
+        # Keep connectivity alert active when host transitions to unknown
+        if msg_to_websockets:
+            msg_to_websockets("host", host.stateinfo())
+
+    async def on_overdue(connection):
+        if connection.getstate() != connection.__class__.UP:
+            return
+        now = time.time()
+        connection.newstate(connection.__class__.OVERDUE, now, cfg.get("grace", 2))
+        msg = f"{connection.afam} overdue"
+        eventlog(uname, "CRITICAL", msg)
+        asyncio.create_task(notify_mod.send_notification(
+            uname,
+            notify_mod.Notification(title=f"[CRITICAL] {uname}", body=msg, level="CRITICAL"),
+        ))
+        # Track in alert_states so the Alerts Dashboard shows this
+        _set_connectivity_alert(host, connection.afam, "CRITICAL")
+        if threshold_checker:
+            threshold_checker.check_value(
+                host_name=uname,
+                metric_path="rtt",
+                value=float("inf"),
+                alert_states=host.alert_states,
+            )
+        if msg_to_websockets:
+            msg_to_websockets("host", host.stateinfo())
+        connection.reset_overdue_timer(DROPOVERDUE, on_unknown)
+
+    return on_overdue, on_unknown
+
+
+def restore_connection_timers(hbdclass, ctx):
+    """Restore overdue timers for all loaded connections after a pickle restore.
+
+    For UP connections, the remaining time until overdue is calculated from
+    lastbeat so that clients that vanished during hbd's downtime are detected.
+    For OVERDUE connections, the UNKNOWN drop timer is restored.
+    """
+    now = time.time()
+    cfg = ctx.get("config", {})
+    grace = cfg.get("grace", 2)
+
+    restored = 0
+    for uname, host in list(hbdclass.Host.hosts.items()):
+        interval = host.interval
+        for afam, conn in list(host.connections.items()):
+            state = conn.getstate()
+            if state == hbdclass.Connection.DOWN:
+                continue
+
+            on_overdue, on_unknown = _make_timer_callbacks(uname, host, ctx)
+
+            if state == hbdclass.Connection.UP and interval > 0:
+                elapsed = now - conn.lastbeat
+                # Give hosts one full (interval + grace) of extra time on startup
+                # so hosts that were silent while hbd was down are not immediately
+                # flagged as overdue before they have a chance to check in.
+                startup_grace = interval + grace
+                remaining = max(startup_grace, 2 * startup_grace - elapsed)
+                conn.reset_overdue_timer(remaining, on_overdue)
+                logger.debug(
+                    "Restored UP timer %s/%s: %.0fs remaining (elapsed %.0fs, startup grace %.0fs)",
+                    uname, afam, remaining, elapsed, startup_grace,
+                )
+                restored += 1
+
+            elif state == hbdclass.Connection.OVERDUE:
+                elapsed_overdue = now - conn.statetime
+                remaining = DROPOVERDUE - elapsed_overdue
+                if remaining <= 1:
+                    # Already past the drop window — mark UNKNOWN immediately
+                    conn.newstate(hbdclass.Connection.UNKNOWN, conn.lastbeat)
+                    logger.info(
+                        "Marking %s/%s UNKNOWN (overdue %.1f days)",
+                        uname, afam, elapsed_overdue / 86400,
+                    )
+                else:
+                    conn.reset_overdue_timer(remaining, on_unknown)
+                    logger.debug(
+                        "Restored OVERDUE timer %s/%s: %.0fs remaining",
+                        uname, afam, remaining,
+                    )
+                restored += 1
+
+    logger.info("Restored timers for %d connection(s)", restored)
+
+
 def handle_datagram(msg: dict, addr, transport, ctx: dict):
     """Handle a parsed datagram message.
 
@@ -74,7 +300,7 @@ def handle_datagram(msg: dict, addr, transport, ctx: dict):
     """
     if not msg:
         return
-    now = __import__("time").time()
+    now = ctx.get("recv_ts") or time.time()
     
     # Log message to journal
     msg_journal = ctx.get("msg_journal")
@@ -89,7 +315,6 @@ def handle_datagram(msg: dict, addr, transport, ctx: dict):
     
     cfg = ctx.get("config", {})
     hbdcls = ctx.get("hbdclass")
-    log = ctx.get("log")
     msg_to_websockets = ctx.get("msg_to_websockets")
     DEBUG = ctx.get("DEBUG", 0)
     verbose = ctx.get("verbose", False)
@@ -107,6 +332,9 @@ def handle_datagram(msg: dict, addr, transport, ctx: dict):
         # Use new config function to check dyndns
         dyndnshosts = config_mod.get_dyndnshosts(cfg)
         host.dyn = uname in dyndnshosts
+        # Apply user-access settings from config
+        access = config_mod.get_host_access(cfg, uname)
+        host.apply_access(access["owner"], access["managers"], access["monitors"])
         if verbose:
             print(("XX: New host, num now %s" % (len(hbdcls.Host.hosts))))
         newh = True
@@ -114,9 +342,6 @@ def handle_datagram(msg: dict, addr, transport, ctx: dict):
         host = hbdcls.Host.hosts[uname]
         newh = False
     
-    # Get watchhosts once for use throughout message handling
-    watchhosts = config_mod.get_watchhosts(cfg)
-
     cid = msg.get("id", 0)
     try:
         rtt = float(msg.get("rtt"))
@@ -126,7 +351,7 @@ def handle_datagram(msg: dict, addr, transport, ctx: dict):
     if msg.get("ID") == "HTB":
         host.doesack = msg.get("acks", -1)
         # send ACK back
-        rmsg = {"time": __import__("time").time()}
+        rmsg = {"time": time.time()}
         opkt = dicttos("ACK", rmsg)
         try:
             transport.sendto(opkt, addr)
@@ -138,8 +363,9 @@ def handle_datagram(msg: dict, addr, transport, ctx: dict):
         # Handle plugin data message
         plugin_name = msg.get("plugin")
         if plugin_name:
-            # Extract all fields except ID and plugin name
+            # Extract plugin fields, dropping protocol metadata fields
-            plugin_data = {k: v for k, v in msg.items() if k not in ["ID", "plugin"]}
+            plugin_data = {k: v for k, v in msg.items()
+                           if k not in ("ID", "plugin", "id", "name")}
             # Store plugin data with timestamp
             host.add_plugin_data(plugin_name, plugin_data, timestamp=now)
             if DEBUG > 1:
@@ -181,8 +407,10 @@ def handle_datagram(msg: dict, addr, transport, ctx: dict):
 
     if res:
         eventlog(uname, "WARNING", res)
-        if uname in watchhosts:
+        asyncio.create_task(notify_mod.send_notification(
-            notify_mod.pushmsg_for_host(uname, "%s %s" % (host.name, res))
+            uname,
+            notify_mod.Notification(title=f"[WARNING] {uname}", body=res, level="WARNING"),
+        ))
 
     interval = int(msg.get("interval", 0) or 0)
     shutdown = msg.get("shutdown", 0)
@@ -192,24 +420,30 @@ def handle_datagram(msg: dict, addr, transport, ctx: dict):
 
     if boot:
         eventlog(uname, "INFO", "booted")
-        if uname in watchhosts:
+        asyncio.create_task(notify_mod.send_notification(
-            m = "%s booted" % (host.name)
+            uname,
-            notify_mod.pushmsg_for_host(uname, m)
+            notify_mod.Notification(title=f"[INFO] {uname}", body=f"{host.name} booted", level="INFO"),
+        ))
     if message:
         eventlog(uname, "INFO", "msg: %s" % message, service=service)
-        if uname in watchhosts:
-            notify_mod.pushmsg_for_host(uname, message)
 
     if conn.getstate() != hbdcls.Connection.UP:
         lasts = conn.state
         d = conn.newstate(hbdcls.Connection.UP, now)
+        # Clear connectivity alert now that the host is back up
+        _set_connectivity_alert(host, conn.afam, "OK")
+        # Don't log/notify RECOVER for a brand-new host seen for the first time —
+        # it was never down, it just hasn't been seen before.
+        if not newh:
             if d == 0 or lasts == "unknown":
                 m = "%s is up" % (conn.afam)
             else:
                 m = "%s back after being %s for %s" % (conn.afam, lasts, dur(d))
             eventlog(uname, "RECOVER", m)
-        if uname in watchhosts:
+            asyncio.create_task(notify_mod.send_notification(
-            notify_mod.pushmsg_for_host(uname, "%s %s is back" % (uname, conn.afam))
+                uname,
+                notify_mod.Notification(title=f"[RECOVER] {uname}", body=m, level="RECOVER"),
+            ))
 
     if boot or newh:
         host.upcount = host.doesack
@@ -217,10 +451,14 @@ def handle_datagram(msg: dict, addr, transport, ctx: dict):
         host.upcount += 1
 
     if shutdown:
-        eventlog(uname, "INFO", "%s shutdown" % conn.afam)
+        m = "%s shutdown" % conn.afam
-        if uname in watchhosts:
+        eventlog(uname, "INFO", m)
-            notify_mod.pushmsg_for_host(uname, "%s %s shutdown" % (uname, conn.afam))
+        asyncio.create_task(notify_mod.send_notification(
+            uname,
+            notify_mod.Notification(title=f"[INFO] {uname}", body=m, level="INFO"),
+        ))
         conn.newstate(hbdcls.Connection.DOWN, now)
+        _set_connectivity_alert(host, conn.afam, "CRITICAL")
 
     if interval > 0:
         host.interval = interval
@@ -229,51 +467,8 @@ def handle_datagram(msg: dict, addr, transport, ctx: dict):
     # Reset overdue timer on every heartbeat
     if interval > 0 and conn.getstate() != hbdcls.Connection.DOWN:
         grace = cfg.get("grace", 2)
-        timeout_seconds = (interval + grace) if interval > 0 else 30
+        timeout_seconds = interval + grace
-        
+        on_overdue, _ = _make_timer_callbacks(uname, host, ctx)
-        # Create callback for timer expiration
-        async def on_overdue(connection):
-            """Called when connection timer expires (no heartbeat received)."""
-            import time
-            now = time.time()
-            
-            # Only mark as overdue if still in UP state (not already marked)
-            if connection.getstate() == hbdcls.Connection.UP:
-                connection.newstate(hbdcls.Connection.OVERDUE, now, cfg.get("grace", 2))
-                
-                msg = f"{connection.afam} overdue"
-                eventlog(uname, "CRITICAL" if uname in watchhosts else "WARNING", msg)
-                
-                if uname in watchhosts:
-                    notify_mod.pushmsg_for_host(uname, f"{uname} {msg}")
-                
-                # Check RTT thresholds with infinite RTT for overdue hosts
-                threshold_checker = ctx.get("threshold_checker")
-                if threshold_checker:
-                    metric_path = "rtt"
-                    threshold_checker.check_value(
-                        host_name=uname,
-                        metric_path=metric_path,
-                        value=float('inf'),
-                        alert_states=host.alert_states
-                    )
-                
-                # Notify websockets
-                if msg_to_websockets:
-                    msg_to_websockets("host", host.stateinfo())
-                
-                # Set a longer timer for marking as UNKNOWN (7 days)
-                DROPOVERDUE = 7 * 24 * 3600
-                
-                async def on_unknown(connection):
-                    """Mark connection as unknown after extended absence."""
-                    connection.newstate(hbdcls.Connection.UNKNOWN, connection.lastbeat)
-                    if msg_to_websockets:
-                        msg_to_websockets("host", host.stateinfo())
-                
-                connection.reset_overdue_timer(DROPOVERDUE, on_unknown)
-        
-        # Reset the timer
         conn.reset_overdue_timer(timeout_seconds, on_overdue)
     
     # Check RTT thresholds using the threshold checker
@@ -295,12 +490,10 @@ def handle_datagram(msg: dict, addr, transport, ctx: dict):
         op, rmsg = host.cmds[0]
         if op == "CMD":
             del host.cmds[0]
-            if log:
+            eventlog(uname, "INFO", "command sent")
-                log(uname, "command sent")
         elif op == "UPD":
             del host.cmds[0]
-            if log:
+            eventlog(uname, "INFO", "update initiated")
-                log(uname, "update initiated")
         opkt = dicttos(op, rmsg)
         try:
             transport.sendto(opkt, addr)

hbd/server/users.py

@@ -0,0 +1,242 @@
+"""User management: loading, authentication, and session tracking.
+
+Users are defined in the config file under the ``users`` key:
+
+    users:
+      alice:
+        full_name: Alice Smith
+        avatar: /path/to/avatar.png   # file path, URL, or base64 data URI
+        password: pbkdf2:sha256:...   # generated with: hbd passwd
+        admin: true                   # optional server-level admin
+        notification_channels: [pushover_standard]
+
+Roles are assigned per-host:
+
+    hosts:
+      webserver01:
+        owner: alice
+        managers: [bob]
+        monitors: [carol]
+
+If no users are defined the server runs in unauthenticated mode (backwards
+compatible).  When users are defined every API call must carry a valid session
+token in an ``Authorization: Bearer <token>`` or ``X-Auth-Token`` header,
+obtained via ``POST /api/0/auth/login``.
+"""
+
+import hashlib
+import hmac
+import logging
+import secrets
+import time
+
+logger = logging.getLogger(__name__)
+
+# Session lifetime in seconds (24 hours).
+SESSION_TTL = 86400
+
+# Global session store: token -> {"username": str, "expires": float, "created": float}
+_sessions: dict = {}
+
+
+# ---------------------------------------------------------------------------
+# User class
+# ---------------------------------------------------------------------------
+
+class User:
+    def __init__(
+        self,
+        username: str,
+        full_name: str = "",
+        avatar: str = "",
+        password_hash: str = "",
+        admin: bool = False,
+        notification_channels: list | None = None,
+    ):
+        self.username = username
+        self.full_name = full_name
+        self.avatar = avatar
+        self.password_hash = password_hash
+        self.admin = admin
+        self.notification_channels: list = notification_channels or []
+
+    def check_password(self, password: str) -> bool:
+        if not self.password_hash:
+            return False
+        return _verify_password(password, self.password_hash)
+
+    def avatar_is_local(self) -> bool:
+        """Return True when the avatar is a local filesystem path (starts with '/')."""
+        return bool(self.avatar and self.avatar.startswith("/"))
+
+    def avatar_url(self) -> str:
+        """Return the URL to use as an <img src>.
+
+        Local file paths are served via the /api/0/users/{username}/avatar
+        endpoint.  External URLs and data URIs are returned as-is.
+        """
+        if self.avatar_is_local():
+            return f"/api/0/users/{self.username}/avatar"
+        return self.avatar
+
+    def to_dict(self) -> dict:
+        return {
+            "username": self.username,
+            "full_name": self.full_name,
+            "avatar": self.avatar,
+            "avatar_url": self.avatar_url(),
+            "admin": self.admin,
+            "notification_channels": self.notification_channels,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Password hashing  (PBKDF2-HMAC-SHA256, stdlib only)
+# ---------------------------------------------------------------------------
+
+def hash_password(password: str) -> str:
+    """Return a storable hash for *password*.
+
+    Format: ``pbkdf2:sha256:<iterations>:<salt>:<hex-digest>``
+
+    Use this to generate the ``password`` value in the config file::
+
+        python -c "from hbd.server.users import hash_password; print(hash_password('secret'))"
+
+    Or via the CLI::
+
+        hbd passwd
+    """
+    salt = secrets.token_hex(16)
+    iterations = 260_000
+    dk = hashlib.pbkdf2_hmac(
+        "sha256", password.encode("utf-8"), salt.encode("utf-8"), iterations
+    )
+    return f"pbkdf2:sha256:{iterations}:{salt}:{dk.hex()}"
+
+
+def _verify_password(password: str, stored_hash: str) -> bool:
+    """Return True if *password* matches *stored_hash*."""
+    try:
+        parts = stored_hash.split(":")
+        if len(parts) != 5 or parts[0] != "pbkdf2" or parts[1] != "sha256":
+            return False
+        _, _, iterations_str, salt, expected_hex = parts
+        iterations = int(iterations_str)
+        dk = hashlib.pbkdf2_hmac(
+            "sha256", password.encode("utf-8"), salt.encode("utf-8"), iterations
+        )
+        return hmac.compare_digest(dk.hex(), expected_hex)
+    except Exception:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Global user registry
+# ---------------------------------------------------------------------------
+
+# username -> User
+users: dict = {}
+
+
+def load_users(config: dict) -> dict:
+    """Populate the global user registry from *config*.
+
+    Called once at startup and again on SIGHUP config reload.
+    Returns the new ``users`` dict.
+    """
+    global users
+    users_cfg = config.get("users", {})
+    if not isinstance(users_cfg, dict):
+        users = {}
+        return users
+
+    result: dict = {}
+    for username, attrs in users_cfg.items():
+        if not isinstance(attrs, dict):
+            logger.warning("Skipping user %r: expected a mapping", username)
+            continue
+        result[username] = User(
+            username=username,
+            full_name=attrs.get("full_name", ""),
+            avatar=attrs.get("avatar", ""),
+            password_hash=attrs.get("password", ""),
+            admin=bool(attrs.get("admin", False)),
+            notification_channels=attrs.get("notification_channels", []),
+        )
+
+    users = result
+    logger.info("Loaded %d user(s) from config", len(users))
+    return users
+
+
+def users_enabled() -> bool:
+    """Return True if at least one user is configured (auth-required mode)."""
+    return bool(users)
+
+
+def get_user(username: str) -> "User | None":
+    return users.get(username)
+
+
+def authenticate(username: str, password: str) -> "User | None":
+    """Return the User if credentials are valid, else None."""
+    user = users.get(username)
+    if user and user.check_password(password):
+        return user
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Session management
+# ---------------------------------------------------------------------------
+
+def create_session(username: str) -> str:
+    """Create a new session for *username* and return the opaque token."""
+    _purge_expired_sessions()
+    token = secrets.token_hex(32)
+    _sessions[token] = {
+        "username": username,
+        "expires": time.time() + SESSION_TTL,
+        "created": time.time(),
+    }
+    return token
+
+
+def get_session_user(token: str) -> "User | None":
+    """Return the User for a valid *token*, or None if missing/expired."""
+    if not token:
+        return None
+    session = _sessions.get(token)
+    if not session:
+        return None
+    if session["expires"] < time.time():
+        del _sessions[token]
+        return None
+    return get_user(session["username"])
+
+
+def delete_session(token: str) -> None:
+    """Invalidate *token* (logout)."""
+    _sessions.pop(token, None)
+
+
+def _purge_expired_sessions() -> None:
+    now = time.time()
+    expired = [t for t, s in list(_sessions.items()) if s["expires"] < now]
+    for t in expired:
+        del _sessions[t]
+
+
+def save_sessions() -> dict:
+    """Return a snapshot of non-expired sessions suitable for pickling."""
+    _purge_expired_sessions()
+    return dict(_sessions)
+
+
+def load_sessions(snapshot: dict) -> None:
+    """Restore sessions from a pickled snapshot, dropping any that have expired."""
+    global _sessions
+    now = time.time()
+    _sessions = {t: s for t, s in snapshot.items() if s.get("expires", 0) > now}
+    logger.debug("Restored %d session(s) from pickle", len(_sessions))

hbd/server/ws.py

@@ -1,7 +1,8 @@
-"""WebSocket server and broadcast helpers for hbd.
+"""WebSocket handler and broadcast helpers for hbd.
 
-Provides an asyncio-based WebSocket server and a thread-safe broadcast
+WebSocket connections are served through the regular HTTP port via the
-function that other threads or synchronous code can call.
+/ws route registered in http.py (aiohttp WebSocketResponse upgrade).
+The separate standalone WebSocket server on ws_port is no longer used.
 """
 
 import asyncio
@@ -10,144 +11,99 @@ import logging
 from typing import Callable, Iterable, Optional
 from . import data
 
-import websockets
-
 logger = logging.getLogger(__name__)
-logger.setLevel(logging.INFO)
+
-_connections = set()
+_connections: set = set()
 _loop: Optional[asyncio.AbstractEventLoop] = None
 _get_hosts: Optional[Callable[[], Iterable]] = None
-#_get_msgs: Optional[Callable[[], Iterable]] = None
+_verbose: bool = False
-_verbose = False
 
 
-async def _handler(websocket, path=None):
+def setup(
-    _connections.add(websocket)
+    loop: asyncio.AbstractEventLoop,
-    remote_address = websocket.remote_address
+    get_hosts: Optional[Callable[[], Iterable]] = None,
-    if path is None:
+    verbose: bool = False,
-        path = getattr(websocket, "path", None)
-    logger.info("WebSocket connection from %s: %s", remote_address, path)
-    try:
-        # send initial hosts
-        if _get_hosts:
-            try:
-                hosts = list(_get_hosts())
-                logger.debug("Sending %d hosts to new WebSocket client", len(hosts))
-                for h in hosts:
-                    jmsg = json.dumps({"type": "host", "data": h})
-                    await websocket.send(jmsg)
-            except Exception as e:
-                logger.error("Error sending initial hosts: %s", e, exc_info=True)
-        # send recent messages
-        if data.msgs:
-            try:
-#                msgs = list(_get_msgs())[-100:]
-                logger.debug("Sending %d recent messages to new WebSocket client", len(data.msgs))
-                for m in data.msgs:
-                    jmsg = json.dumps({"type": "message", "data": m})
-                    await websocket.send(jmsg)
-            except Exception as e:
-                logger.error("Error sending initial messages: %s", e, exc_info=True)
-
-        # keep connection open until client disconnects
-        async for _ in websocket:
-            # we don't expect meaningful incoming messages besides the initial
-            # client 'hello' that some clients send; ignore for now
-            if _verbose:
-                logger.debug("received ws data: %s", _)
-
-    except (
-        websockets.exceptions.ConnectionClosedOK,
-        websockets.exceptions.ConnectionClosedError,
-    ) as e:
-        logger.info("WebSocket closed from %s: %r", remote_address, e)
-    except Exception as e:
-        logger.exception("WebSocket handler exception from %s: %s", remote_address, e)
-    finally:
-        logger.debug("Removing WebSocket connection from %s", remote_address)
-        try:
-            _connections.remove(websocket)
-        except KeyError:
-            pass
-        await websocket.wait_closed()
-
-
-async def start(
-    host: str,
-    ws_port: int,
-    wss_port: Optional[int] = None,
-    ssl_context=None,
-    get_hosts: Optional[Callable] = None,
-#    get_msgs: Optional[Callable] = None,
-    config: dict = {},
 ):
-    """Start WebSocket servers and block until cancelled.
+    """Register the running loop and initial-state callback.
 
-    This is intended to be awaited inside the main asyncio event loop.
+    Call this once from _run_async before starting the HTTP server.
-    If `wss_port` and `ssl_context` are provided, a WSS server will also be
-    started.
     """
     global _loop, _get_hosts, _verbose
-    _loop = asyncio.get_running_loop()
+    _loop = loop
     _get_hosts = get_hosts
-    _verbose = config.get("verbose", False),
+    _verbose = verbose
-    _debug = config.get("debug", 0),
-
-    servers = []
-    # plain WebSocket
-    websockets_logger = logging.getLogger("websockets.server")
-    #if _debug > 2:
-    #    websockets_logger.setLevel(logging.DEBUG)
-    #else:   
-    #    websockets_logger.setLevel(logging.INFO)
-    # regular WebSocket
-    ws_server = websockets.serve(_handler, host, ws_port)  # , subprotocols=["hbd"])
-    servers.append(ws_server)
-    # secure WebSocket (optional)
-    if wss_port and ssl_context:
-        wss_server = websockets.serve(
-            _handler, host, wss_port, ssl=ssl_context
-        )  # , subprotocols=["hbd"])
-        servers.append(wss_server)
-
-    # await starting of all servers
-    for srv in servers:
-        await srv
-
-    logger.info(
-        "WebSocket server(s) started on port %s (wss %s)", ws_port, wss_port
-    )
-
-    # block forever (until loop is stopped or cancelled)
-    await asyncio.Future()
 
 
-def broadcast(typ: str, data) -> bool:
+async def handler(request):
-    """Thread-safe broadcast helper.
+    """aiohttp WebSocket upgrade handler — register as GET /ws."""
+    from aiohttp import web
 
-    Schedules coroutine(s) on the running loop to send message to all
+    ws = web.WebSocketResponse()
-    connected websockets. Returns False if server was not running.
+    await ws.prepare(request)
+
+    _connections.add(ws)
+    remote = request.remote
+    logger.info("WebSocket connected from %s", remote)
+
+    try:
+        # Send current host state to the new client
+        if _get_hosts:
+            try:
+                for h in list(_get_hosts()):
+                    await ws.send_str(json.dumps({"type": "host", "data": h}))
+            except Exception as e:
+                logger.error("Error sending initial hosts: %s", e)
+
+        # Send recent messages
+        if data.msgs:
+            try:
+                for m in data.msgs:
+                    await ws.send_str(json.dumps({"type": "message", "data": m}))
+            except Exception as e:
+                logger.error("Error sending initial messages: %s", e)
+
+        # Keep connection open, ignore incoming frames
+        async for msg in ws:
+            from aiohttp import WSMsgType
+            if msg.type == WSMsgType.TEXT:
+                if _verbose:
+                    logger.debug("ws recv from %s: %s", remote, msg.data)
+            elif msg.type in (WSMsgType.ERROR, WSMsgType.CLOSE):
+                break
+
+    except Exception as e:
+        logger.exception("WebSocket handler error from %s: %s", remote, e)
+    finally:
+        _connections.discard(ws)
+        logger.info("WebSocket disconnected from %s", remote)
+
+    return ws
+
+
+def broadcast(typ: str, payload) -> bool:
+    """Thread-safe broadcast to all connected WebSocket clients.
+
+    Can be called from any thread; schedules sends on the event loop.
+    Returns False if the loop is not running yet.
     """
     if not _loop:
         return False
-    jmsg = json.dumps({"type": typ, "data": data})
+    jmsg = json.dumps({"type": typ, "data": payload})
-    to_close = []
+
+    async def _send_all():
+        dead = set()
         for ws in list(_connections):
-        if ws.state != websockets.protocol.State.OPEN:
-            to_close.append(ws)
-            continue
             try:
-            asyncio.run_coroutine_threadsafe(ws.send(jmsg), _loop)
+                if not ws.closed:
+                    await ws.send_str(jmsg)
+                else:
+                    dead.add(ws)
             except Exception:
-            to_close.append(ws)
+                dead.add(ws)
-            logger.debug("ws.send exception: closed")
+        for ws in dead:
-    for ws in to_close:
+            _connections.discard(ws)
-        try:
+
-            asyncio.run_coroutine_threadsafe(ws.wait_closed(), _loop)
+    asyncio.run_coroutine_threadsafe(_send_all(), _loop)
-        except Exception:
-            pass
-        if ws in _connections:
-            _connections.remove(ws)
     return True
 
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hbd"
-version = "5.0.6"
+version = "5.1.12"
 description = "Heartbeat monitoring system — client (hbc) and server (hbd)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -31,8 +31,12 @@ server = [
   "mattermostdriver>=7.3.0",
   "aiohttp>=3.11",
   "Jinja2>=3.1.6",
+  "matrix-nio>=0.24",
 ]
 
+# Minimal client — hbc_mini only, no external dependencies
+mini = []
+
 # Install both client and server
 all = [
   "hbd[client,server]",
@@ -53,6 +57,9 @@ dev = [
 hbd = "hbd.server.cli:main"
 hbc = "hbd.client.main:main"
 
+[tool.setuptools]
+script-files = ["scripts/hb_install.sh", "scripts/hbc_mini.py"]
+
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["hbd*"]

scripts/bumpminor.sh

@@ -3,11 +3,15 @@
 set -e
 uv version --bump patch 
 VER=$(uv  version  --short)
-sed -i ""  "s/__version__ = \"[0-9.]*\"\(.*\)$/__version__ = \"$VER\"\1/" hbd/__init__.py
+sed -i".bak"  "s/__version__ = \"[0-9.]*\"\(.*\)$/__version__ = \"$VER\"\1/" hbd/__init__.py
+sed -i".bak"  "s/__version__ = \"[0-9.]*\"\(.*\)$/__version__ = \"$VER\"\1/" scripts/hbc_mini.py
 
 # commit pyproject.toml
-git commit -m "version $VER" pyproject.toml hbd/__init__.py
+git commit -m "version $VER" pyproject.toml hbd/__init__.py scripts/hbc_mini.py
 git push 
 # tag version
 git tag -a v$VER -m "Version $VER"
 git push --tags
+
+rm hbd/__init__.py.bak
+rm scripts/hbc_mini.py.bak

scripts/hb_install.sh

@@ -0,0 +1,115 @@
+#!/bin/sh
+
+# Helper script to install the heartbeat tools. By default, it will only
+# install the heartbeat client, hbc. The server is installed when the arg 'server' is passed 
+# to the script. The script will install the heartbeat tools in a python 
+# virtual environment in ~/venvs/hbd. The hbd and hbc commands will be
+# installed from the wheel and symlinked to ~/bin/hbd and ~/bin/hbc,
+# respectively. If the virtual environment already exists, it will be
+# reused. The script will also remove any existing symlinks for hbd and hbc
+# in ~/bin before creating new ones.
+
+set -e
+what=$1
+on_ha=0
+where=""
+venv=""
+[ "$2" = "HA" ] && on_ha=1
+[ -z "$what" ] && what="client"
+
+if [ -d /homeassistant ]; then  # if running from HA command line
+    echo "HA, running \"docker exec homeassistant /config/bin/hb_install.sh $@\""
+    docker exec homeassistant /config/bin/hb_install.sh $@ HA
+    rc=$?
+    if [ $rc -ne 0 ]; then
+        echo "Failed to install heartbeat in HA, please check the logs for more details"
+        exit 1
+    fi
+    exit 0
+fi
+
+if [ $on_ha -eq 1 ] || [ -r /.dockerenv ] && [ -d /config/bin ]; then
+    # Installing under docker on Home Assistant OS, using /config/bin for executables and /config/venvs for virtual environments 
+    echo "Home Assistant OS detected, installing under docker"
+    where="/config/bin"
+    venv="/config/venvs"
+else
+    if [ ! -d $HOME/.local/bin ] && [ ! -d $HOME/bin ]; then
+        echo "No suitable bin directory found in PATH, please add either $HOME/.local/bin or $HOME/bin to your PATH"
+        exit 1
+    fi
+    for where in $HOME/bin $HOME/.local/bin notset ; do
+        if echo ":$PATH:" | grep -q ":$where:" ; then
+            break
+        fi
+    done
+    if [ "$where" = "notset" ]; then
+        echo "No suitable bin directory found in PATH, please add either $HOME/.local/bin or $HOME/bin to your PATH"
+        exit 1
+    fi
+    if [ "$what" = "mini" ]; then
+        venv=""
+    else
+        venv="$HOME/venvs"
+    fi
+fi
+echo "Installing $what to $where"
+if [ ! -z "$venv" ]; then
+    echo "Using virtual environment at $venv/hbd"
+fi
+
+if [ "$venv" != "" ] && [ ! -d  $venv/hbd ]; then
+    arg=""
+    have_pip=$(python3 -c "import pip" 2>/dev/null &> /dev/null && echo "Installed" || echo "Not Installed")
+    if [ "$have_pip" = "Not Installed" ]; then
+        # some systems do not have pip installed by default, so we need to fetch get-pip.py and install pip
+        echo "pip is not installed, fetching get-pip.py and installing pip"
+        arg="--without-pip"
+    fi
+    mkdir -p $venv
+    have_venv=$(python3 -c "import venv" 2>/dev/null &> /dev/null && echo "Installed" || echo "Not Installed")
+    if [ "$have_venv" = "Not Installed" ]; then
+        if [ "$have_pip" = "Not Installed" ]; then
+            echo "python has no venv, and no pip to install virtualenv, cannot continue"
+            exit 1
+        fi
+        echo "python venv module not found, installing virtualenv"
+        python3 -m pip install --user virtualenv
+        python3 -m virtualenv $venv/hbd --system-site-packages $arg
+    else
+        python3 -m venv $venv/hbd --system-site-packages $arg
+    fi
+    . $venv/hbd/bin/activate
+    if [ -n "$arg" ]; then  
+        curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py && python3 get-pip.py
+    fi
+    deactivate
+fi
+
+if [ ! -z "$venv" ]; then
+    . $venv/hbd/bin/activate
+fi
+if [ "$what" = "mini" ]; then
+    curl -s -o $where/hbc_mini https://git.wrede.ca/andreas/heartbeat/raw/branch/master/scripts/hbc_mini.py
+    chmod +x $where/hbc_mini
+else
+    python3 -mpip install --upgrade --index-url https://git.wrede.ca/api/packages/andreas/pypi/simple/ --extra-index-url https://pypi.org/simple hbd[$what]
+fi
+
+if [ ! -z "$venv" ]; then
+    echo "linking executables to $where"
+    if [ "$what" = "server" ]; then
+        rm -f $where/hbd
+        ln -sf $(which hbd) $where/hbd
+    elif [ "$what" = "client" ]; then
+        rm -f $where/hbc
+        ln -sf $(which hbc) $where/hbc
+    fi
+    rm -f $where/hb_install.sh
+    ln -sf $(which hb_install.sh) $where/hb_install.sh
+fi
+echo "Installation complete. To upgrade, run the following:"
+echo "    $where/hb_install.sh $what"
+echo "To install on another machine, run the following obtain the install script and run it:"
+echo "from https://git.wrede.ca/andreas/heartbeat/raw/branch/master/scripts/hb_install.sh"
+echo "and then run sh hb_install.sh [mini|client]"

scripts/install.sh

@@ -1,15 +0,0 @@
-#!/bin/sh
-
-# install hbd/hbc from wheel and create symlinks for hbd and hbc in ~/bin
-
-set -e
-if [ ! -d  ~/venvs/hbd ]; then
-    mkdir -p ~/venvs
-    python3 -m venv ~/venvs/hbd --system-site-packages
-fi
-. ~/venvs/hbd/bin/activate
-pip install 'git+ssh://git@git.wrede.ca/andreas/heartbeat.git'
-rm -f ~/bin/hbd
-rm -f ~/bin/hbc
-ln -sf $(which hbd) ~/bin/hbd
-ln -sf $(which hbc) ~/bin/hbc

tests/test_nagios_runner.py

@@ -0,0 +1,99 @@
+import asyncio
+import logging
+import os
+import stat
+
+from hbd.client.plugins.nagios_runner import (
+    NagiosRunnerPlugin,
+    NAGIOS_OK,
+    NAGIOS_WARNING,
+    NAGIOS_CRITICAL,
+    NAGIOS_UNKNOWN,
+)
+
+
+def test_no_commands_sets_skip_reason():
+    plugin = NagiosRunnerPlugin(config={"commands": []})
+    result = asyncio.run(plugin.initialize())
+    assert result is False
+    assert plugin.skip_reason is not None
+    assert "nagios_runner.commands" in plugin.skip_reason
+
+
+def test_stderr_used_when_stdout_empty(tmp_path):
+    script = tmp_path / "check_err.sh"
+    script.write_text("#!/bin/sh\necho 'error from stderr' >&2\nexit 2\n")
+    script.chmod(script.stat().st_mode | stat.S_IEXEC)
+
+    config = {"commands": [{"name": "t", "command": str(script)}], "timeout": 5}
+    plugin = NagiosRunnerPlugin(config=config)
+    asyncio.run(plugin.initialize())
+    data = asyncio.run(plugin._collect_metrics())
+
+    assert "error from stderr" in data["t_output"]
+    assert data["t_status_code"] == NAGIOS_CRITICAL
+
+
+def test_stderr_appended_when_both_present(tmp_path):
+    script = tmp_path / "check_both.sh"
+    script.write_text("#!/bin/sh\necho 'OK - all good'\necho 'extra detail' >&2\nexit 0\n")
+    script.chmod(script.stat().st_mode | stat.S_IEXEC)
+
+    config = {"commands": [{"name": "t", "command": str(script)}], "timeout": 5}
+    plugin = NagiosRunnerPlugin(config=config)
+    asyncio.run(plugin.initialize())
+    data = asyncio.run(plugin._collect_metrics())
+
+    assert "OK - all good" in data["t_output"]
+    assert "extra detail" in data["t_output"]
+    assert data["t_status_code"] == NAGIOS_OK
+
+
+def test_negative_returncode_maps_to_unknown():
+    # kill -9 $$ kills the shell itself; asyncio sees returncode -9
+    config = {"commands": [{"name": "t", "command": "kill -9 $$"}], "timeout": 5}
+    plugin = NagiosRunnerPlugin(config=config)
+    asyncio.run(plugin.initialize())
+    data = asyncio.run(plugin._collect_metrics())
+
+    assert data["t_status_code"] == NAGIOS_UNKNOWN
+    assert "signal" in data["t_output"].lower()
+
+
+def test_absolute_path_not_found_warns(caplog):
+    fake_cmd = "/nonexistent_hbc_test_path/check_something"
+    config = {"commands": [{"name": "t", "command": fake_cmd}]}
+    plugin = NagiosRunnerPlugin(config=config)
+
+    with caplog.at_level(logging.WARNING, logger="plugin.nagios_runner"):
+        asyncio.run(plugin.initialize())
+
+    assert any("not found" in r.message for r in caplog.records)
+
+
+def test_absolute_path_not_executable_warns(caplog, tmp_path):
+    non_exec = tmp_path / "check_test"
+    non_exec.write_text("#!/bin/sh\necho OK\n")
+    non_exec.chmod(0o644)  # readable but not executable
+
+    config = {"commands": [{"name": "t", "command": str(non_exec)}]}
+    plugin = NagiosRunnerPlugin(config=config)
+
+    with caplog.at_level(logging.WARNING, logger="plugin.nagios_runner"):
+        asyncio.run(plugin.initialize())
+
+    assert any("not executable" in r.message for r in caplog.records)
+
+
+def test_relative_path_not_checked(caplog):
+    # Relative paths (resolved via PATH) must not generate warnings
+    config = {"commands": [{"name": "t", "command": "echo OK"}]}
+    plugin = NagiosRunnerPlugin(config=config)
+
+    with caplog.at_level(logging.WARNING, logger="plugin.nagios_runner"):
+        asyncio.run(plugin.initialize())
+
+    assert not any(
+        "not found" in r.message or "not executable" in r.message
+        for r in caplog.records
+    )

tests/test_plugin.py

@@ -0,0 +1,83 @@
+import asyncio
+import logging
+import textwrap
+
+from hbd.client.plugin import PluginLoader, PluginRegistry
+
+
+def test_plugin_skip_reason_defaults_none(tmp_path):
+    plugin_code = textwrap.dedent("""
+        from hbd.client.plugin import MonitorPlugin
+
+        class MinimalPlugin(MonitorPlugin):
+            name = "minimal"
+            version = "1.0.0"
+            interval = 60
+
+            async def initialize(self):
+                return True
+
+            async def _collect_metrics(self):
+                return {}
+    """)
+    (tmp_path / "minimal.py").write_text(plugin_code)
+    registry = PluginRegistry()
+    loader = PluginLoader(registry)
+    asyncio.run(loader.load_from_directory(tmp_path))
+    plugin = registry.get("minimal")
+    assert plugin is not None
+    assert plugin.skip_reason is None
+
+
+def test_loader_logs_info_when_skip_reason_set(tmp_path, caplog):
+    plugin_code = textwrap.dedent("""
+        from hbd.client.plugin import MonitorPlugin
+
+        class SkippablePlugin(MonitorPlugin):
+            name = "skippable"
+            version = "1.0.0"
+            interval = 60
+
+            async def initialize(self):
+                self.skip_reason = "not configured in yaml"
+                return False
+
+            async def _collect_metrics(self):
+                return {}
+    """)
+    (tmp_path / "skippable.py").write_text(plugin_code)
+    registry = PluginRegistry()
+    loader = PluginLoader(registry)
+
+    with caplog.at_level(logging.INFO, logger="plugin.loader"):
+        count = asyncio.run(loader.load_from_directory(tmp_path))
+
+    assert count == 0
+    assert any("skipped: not configured in yaml" in r.message for r in caplog.records)
+    assert not any("failed initialization" in r.message for r in caplog.records)
+
+
+def test_loader_logs_warning_when_no_skip_reason(tmp_path, caplog):
+    plugin_code = textwrap.dedent("""
+        from hbd.client.plugin import MonitorPlugin
+
+        class FailPlugin(MonitorPlugin):
+            name = "fail"
+            version = "1.0.0"
+            interval = 60
+
+            async def initialize(self):
+                return False
+
+            async def _collect_metrics(self):
+                return {}
+    """)
+    (tmp_path / "fail_plugin.py").write_text(plugin_code)
+    registry = PluginRegistry()
+    loader = PluginLoader(registry)
+
+    with caplog.at_level(logging.WARNING, logger="plugin.loader"):
+        count = asyncio.run(loader.load_from_directory(tmp_path))
+
+    assert count == 0
+    assert any("failed initialization" in r.message for r in caplog.records)