From 0b18314e1eeaf4629264fbf8987b6d09cb474768 Mon Sep 17 00:00:00 2001 From: Cameron Rye Date: Sun, 11 Oct 2026 00:45:57 -0400 Subject: [PATCH 1/2] docs: describe 0.3.0's service hardening, secure defaults and deployment on the website --- .../src/content/docs/docs/cli/commands.mdx | 22 +- .../src/content/docs/docs/installation.mdx | 4 +- .../content/docs/docs/service/deployment.mdx | 336 ++++++++++++------ .../docs/docs/service/home-assistant.mdx | 9 +- .../content/docs/docs/service/security.mdx | 125 +++++-- .../docs/docs/service/websocket-api.mdx | 11 + website/src/content/docs/index.mdx | 4 +- 7 files changed, 351 insertions(+), 160 deletions(-) diff --git a/website/src/content/docs/docs/cli/commands.mdx b/website/src/content/docs/docs/cli/commands.mdx index 2aa051f..a77c4ab 100644 --- a/website/src/content/docs/docs/cli/commands.mdx +++ b/website/src/content/docs/docs/cli/commands.mdx @@ -222,12 +222,12 @@ aranet config | Subcommand | Description | |------------|-------------| -| `show` | Print the full config | +| `show` | Print the config (`gui.service_api_key` hidden) | | `get ` | Print a single config value | | `set ` | Update a config value | | `unset ` | Remove a config value | | `path` | Print the config file path | -| `init` | Create a default config file | +| `init` | Create a commented config file (an existing file is left alone) | Supported keys: `device`, `format`, `timeout`, `no-color`, `fahrenheit`, `inhg`, `bq`. @@ -238,6 +238,22 @@ aranet config set format json aranet config show ``` +`config.toml` lives in your platform's config directory: `aranet config path` prints where, and `ARANET_CONFIG_DIR` changes the directory. `config set`, `config unset`, `alias set`, `alias remove`, the alias prompt of `scan` and the GUI's settings change only the keys they touch: comments, key order and settings aranet doesn't know are kept. If the file doesn't parse, they fail with the parse error and leave it untouched. aranet writes the file atomically and owner-only (mode `0600`); a file that an earlier version created at `0644` becomes `0600` at its next change. `config init` writes a commented template and never replaces an existing file, and `config show` hides `gui.service_api_key`. + +The last device you connected to is kept in `cli-state.toml` in the data directory, not in `config.toml`, so connecting to a sensor doesn't rewrite your config: + +| OS | Location | +|----|----------| +| Linux | `~/.local/share/aranet/cli-state.toml` | +| macOS | `~/Library/Application Support/aranet/cli-state.toml` | +| Windows | `%LOCALAPPDATA%\aranet\cli-state.toml` | + +`ARANET_DATA_DIR` changes that directory. `config show` no longer lists `last_device`; a `last_device` that an earlier version wrote into `config.toml` is still used until your next connection. + + + ## sync Sync device history into the local SQLite cache. @@ -335,6 +351,8 @@ aranet server --bind 127.0.0.1:8080 aranet server --config ~/.config/aranet/server.toml --no-collector ``` +`--bind` takes an IP address and port, such as `127.0.0.1:8080` (`localhost:8080` is rejected). A network address such as `0.0.0.0:8080` needs API-key authentication in the config file, or `security.allow_unauthenticated_network = true`; see [API Security](/aranet/docs/service/security/). `--bind` and `--database` apply to this run only and are never written into the config file. With `--daemon`, the configuration is checked before the server detaches: an invalid config or a refused bind address is printed and the command exits non-zero instead of reporting that the server started. A port that is already in use isn't detected before detaching: the detached server exits and its output is discarded, so run `aranet server` without `--daemon` to see the error. The same goes for `security.api_key_enabled = true` without an `api_key` when the config file can't be written: `--daemon` reports that the server started, and the detached server then exits because it can't save the key it generated. When the key is saved, the `Generated an API key` line isn't shown under `--daemon`, so read the key from the config file. + ## completions Generate shell completions. diff --git a/website/src/content/docs/docs/installation.mdx b/website/src/content/docs/docs/installation.mdx index 55b4af5..c74deb4 100644 --- a/website/src/content/docs/docs/installation.mdx +++ b/website/src/content/docs/docs/installation.mdx @@ -64,11 +64,11 @@ Download binaries directly from GitHub Releases: ## Docker -Run aranet-service in a container (requires BLE access on the host): +Run aranet-service in a container, from a clone of the repository. Bluetooth in Docker needs a Linux host with BlueZ: ```bash docker compose up -d -# Dashboard: http://localhost:8080/dashboard +# Dashboard: http://127.0.0.1:8080/dashboard (published on this machine only) ``` Or use the full monitoring stack with Prometheus and Grafana: diff --git a/website/src/content/docs/docs/service/deployment.mdx b/website/src/content/docs/docs/service/deployment.mdx index 7885567..0ba0407 100644 --- a/website/src/content/docs/docs/service/deployment.mdx +++ b/website/src/content/docs/docs/service/deployment.mdx @@ -6,20 +6,23 @@ description: Deploy aranet-service as a background system service. import { Aside, Steps, Tabs, TabItem, Badge, Code } from '@astrojs/starlight/components'; import { CURRENT_RELEASE } from '../../../../site-config.mjs'; -This guide covers deploying aranet-service as a persistent background service on various platforms. +This guide covers running aranet-service as a persistent background service. The `aranet` CLI from the [downloads](/aranet/docs/downloads/) runs the same service as `aranet server`. The standalone `aranet-service` binary, which can also install itself as a service, comes from `cargo install aranet-service --features full`. ## Deployment Options -| Platform | Service Manager | Config Location | -|----------|----------------|-----------------| -| macOS | launchd | `~/Library/LaunchAgents/` | -| Linux | systemd | `/etc/systemd/system/` | -| Docker | docker-compose | Container orchestration | -| Windows | NSSM | Windows Service | +| Platform | Service Manager | Installed as | +|----------|----------------|--------------| +| macOS | launchd (per-user LaunchAgent) | `~/Library/LaunchAgents/dev.rye.aranet.plist` | +| Linux | systemd (system service) | `/etc/systemd/system/aranet.service` | +| Linux | systemd (user service) | `~/.config/systemd/user/aranet.service` | +| Docker | Docker Compose | `docker-compose.yml` or `docker/docker-compose.yml` | +| Windows | Task Scheduler | A task that starts the service at logon | + +`sudo aranet-service service install` installs a system-level service only on Linux with systemd, where the service runs as an unprivileged user. On macOS, Windows, OpenRC and rc.d it refuses, because the service would run as root there. Use `aranet-service service install --user` on macOS, Task Scheduler on Windows (see [Windows](#windows)), and an init script of your own that runs `aranet-service run` as an unprivileged user on OpenRC and rc.d. ## macOS (launchd) -### User-Level Service +On macOS the service runs as a LaunchAgent: as you, while you're logged in, with your own config and database. 1. Install aranet-service @@ -27,7 +30,7 @@ This guide covers deploying aranet-service as a persistent background service on cargo install aranet-service --features full ``` -2. Install as user service +2. Install the LaunchAgent ```bash aranet-service service install --user ``` @@ -43,9 +46,13 @@ This guide covers deploying aranet-service as a persistent background service on ``` +The agent reads `~/Library/Application Support/aranet/server.toml`. To use another file, name it when you install: `aranet-service service install --user --config /path/to/server.toml`. If polls fail because Bluetooth access is denied, allow `aranet-service` under **System Settings → Privacy & Security → Bluetooth**. Remove the agent with `aranet-service service uninstall --user`. + +A system-level install (`sudo aranet-service service install`) is refused on macOS, because launchd would run the service as root. + ### Manual Configuration -Create `~/Library/LaunchAgents/dev.rye.aranet.plist`: +The agent that `service install --user` writes doesn't keep a log. For a log file, write the agent yourself instead, and don't also run `service install --user`, which uses the same label. Create `~/Library/LaunchAgents/dev.rye.aranet.plist`, replacing `/Users/you` with your home directory (launchd doesn't expand `~`): ```xml @@ -56,7 +63,7 @@ Create `~/Library/LaunchAgents/dev.rye.aranet.plist`: dev.rye.aranet ProgramArguments - /usr/local/bin/aranet-service + /Users/you/.cargo/bin/aranet-service run RunAtLoad @@ -64,119 +71,137 @@ Create `~/Library/LaunchAgents/dev.rye.aranet.plist`: KeepAlive StandardOutPath - /usr/local/var/log/aranet.log + /Users/you/Library/Logs/aranet-service.log StandardErrorPath - /usr/local/var/log/aranet.err - WorkingDirectory - /usr/local/var/aranet + /Users/you/Library/Logs/aranet-service.log ``` -Load the service: +Load it, and unload it when you no longer want it: ```bash -launchctl load ~/Library/LaunchAgents/dev.rye.aranet.plist +launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/dev.rye.aranet.plist +launchctl bootout "gui/$(id -u)/dev.rye.aranet" ``` ## Linux (systemd) -### System-Level Service +### System Service + +The system service is `aranet.service`. It runs aranet-service as a dynamic, unprivileged `aranet` user with no extra capabilities, reads `/var/lib/aranet/server.toml` and keeps its database in `/var/lib/aranet`. You don't create the user or the directory: systemd does when the service starts. (With a dynamic user, systemd keeps the directory at `/var/lib/private/aranet` and links `/var/lib/aranet` to it; as root, either path works.) -1. Build and install +1. Install aranet-service where only root can change it ```bash - cargo build --release -p aranet-service --features full - sudo cp target/release/aranet-service /usr/local/bin/ + cargo install aranet-service --features full + sudo install -o root -g root -m 0755 ~/.cargo/bin/aranet-service /usr/local/bin/aranet-service ``` + The installer refuses a program that a non-root user could replace, such as `~/.cargo/bin/aranet-service` itself or a build in `target/`. -2. Create service user +2. Install and start the service ```bash - sudo useradd -r -s /bin/false aranet - sudo mkdir -p /var/lib/aranet - sudo chown aranet:aranet /var/lib/aranet + sudo /usr/local/bin/aranet-service service install + sudo systemctl start aranet ``` + Or install the unit from the repository yourself: `sudo install -m 0644 distribution/systemd/aranet.service /etc/systemd/system/aranet.service`, then `sudo systemctl daemon-reload` and `sudo systemctl enable --now aranet`. -3. Install the service file +3. Add your sensors, then restart ```bash - aranet-service service install - # Or manually: sudo cp distribution/systemd/aranet.service /etc/systemd/system/ + sudoedit /var/lib/aranet/server.toml + sudo systemctl restart aranet ``` -4. Enable and start +4. Check status and logs ```bash - sudo systemctl daemon-reload - sudo systemctl enable --now dev.rye.aranet + systemctl status aranet + journalctl -u aranet -f ``` -### Service File - -Create `/etc/systemd/system/aranet.service`: - -```ini -[Unit] -Description=Aranet Sensor Collector Service -Documentation=https://github.com/cameronrye/aranet -After=network-online.target bluetooth.target -Wants=network-online.target - -[Service] -Type=simple -User=aranet -Group=aranet -ExecStart=/usr/local/bin/aranet-service run -Restart=on-failure -RestartSec=5 -StartLimitIntervalSec=60 -StartLimitBurst=3 - -# Paths -WorkingDirectory=/var/lib/aranet -ReadWritePaths=/var/lib/aranet - -# Security hardening -ProtectSystem=strict -ProtectHome=true -PrivateTmp=true -NoNewPrivileges=true - -# Bluetooth access -AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW -CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW - -[Install] -WantedBy=multi-user.target +`service install --config ` makes the unit read another config file. A path that contains `..`, or that lies in `/home`, `/root`, `/run/user`, `/tmp` or `/var/tmp` (also when a symlink leads there), is refused at install time, because the unit hides those directories from the service. + +If the journal shows that BlueZ refused access (`org.freedesktop.DBus.Error.AccessDenied`), let the service use the `bluetooth` group with a drop-in: + +```bash +sudo mkdir -p /etc/systemd/system/aranet.service.d +printf '[Service]\nSupplementaryGroups=bluetooth\n' | sudo tee /etc/systemd/system/aranet.service.d/bluetooth.conf +sudo systemctl daemon-reload +sudo systemctl restart aranet +``` + +To remove the service, stop it first: `sudo aranet-service service stop`, then `sudo aranet-service service uninstall`. + +The system service has no desktop session, so desktop notifications (the `notifications` feature) don't reach anyone from it: use webhooks or MQTT there, or a [user service](#user-service). + +#### Running the released `aranet` binary + +The release downloads contain `aranet`, not `aranet-service`, and `aranet server` runs the same service. To run it under this unit, copy it where only root can change it, install the unit, and replace the unit's command with a drop-in: + +```bash +sudo install -o root -g root -m 0755 ~/.cargo/bin/aranet /usr/local/bin/aranet +sudo install -m 0644 distribution/systemd/aranet.service /etc/systemd/system/aranet.service +sudo mkdir -p /etc/systemd/system/aranet.service.d +printf '[Service]\nExecStart=\nExecStart=/usr/local/bin/aranet server --config /var/lib/aranet/server.toml\nEnvironment=RUST_LOG=aranet_service=info\n' \ + | sudo tee /etc/systemd/system/aranet.service.d/aranet-cli.conf +sudo systemctl daemon-reload +sudo systemctl enable --now aranet +``` + +#### Upgrading from a 0.2.x system service + +Earlier versions installed the system service as `rye-aranet.service`, running as root. Every `aranet-service service` command warns while that unit is still installed; `sudo aranet-service service install` stops and removes it (or `sudo aranet-service service uninstall` removes it without installing the new one). Its config and database stay where they were, by default `/root/.config/aranet/server.toml` and `/root/.local/share/aranet/data.db`. To keep them, copy them into `/var/lib/aranet` after the first start of `aranet.service`, and give them to the service's user. `sudo aranet-service service install` prints these steps when it finds the old config: + +```bash +sudo systemctl start aranet && sudo systemctl stop aranet # creates /var/lib/aranet +sudo cp /root/.config/aranet/server.toml /var/lib/aranet/ +sudo sh -c 'rm -f /var/lib/aranet/data.db*' +sudo sh -c 'cp /root/.local/share/aranet/data.db* /var/lib/aranet/' +sudo chown -R --reference=/var/lib/aranet /var/lib/aranet/ +sudoedit /var/lib/aranet/server.toml # if storage.path points under /root, delete that line +sudo systemctl start aranet ``` -### User-Level Service +The `rm` removes the empty database that the first start created, with its `-wal` and `-shm` files, so none of them is applied to the old database. The `cp` copies the old database together with its own `-wal` and `-shm` files, if any, so no reading that is still only in the write-ahead log is lost. The globs run in `sh -c` because your own shell can't list `/root` or `/var/lib/aranet`. Without a `storage.path`, the service uses the database in `/var/lib/aranet`. + +### User Service + +A user service runs as you, with `~/.config/aranet/server.toml` and your own database, and needs no root: ```bash -# Create user service directory -mkdir -p ~/.config/systemd/user +aranet-service service install --user +aranet-service service start --user +aranet-service service status --user +journalctl --user -u aranet -f +``` + +It runs while you're logged in; `loginctl enable-linger "$USER"` keeps it running after you log out. A user service that 0.2.x installed as `rye-aranet.service` is stopped and removed when you install the new one. -# Copy service file -cp distribution/systemd/aranet.service ~/.config/systemd/user/ +## Windows -# Edit to remove User/Group and adjust paths -# Then enable -systemctl --user daemon-reload -systemctl --user enable --now dev.rye.aranet +`aranet-service service install` doesn't support Windows yet: the program can't run as a Windows service. Start the service at logon with Task Scheduler instead. Creating a logon task needs a Command Prompt opened with **Run as administrator**; `/ru` and `/it` keep the task running as you, in your session. For the `aranet` CLI from the installer: + +```text +schtasks /create /tn "Aranet Service" /tr "\"%USERPROFILE%\.cargo\bin\aranet.exe\" server" /sc onlogon /ru "%USERNAME%" /it ``` +With `aranet-service` from `cargo install`, use `"\"%USERPROFILE%\.cargo\bin\aranet-service.exe\" run"` as the `/tr` value instead. The task runs as you, with `%APPDATA%\aranet\server.toml` and your own database, in a console window that stays open while the service runs. Remove it with `schtasks /delete /tn "Aranet Service"`, also from an administrator prompt. Without administrator rights, put a shortcut to `aranet.exe server` (or `aranet-service.exe run`) in your Startup folder (Win+R, `shell:startup`) instead. + ## Docker -A multi-stage `Dockerfile` and `docker-compose.yml` are provided at the repository root. BLE access requires privileged mode and D-Bus passthrough. +`docker/Dockerfile` builds an image that runs aranet-service as an unprivileged user (uid and gid 999) and always reads `/app/server.toml`. The image holds a copy of [`docker/server.toml`](https://github.com/cameronrye/aranet/blob/main/docker/server.toml), and both compose files mount that file over it. A config that fails validation stops the container; `docker logs aranet-service` shows why. ### Quick Start ```bash -# Standalone service with BLE +# Standalone service, from the repository root docker compose up -d -# Dashboard: http://localhost:8080/dashboard +# Dashboard: http://127.0.0.1:8080/dashboard ``` +The compose files publish their ports on `127.0.0.1` only, so the dashboard and API (and Prometheus and Grafana in the monitoring stack) are reachable from this machine but not from the network. + ### Full Monitoring Stack Use the `docker/` directory for a Prometheus + Grafana stack: @@ -185,57 +210,82 @@ Use the `docker/` directory for a Prometheus + Grafana stack: docker compose -f docker/docker-compose.yml up -d ``` +For Bluetooth, uncomment the `/run/dbus:/run/dbus:ro` volume of `aranet-service` in `docker/docker-compose.yml`. Grafana is at http://127.0.0.1:3000 (user `admin`, password `changeme` unless you set `GRAFANA_ADMIN_PASSWORD`). + +### Editing the Configuration + +Edit `docker/server.toml` and restart the container (`docker compose restart aranet-service`). The compose files mount it read-only, so adding, changing or removing a sensor through the API, the TUI or the GUI fails with `500 Internal Server Error`. To manage sensors that way, mount a writable copy that uid 999 can write, without `:ro`: + +```bash +cp docker/server.toml server.toml +sudo chown 999:999 server.toml +# in the compose file: - ./server.toml:/app/server.toml +``` + +The service then rewrites that file in place, keeping its comments. It can't replace a single mounted file, so an interrupted write can leave it incomplete: keep a copy. + +### Bluetooth in Docker + +Bluetooth works on a Linux host running BlueZ: mount the host's `/run/dbus` read-only (`/run/dbus:/run/dbus:ro`), and the service talks to BlueZ over the system bus. No privileged mode, host networking or device nodes are needed. Docker Desktop on macOS and Windows can't reach the host's Bluetooth adapter; run the service natively there. + +If the log shows `AccessDenied` for `org.bluez` or the system bus: + +- BlueZ may accept only members of the host's `bluetooth` group. Add its group id (`getent group bluetooth`) to the service with `group_add: [""]`. +- AppArmor (Ubuntu) or SELinux (Fedora, RHEL) may block the container's D-Bus messages. Lifting that confinement for this one container is the way out; the root `docker-compose.yml` has both lines, commented out: + + ```yaml + security_opt: ["apparmor=unconfined"] # Ubuntu and other AppArmor hosts + # security_opt: ["label=disable"] # SELinux hosts (Fedora, RHEL) + ``` + ### Build from Source ```bash -docker build -t aranet-service . +docker build -f docker/Dockerfile -t aranet-service . docker run -d --name aranet-service \ - --privileged --network host \ - -v /var/run/dbus:/var/run/dbus \ + -p 127.0.0.1:8080:8080 \ + -v /run/dbus:/run/dbus:ro \ -v aranet-data:/data \ - -v ./server.toml:/app/server.toml:ro \ - -e RUST_LOG=aranet_service=info \ + -v "$PWD/server.toml:/app/server.toml:ro" \ aranet-service ``` +Build from the repository root with `-f docker/Dockerfile`; there is no `Dockerfile` at the root any more. The Dockerfile needs BuildKit (it uses cache mounts and `COPY --chmod`), the default builder since Docker 23 when the buildx plugin is installed (on Debian and Raspberry Pi OS, the `docker-buildx` package). An older engine may build it with `DOCKER_BUILDKIT=1 docker build …`; if that fails on `--chmod`, update Docker. `docker compose` needs the Compose v2 plugin. The mounted `server.toml` must be readable by uid 999 (`chmod 644 server.toml`, or `sudo chown 999:999 server.toml` if it holds secrets). Arguments after the image name replace the default `run` command and still read `/app/server.toml`, for example `docker run … aranet-service run --no-collector`. + ### Production Deployment ```yaml -# docker-compose.prod.yml +# docker-compose.prod.yml, in the repository root services: aranet-service: - build: . + build: + context: . + dockerfile: docker/Dockerfile restart: always ports: - - "8080:8080" + - "127.0.0.1:8080:8080" volumes: - aranet-data:/data - ./server.toml:/app/server.toml:ro - - /var/run/dbus:/var/run/dbus - privileged: true - network_mode: host + - /run/dbus:/run/dbus:ro environment: - RUST_LOG=aranet_service=info - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"] - interval: 30s - timeout: 10s - retries: 3 - start_period: 5s volumes: aranet-data: ``` +The image has its own health check on `/api/health`. + ## Configuration ### Server Configuration -Create `~/.config/aranet/server.toml`: +The service reads `server.toml` from `~/.config/aranet/` on Linux, `~/Library/Application Support/aranet/` on macOS and `%APPDATA%\aranet\` on Windows, or the file you pass with `--config`. The systemd system service uses `/var/lib/aranet/server.toml`, and the Docker image `/app/server.toml`. ```toml [server] @@ -244,6 +294,11 @@ bind = "127.0.0.1:8080" [storage] path = "~/.local/share/aranet/data.db" +# Optional: delete old data (off by default) +[storage.retention] +readings_days = 90 +history_days = 365 + [prometheus] enabled = true @@ -253,14 +308,23 @@ alias = "office" poll_interval = 60 ``` +- `server.bind` is an IP address and port. Host names such as `localhost:8080` are rejected: use `127.0.0.1:8080`. Listening on a network address (`0.0.0.0`, `[::]` or a LAN address) needs API-key authentication; see [API Security](/aranet/docs/service/security/). +- `storage.path` may start with `~/`, meaning your home directory. Earlier versions created a directory literally named `~` in the working directory instead. If you used such a path, the service logs a warning that names both paths at every start, until the old file is moved or removed. To keep that data, stop the service first, then move `./~/.local/share/aranet/data.db` (with its `data.db-wal` and `data.db-shm` files, if any) to `~/.local/share/aranet/`. The move replaces the database the service has created there since the upgrade, which on Linux is also the `aranet` CLI's cache: if that database holds data you want, merge the two instead. Leave `storage.path` out under the systemd system service, which keeps its database in `/var/lib/aranet`. +- `[storage.retention]` makes the service delete readings older than `readings_days` and history records older than `history_days` (1 to 36500 days each), at startup and then every hour, in small batches, and logs what it deleted (`Retention: deleted N readings and M history records older than the retention limits`). Leave it out to keep everything; a change takes effect when the service restarts. `history_days` also deletes the history that `aranet sync` cached in the same database, so the next `aranet sync` may download those records from the sensor again. Deleting rows doesn't shrink the file: stop the service, then run `sqlite3 'VACUUM;'` to give the space back (`aranet cache prune --vacuum` also deletes cached history, and readings unless you add `--history-only`, older than its `--older-than` age). +- Device addresses and aliases can be up to 64 characters long and can't contain control characters or backslashes. + +The service writes this file only when you add, change or remove a device through the API (the TUI and GUI service panels use it) or when it generates an API key. It changes only those keys, keeps your comments and layout, never writes command-line overrides such as `--bind` or default values into it, and never overwrites a file it can't parse. It writes atomically and owner-only (mode `0600`), and keeps the file's owner. Sensors you add to the file by hand while the service runs take effect after a restart, and a device change made through the API meanwhile replaces the file's device list with the service's. + +If the file no longer parses when a device is added, changed or removed through the API, the request fails with `500 Internal Server Error` and the file stays as it is. The response names the file and says it is not valid TOML (see the service log); the parse error itself goes only to the service log. It can quote the line of `server.toml` it failed on, so treat the log with the same care as the file. + ### Security Configuration -For production deployments, enable API authentication and rate limiting: +For production deployments, enable API authentication and keep rate limiting on: ```toml [security] api_key_enabled = true -api_key = "your-secure-random-key-at-least-32-chars" +# Leave api_key out and the service generates one and saves it here. rate_limit_enabled = true rate_limit_requests = 100 rate_limit_window_secs = 60 @@ -307,6 +371,8 @@ Each webhook POST sends a JSON payload: Valid event types: `co2_high`, `radon_high`, `battery_low`. +Deliveries run in the background, up to 16 at a time, so a slow or unreachable endpoint doesn't hold up other alerts. Each request times out after 10 s and is tried up to 3 times, 2 s apart and then longer. An alert's cooldown starts once it has been delivered. When 16 deliveries are already running, new alerts are dropped with a warning and come back with a later reading. The log names each endpoint by its position, `endpoint #1` for the first `[[webhooks.endpoints]]` entry, followed by its scheme, host and port only (`https://hooks.slack.com/…`), because many webhook URLs contain their secret. Validation errors count from 0 instead: `webhooks.endpoints[0]` is the same entry. + ### InfluxDB Export Export sensor readings to InfluxDB v2 in real time: @@ -322,17 +388,20 @@ measurement = "aranet" precision = "s" # s, ms, us, or ns ``` -Data is written using the InfluxDB v2 line protocol: `aranet,device=office,address=Aranet4+AAAAA co2=450i,temperature=22.50,humidity=45i,pressure=1013.50,battery=85i`. +Data is written using the InfluxDB v2 line protocol: `aranet,device=office,address=Aranet4\ AAAAA co2=450i,temperature=22.50,humidity=45i,pressure=1013.50,battery=85i`. Tag values and the measurement name are escaped, and `measurement` can't start with `_` or `#` or contain control characters or backslashes. A `measurement` whose spaces or commas were escaped by hand (`air\ quality`) must now be written plain (`air quality`): the service escapes it, and readings continue in the same measurement. + +Lines are sent in batches of up to 500. While InfluxDB is unreachable, or answers with a server error, `408` or `429`, the service keeps up to 10000 lines queued and retries with a growing delay, from 1 s up to 5 minutes. When the queue is full, new readings are dropped, with a warning at most once a minute. A batch that InfluxDB rejects with another `4xx` error is dropped, and lines still queued when the service stops are lost. The log shows the InfluxDB URL as `scheme://host[:port]/…` only. ### mDNS Service Discovery -When running, aranet-service automatically advertises itself on the local network via mDNS: +When the service listens on a network address with API-key authentication on, it advertises itself on the local network via mDNS: - Service type: `_aranet._tcp.local.` - HTTP service: `_http._tcp.local.` +- Instance and host: `Aranet Service on ` at `aranet-.local.`, where `` is the first label of this machine's host name (for example `aranet-raspberrypi.local.`), with the port the service listens on - Properties: `version`, `path` (`/api`), `dashboard` (`/dashboard`) -Clients can discover the service without manual IP configuration: +It doesn't advertise a loopback address such as `127.0.0.1`, or a network address served without authentication (`security.allow_unauthenticated_network = true`). Clients can then find the service without manual IP configuration: ```bash # macOS @@ -363,10 +432,12 @@ The dashboard includes panels for: # Log level export RUST_LOG=aranet_service=info -# Config file location -export ARANET_CONFIG=/path/to/server.toml +# Directory of the default database (data.db); the CLI also keeps cli-state.toml there +export ARANET_DATA_DIR=/var/lib/aranet ``` +There is no environment variable for the service's config file: pass it with `--config`, as in `aranet-service --config /path/to/server.toml` or `aranet server --config /path/to/server.toml`. + ## Prometheus Integration ### Scrape Configuration @@ -382,6 +453,22 @@ scrape_configs: scrape_interval: 60s ``` +With API-key authentication on, `/metrics` needs the key too. Prometheus sends it as a bearer token: + +```yaml +scrape_configs: + - job_name: 'aranet' + authorization: + type: Bearer + credentials_file: /etc/prometheus/aranet-api-key + static_configs: + - targets: ['aranet.example.com:8080'] + metrics_path: /metrics + scrape_interval: 60s +``` + +`credentials_file` holds only the key; `credentials: ''` also works. Without authentication, the service answers only host names it knows (see [Host Names](/aranet/docs/service/security/#host-names)): a target other than `localhost`, an IP address or this machine's name must be listed in `security.allowed_hosts`. + ### Available Metrics | Metric | Type | Description | @@ -394,8 +481,8 @@ scrape_configs: | `aranet_reading_age_seconds` | gauge | Time since last reading | | `aranet_collector_running` | gauge | Collector status (1/0) | | `aranet_collector_uptime_seconds` | gauge | Collector uptime | -| `aranet_device_poll_success_total` | counter | Successful polls | -| `aranet_device_poll_failure_total` | counter | Failed polls | +| `aranet_device_poll_success_total` | counter | Successful polls since the service started | +| `aranet_device_poll_failure_total` | counter | Failed polls since the service started | | `aranet_device_poll_duration_ms` | gauge | Per-device poll duration | ## Multi-Device Setup @@ -458,11 +545,14 @@ For sensors spread across multiple locations: ### View Logs ```bash -# systemd +# systemd system service journalctl -u aranet -f -# launchd -tail -f /usr/local/var/log/aranet.log +# systemd user service +journalctl --user -u aranet -f + +# launchd, with the manual LaunchAgent above +tail -f ~/Library/Logs/aranet-service.log # Docker docker logs -f aranet-service @@ -487,19 +577,31 @@ curl http://localhost:8080/api/health/detailed curl http://localhost:8080/metrics ``` +### Reading Stored Data + +`/api/readings`, `/api/devices/{id}/readings` and `/api/devices/{id}/history` return the newest rows first, 1000 at a time unless you pass `limit` (at most 10000). `pagination.has_more` says whether older rows remain, and `pagination.limit` is the page size used. Page with `offset`, up to 1000000; beyond that, or to jump to a time range, use `since` and `until` (Unix timestamps). `limit=0`, a larger `limit` and a larger `offset` are rejected with `400 Bad Request`. + +```bash +curl "http://localhost:8080/api/readings?since=1767225600&limit=500" +``` + ## Troubleshooting ### Service Won't Start -1. Check logs for errors -2. Verify configuration file syntax: `toml-cli check server.toml` -3. Ensure Bluetooth permissions (Linux: CAP_NET_ADMIN) +1. Read the error: `journalctl -u aranet` for the system service, `docker logs aranet-service` in Docker, or run `aranet-service --config run` in a terminal. +2. A config file that doesn't parse is reported with its path and the position of the error. Fix it by hand: aranet never overwrites a file it can't parse. +3. `server.bind` must be an IP address and port: `127.0.0.1:8080`, not `localhost:8080`. +4. On a network address (`0.0.0.0`, `[::]` or a LAN address) without API-key authentication, the service refuses to start. Enable `security.api_key_enabled`, bind to `127.0.0.1`, or set `security.allow_unauthenticated_network = true` if a firewall or an authenticating proxy protects the port. +5. With `security.api_key_enabled = true` and no `api_key`, the service generates a key and must save it in `server.toml`. If it can't write the file, as with a read-only mount in Docker, set `api_key` yourself. +6. A port that is already in use is reported before the service opens its database or uses Bluetooth. ### No Bluetooth Access -- **Linux**: Add user to `bluetooth` group: `sudo usermod -aG bluetooth $USER` -- **macOS**: Grant Bluetooth permission in System Preferences -- **Docker**: Run with `--privileged` or mount `/var/run/dbus` +- **Linux (system service)**: if the journal shows `AccessDenied` for `org.bluez`, add `SupplementaryGroups=bluetooth` with a drop-in (see [System Service](#system-service)) +- **Linux (desktop or user service)**: add your user to the `bluetooth` group with `sudo usermod -aG bluetooth $USER`, then log in again +- **macOS**: allow the terminal app, or `aranet-service` when it runs as a LaunchAgent, under **System Settings → Privacy & Security → Bluetooth** +- **Docker**: on a Linux host with BlueZ, mount `/run/dbus` read-only; see [Bluetooth in Docker](#bluetooth-in-docker). Docker Desktop on macOS and Windows can't reach the host's Bluetooth adapter ### Connection Timeouts diff --git a/website/src/content/docs/docs/service/home-assistant.mdx b/website/src/content/docs/docs/service/home-assistant.mdx index 3006de1..31efdd8 100644 --- a/website/src/content/docs/docs/service/home-assistant.mdx +++ b/website/src/content/docs/docs/service/home-assistant.mdx @@ -33,7 +33,7 @@ aranet-service can publish sensor readings to MQTT and optionally register suppo ## aranet-service Configuration -Edit `~/.config/aranet/server.toml`: +Edit `server.toml` (see [Server Configuration](/aranet/docs/service/deployment/#server-configuration) for where it is): ```toml [mqtt] @@ -61,6 +61,7 @@ Key points: - `topic_prefix` controls the reading topics, such as `aranet/office/co2`. - `ha_discovery_prefix` controls the Home Assistant discovery topics, usually `homeassistant`. - `homeassistant = true` enables discovery publishing. +- While MQTT is enabled, `topic_prefix`, and `ha_discovery_prefix` when `homeassistant = true`, can't contain the MQTT wildcards `+` and `#` or control characters; the service refuses to start with such a prefix. ## Home Assistant Setup @@ -169,7 +170,7 @@ mosquitto_sub -t 'homeassistant/#' -v ### Topic names are unexpected -Device aliases are preferred for topic names. MQTT topic segments are sanitized by replacing spaces, `/`, `#`, and `+` with `_`. +Device aliases are preferred for topic names. MQTT topic segments are sanitized by replacing spaces, `/`, `#`, `+` and control characters with `_`. An alias longer than 64 characters or with a control character or backslash is rejected: the API answers `400`, and a `server.toml` with one fails validation at startup. ### Discovery is enabled but no sensors appear @@ -177,3 +178,7 @@ Device aliases are preferred for topic names. MQTT topic segments are sanitized 2. Make sure the service has at least one configured device. 3. Wait for the service to publish readings after startup or config reload. 4. Verify the discovery prefix matches Home Assistant expectations, usually `homeassistant`. + +### Readings are missing after a broker outage + +While the broker is unreachable, aranet-service keeps polling but drops live readings once the MQTT client's queue is full, with a warning in its log, instead of waiting. When the connection is back, the readings queued at the start of the outage (at most 100 messages, about 14 Aranet4 readings) are sent first, then live readings. The rest of the outage is a gap in Home Assistant's history, and retained topics end on the newest values. diff --git a/website/src/content/docs/docs/service/security.mdx b/website/src/content/docs/docs/service/security.mdx index 410c30f..46ed5f7 100644 --- a/website/src/content/docs/docs/service/security.mdx +++ b/website/src/content/docs/docs/service/security.mdx @@ -5,17 +5,21 @@ description: Configure authentication, rate limiting, and CORS for aranet-servic import { Aside, Steps } from '@astrojs/starlight/components'; -aranet-service includes optional API-key authentication plus enabled-by-default rate limiting and localhost-only CORS defaults. +aranet-service has optional API-key authentication and rate limiting that is on by default. While authentication is off, it also keeps other web pages and the network out. ## Security Defaults | Feature | Default | Notes | |---------|---------|-------| -| API key authentication | Disabled | Enable with `security.api_key_enabled = true` | -| Rate limiting | Enabled | Defaults to `100` requests per `60` seconds per IP | -| Rate-limit IP cache | `10000` entries | Controlled by `security.rate_limit_max_entries` | -| CORS | `http://localhost`, `http://127.0.0.1` | Override with `security.cors_origins` | -| Device ID sanitization | Always enabled | Used for API-facing identifiers and dashboard output | +| API key authentication | Off | Enable with `security.api_key_enabled = true`; a key is generated and saved if you don't set one. Send it as `X-API-Key` or `Authorization: Bearer` | +| Listening on the network | Refused without authentication | `0.0.0.0`, `[::]` or a LAN address needs an API key, or `security.allow_unauthenticated_network = true` if a firewall or authenticating proxy protects the port | +| Host check | On while authentication is off | `localhost`, IP addresses, this machine's name and `security.allowed_hosts` (421 otherwise) | +| Cross-origin browser requests | Rejected while authentication is off | The service's own pages and `security.cors_origins` only (403 otherwise) | +| CORS | No origins | `security.cors_origins` | +| Rate limiting | Enabled | A burst of `100` requests, then one every 0.6 s (`100` per `60` seconds), per IPv4 address or IPv6 /64 | +| Rate-limit client table | Swept above `10000` entries | `security.rate_limit_max_entries`; clients whose budget has refilled are forgotten early | +| Device addresses and aliases | Validated | At most 64 characters, no control characters or backslashes | +| Config files | Owner-only (`0600`) | Written atomically; comments are kept |