diff --git a/website/src/content/docs/docs/cli/commands.mdx b/website/src/content/docs/docs/cli/commands.mdx index 2aa051f..3262721 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,24 @@ 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` and the alias prompt of `scan` 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 GUI saves its own settings whenever you change one and when it quits: the `[gui]` table as a whole, and each `[behavior]` switch on its own. It keeps the rest of the file and its comments. It never changes `gui.service_url` or `gui.service_api_key`: it has no control for them, so set those two by hand. Other `[gui]` keys that you edit by hand while the GUI runs are overwritten by its next save, so quit it first (with Quit: while Close to Menu Bar is on, closing the window only hides it). If the file doesn't parse, the GUI leaves it untouched and shows `Settings not saved: could not update . The log says why.`; the parse error is in its log. + +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 +353,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..9e67107 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 service as `aranet server`: the API, the dashboard, the WebSocket, `/metrics`, webhooks, InfluxDB export, mDNS and retention. It has no MQTT (so no Home Assistant discovery), no Prometheus push gateway and no desktop notifications: their settings are accepted in `server.toml` but do nothing there. For those, use the standalone `aranet-service` binary from `cargo install aranet-service --features full`, which can also install itself as a service, or the Docker image, which is built the same way (a container has no desktop for notifications to appear on). ## 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. A LaunchDaemon that 0.2.x installed keeps running the service as root after an upgrade: remove it with `sudo aranet-service service uninstall`, then run `aranet-service service install --user`. Every `aranet-service service` command prints a warning while it is still there. + ### 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,143 @@ 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 + After a re-install over a running service, use `sudo systemctl restart aranet`: `start` does nothing to a service that is already running. + +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. The service can read a config outside `/var/lib/aranet` but not change it: add sensors by editing the file, and if you set `security.api_key_enabled = true`, set `security.api_key` there yourself. `service install --database ` is refused unless the file is in `/var/lib/aranet`, the only directory the service can write. + +The unit reads environment settings from `/etc/default/aranet` if that file exists. It is the place for `RUST_LOG` and other variables, one `NAME=value` per line, for example `RUST_LOG=aranet_core=info`; restart the service after changing it. + +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 ``` -### User-Level Service +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). With the released `aranet` binary under this unit (next section), alerts go out by webhooks only: `aranet server` has no MQTT. + +#### Running the released `aranet` binary + +The release downloads contain `aranet`, not `aranet-service`. `aranet server` runs the service without MQTT, the Prometheus push gateway and desktop notifications (see the top of this page), so its alerts go out by webhooks. To run it under this unit, copy it where only root can change it, install the unit from a clone of the repository, and replace the unit's command with a drop-in: ```bash -# Create user service directory -mkdir -p ~/.config/systemd/user +sudo install -o root -g root -m 0755 ~/.cargo/bin/aranet /usr/local/bin/aranet +# The next line needs a clone of the repository: git clone https://github.com/cameronrye/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 -# Copy service file -cp distribution/systemd/aranet.service ~/.config/systemd/user/ +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, do these steps once, right after the first install. The third one deletes the new service's database, which is still empty then: once the service has stored readings of its own, do not run the steps again. `sudo aranet-service service install` prints them for as long as it finds the old config: -# Edit to remove User/Group and adjust paths -# Then enable -systemctl --user daemon-reload -systemctl --user enable --now dev.rye.aranet +```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 +sudo mv /root/.config/aranet /root/.config/aranet.moved # the steps are then no longer printed ``` +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`. The last line moves the old config directory away, because its `server.toml` is what makes the installer print the steps. + +### User Service + +A user service runs as you, with `~/.config/aranet/server.toml` and your own database, and needs no root: + +```bash +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. + +## Windows + +`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. Under `aranet server`, alerts go out by webhooks: the released `aranet` has no MQTT and no desktop notifications. 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. An image built after you put an API key, an MQTT password or a webhook URL into that file contains them: don't push or share such an image, or keep them in a config outside the checkout and mount that. 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 +216,83 @@ 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. Its first write also makes the file readable only by its owner, uid 999, so reading or editing it on the host then needs `sudo`. + +### 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. The mount gives the container the host's whole system bus, with the rights of uid 999 on the host: BlueZ (pairing and removing devices, switching the adapter off) and every other service on the bus that admits that uid. `:ro` only keeps the container from changing the directory: it can still send requests through the socket in it. 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`. The image passes `--config /app/server.toml` itself, so `docker run … aranet-service --config ` stops with a usage error (`the argument '--config ' cannot be used multiple times`): mount your file over `/app/server.toml` instead. + ### 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 + stop_grace_period: 30s # a clean shutdown can take up to 20 s; Docker's default is 10 s 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 +301,11 @@ bind = "127.0.0.1:8080" [storage] path = "~/.local/share/aranet/data.db" +# Optional: delete old data at startup and hourly (off by default) +# [storage.retention] +# readings_days = 90 +# history_days = 365 + [prometheus] enabled = true @@ -253,14 +315,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. Both limits apply to everything in the database, including readings that the `aranet` CLI, TUI and GUI stored there: they share the database unless the service has its own, as under the systemd system service and in Docker. `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 +378,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. A redirect is never followed: an endpoint that answers `301`, `302`, `307` or `308` counts as failed, so give the endpoint's final URL. 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 +395,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. So is one that it answers with a redirect, which the service never follows: set `url` to InfluxDB's final address. 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 +439,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 ``` +The systemd system service doesn't see variables exported in a shell: set them in `/etc/default/aranet` (see [System Service](#system-service)). 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 +460,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 +488,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 +552,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 +584,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..41b921e 100644 --- a/website/src/content/docs/docs/service/home-assistant.mdx +++ b/website/src/content/docs/docs/service/home-assistant.mdx @@ -9,7 +9,7 @@ aranet-service can publish sensor readings to MQTT and optionally register suppo ## Prerequisites -- `aranet-service` running with MQTT enabled +- `aranet-service` built with MQTT support, running with MQTT enabled: the binary from `cargo install aranet-service --features full`, or the Docker image. `aranet server` from the released `aranet` CLI has no MQTT - A reachable MQTT broker such as Mosquitto or EMQX - Home Assistant with the MQTT integration configured @@ -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 @@ -155,6 +156,10 @@ automation: ## Troubleshooting +### Nothing is published + +A build with MQTT support logs `Starting MQTT publisher to …` or `MQTT publisher is disabled` when it starts. If the log has neither line, the binary has no MQTT support: `aranet server` from the released `aranet` CLI doesn't, and neither does `aranet-service` built without the `mqtt` feature, which `--features full` includes. `[mqtt]` settings are accepted there but do nothing. + ### Entities do not appear 1. Confirm the broker is reachable. @@ -169,7 +174,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 +182,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..e2f1f32 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 |