Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .github/scripts/test-mqtt-car-user/compose.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# The broker for run.sh: built from docker/mosquitto, with the repository's
# broker.conf and car.acl, as on routy. SECRETS_DIR holds a test password file.
services:
broker:
build: ../../../docker/mosquitto
volumes:
- ../../../config/mosquitto/broker.conf:/mosquitto/config/mosquitto.conf:ro
- ../../../config/mosquitto/car.acl:/mosquitto/config/car.acl:ro
- ${SECRETS_DIR:?run run.sh}:/mosquitto/secrets:ro

# The same broker when the deploy has no password file.
broker-nopass:
build: ../../../docker/mosquitto
volumes:
- ../../../config/mosquitto/broker.conf:/mosquitto/config/mosquitto.conf:ro
- ../../../config/mosquitto/car.acl:/mosquitto/config/car.acl:ro
123 changes: 123 additions & 0 deletions .github/scripts/test-mqtt-car-user/run.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
#!/usr/bin/env bash
# Integration test for the car-only MQTT user (#1962), with the real broker
# config (config/mosquitto/broker.conf, car.acl) and image (docker/mosquitto).
#
# Port 1883 is anonymous; port 1884 needs a login and uses car.acl. Checks:
# a. the car user can publish to its own topic (ioniq/...);
# b. it can read homy/ioniq/journeys and homy/ioniq/road_check;
# c. it cannot publish to homy/ioniq/journeys;
# d. it cannot read or write any other topic, also ioniq/derived/...;
# e. a client without a login, or with a wrong password, cannot use 1884;
# f. with no password file the broker still starts, 1883 works, and nobody
# can log in on 1884.
# The broker drops a publish the ACL denies without an error, so every check
# reads a retained message back.
#
# Needs docker (with compose). Run from anywhere.
set -euo pipefail

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
WORK="$(mktemp -d)"
export SECRETS_DIR="$WORK/secrets"
mkdir "$SECRETS_DIR"

dc() { docker compose -p mqtt-car-user-test -f "$HERE/compose.yml" "$@"; }
cleanup() {
status=$?
if [ "$status" -ne 0 ]; then dc logs | tail -40 || true; fi
dc down -v --remove-orphans >/dev/null 2>&1 || true
rm -rf "$WORK"
exit "$status"
}
trap cleanup EXIT

fail() { echo "FAIL: $*"; exit 1; }
log() { echo "[$(date +%T)] $*"; }

# wait_for SECONDS DESCRIPTION COMMAND...: runs COMMAND every 2s until it succeeds.
wait_for() {
local limit=$1 what=$2; shift 2
local end=$((SECONDS + limit))
until "$@" >/dev/null 2>&1; do
[ "$SECONDS" -lt "$end" ] || fail "timed out after ${limit}s waiting for: $what"
sleep 2
done
log "ok: $what"
}

log "starting the broker"
dc build --quiet
# The password file, made the way docs/mqtt-car-user.md says.
dc run --rm --no-deps -T -v "$SECRETS_DIR:/out" --entrypoint mosquitto_passwd broker \
-c -b /out/passwd ioniq test-password
dc up -d broker broker-nopass

SVC=broker
# anon ARGS...: mosquitto_pub/sub on 1883 without a login. car: on 1884 as the car.
pub_anon() { dc exec -T "$SVC" mosquitto_pub -p 1883 -q 1 -r "$@"; }
pub_car() { dc exec -T "$SVC" mosquitto_pub -p 1884 -u ioniq -P test-password -q 1 -r "$@"; }
# retained TOPIC (anonymous) / retained_car TOPIC: the retained message, or
# nothing after 3s.
retained() { dc exec -T "$SVC" mosquitto_sub -p 1883 -C 1 -W 3 -t "$1" 2>/dev/null || true; }
retained_car() { dc exec -T "$SVC" mosquitto_sub -p 1884 -u ioniq -P test-password -C 1 -W 3 -t "$1" 2>/dev/null || true; }
# refused SERVICE ARGS...: mosquitto_pub ARGS fails because the broker says
# "not authorised" (not because nothing listens).
refused() {
local svc=$1 out; shift
if out=$(dc exec -T "$svc" mosquitto_pub "$@" 2>&1); then return 1; fi
grep -q "not authorised" <<<"$out"
}
is() { [ "$1" = "$2" ] || fail "$3: got '$1', want '$2'"; log "ok: $3"; }

wait_for 30 "broker is up" dc exec -T broker mosquitto_sub -p 1883 -t '$SYS/#' -C 1
wait_for 30 "car can log in" dc exec -T broker mosquitto_sub -p 1884 -u ioniq -P test-password -t ioniq/status -E

# a. its own topics, also the will/status topic.
pub_car -t ioniq/parsed/gps -m car-gps
is "$(retained ioniq/parsed/gps)" car-gps "a: car publishes ioniq/parsed/gps"
pub_car -t ioniq/status -m '{"online":true}'
is "$(retained ioniq/status)" '{"online":true}' "a: car publishes ioniq/status"

# b. what ev-journal publishes for the car.
pub_anon -t homy/ioniq/journeys -m journeys-1
pub_anon -t homy/ioniq/road_check -m road-1
is "$(retained_car homy/ioniq/journeys)" journeys-1 "b: car reads homy/ioniq/journeys"
is "$(retained_car homy/ioniq/road_check)" road-1 "b: car reads homy/ioniq/road_check"

# c. no write to ev-journal's topics.
pub_car -t homy/ioniq/journeys -m from-car || true
is "$(retained homy/ioniq/journeys)" journeys-1 "c: car cannot publish homy/ioniq/journeys"
pub_car -t homy/ioniq/notice -m from-car || true
is "$(retained homy/ioniq/notice)" "" "c: car cannot publish homy/ioniq/notice"

# d. nothing else.
pub_anon -t homy/other/state -m other-1
is "$(retained_car homy/other/state)" "" "d: car cannot read homy/other/state"
is "$(retained_car homy/ioniq/charges)" "" "d: car cannot read homy/ioniq/charges"
pub_car -t homy/other/state -m from-car || true
is "$(retained homy/other/state)" other-1 "d: car cannot publish homy/other/state"
pub_car -t other/x -m from-car || true
is "$(retained other/x)" "" "d: car cannot publish other/x"
pub_anon -t ioniq/derived/trip -m trip-1
pub_car -t ioniq/derived/trip -m from-car || true
is "$(retained ioniq/derived/trip)" trip-1 "d: car cannot publish ioniq/derived/trip"

# e. no login, or a wrong one, on the car's listener.
refused broker -p 1884 -t ioniq/status -m anon ||
fail "e: a client without a login could publish on 1884"
log "ok: e: no login is refused on 1884"
refused broker -p 1884 -u ioniq -P wrong -t ioniq/status -m bad ||
fail "e: a wrong password could publish on 1884"
log "ok: e: a wrong password is refused on 1884"
is "$(retained ioniq/status)" '{"online":true}' "e: ioniq/status unchanged"

# f. no password file.
SVC=broker-nopass
wait_for 30 "broker without a password file is up" dc exec -T broker-nopass mosquitto_sub -p 1883 -t '$SYS/#' -C 1
pub_anon -t test/anon -m anon-1
is "$(retained test/anon)" anon-1 "f: 1883 works without a password file"
refused broker-nopass -p 1884 -u ioniq -P test-password -t ioniq/status -m x ||
fail "f: the car could log in without a password file"
log "ok: f: nobody can log in on 1884 without a password file"

log "PASS"
36 changes: 36 additions & 0 deletions .github/workflows/test-mqtt-car-user.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
name: Test MQTT Car User

# Integration test for the car-only MQTT user (#1962): the real broker image
# and config, the car user's ACL on the login-only listener, and a broker
# without a password file. See .github/scripts/test-mqtt-car-user/run.sh.

on:
push:
branches:
- master
paths:
- 'config/mosquitto/**'
- 'docker/mosquitto/**'
- '.github/scripts/test-mqtt-car-user/**'
- '.github/workflows/test-mqtt-car-user.yml'
pull_request:
paths:
- 'config/mosquitto/**'
- 'docker/mosquitto/**'
- '.github/scripts/test-mqtt-car-user/**'
- '.github/workflows/test-mqtt-car-user.yml'
workflow_dispatch:

jobs:
test:
name: Test MQTT car user
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
steps:
- name: Checkout code
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

- name: Run integration test
run: .github/scripts/test-mqtt-car-user/run.sh
20 changes: 18 additions & 2 deletions config/mosquitto/broker.conf
Original file line number Diff line number Diff line change
@@ -1,10 +1,26 @@
# This is a Mosquitto configuration file that creates a listener on port 1883
# that allows unauthenticated access.
# Mosquitto configuration for the broker on routy.
# Reference: https://mosquitto.org/man/mosquitto-conf-5.html
#
# Two listeners, each with its own settings:
# 1883: anonymous, for the docker networks and the clients that use it today.
# 1884: login only, for the car app. Its rights are in car.acl (#1962).
# Setup and how to add the car user: docs/mqtt-car-user.md.

per_listener_settings true

listener 1883
allow_anonymous true

listener 1884
allow_anonymous false
# docker/mosquitto/entrypoint.sh copies the deployed password file here, or
# makes an empty one (nobody can log in) when the deploy has none.
password_file /mosquitto/auth/passwd
acl_file /mosquitto/config/car.acl
# Client ids are shared by all listeners. This stops a 1884 user from taking
# the id of a 1883 client and pushing it off the broker.
use_username_as_clientid true

persistence true
# Bind-mounted at ${DATA_PATH}/mosquitto/data (docker-compose.yml); never an
# unnamed Docker volume, so `docker compose down` keeps retained messages.
Expand Down
16 changes: 16 additions & 0 deletions config/mosquitto/car.acl
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Rights of the users on the login-only listener (port 1884, #1962).
# A user not named here may do nothing. No passwords here: those are in the
# password file the deploy provides (docs/mqtt-car-user.md).

# The car app. It publishes ioniq/parsed/#, ioniq/raw/#, ioniq/log and its
# will/status topic ioniq/status. Only those: other ioniq/ topics (such as
# ioniq/derived/#, from the automations) are not the car's. It may read what
# ev-journal publishes for the car, but never write it, and nothing else.
user ioniq
topic readwrite ioniq/parsed/#
topic readwrite ioniq/raw/#
topic readwrite ioniq/log
topic readwrite ioniq/status
topic read homy/ioniq/journeys
topic read homy/ioniq/road_check
topic read homy/ioniq/home
6 changes: 6 additions & 0 deletions docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -102,8 +102,14 @@ services:
- no-new-privileges:true
ports:
- "1883:1883"
# Login only, for the car app (#1962).
- "1884:1884"
volumes:
- ${CONFIG_PATH}/mosquitto/broker.conf:/mosquitto/config/mosquitto.conf:ro
- ${CONFIG_PATH}/mosquitto/car.acl:/mosquitto/config/car.acl:ro
# Holds `passwd`, from the deploy; never in the repo. A folder, not the
# file, so a missing file does not stop the broker (entrypoint.sh).
- ${SECRETS_PATH}/mosquitto:/mosquitto/secrets:ro
# The image declares both as VOLUMEs; without a mount here docker makes
# unnamed volumes that `down` throws away with the retained messages.
- ${DATA_PATH}/mosquitto/data:/mosquitto/data
Expand Down
5 changes: 5 additions & 0 deletions docker/mosquitto/Dockerfile
Original file line number Diff line number Diff line change
@@ -1,4 +1,9 @@
FROM ghcr.io/groupsky/homy/mosquitto:2.0.22

COPY entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
# Setting ENTRYPOINT clears the base image's CMD, so set it again.
CMD ["/usr/sbin/mosquitto", "-c", "/mosquitto/config/mosquitto.conf"]

HEALTHCHECK --interval=30s --timeout=5s --retries=6 \
CMD mosquitto_sub -i healthcheck -t '$SYS/#' -C 1 | grep -v Error || exit 1
20 changes: 20 additions & 0 deletions docker/mosquitto/entrypoint.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
#!/bin/ash
# The broker reads its password file as user mosquitto and stops when it
# cannot. The deployed file (in a read-only secrets folder) may be owned by
# another user, or missing. So copy it to a place the broker owns; when it
# is missing, use an empty file: the broker starts and nobody can log in on
# the login-only listener.
set -e
src=/mosquitto/secrets/passwd
dst=/mosquitto/auth/passwd
mkdir -p /mosquitto/auth
if [ -f "$src" ]; then
cp "$src" "$dst"
else
echo "entrypoint: no $src, the login-only listener has no users" >&2
: > "$dst"
fi
chown -R mosquitto:mosquitto /mosquitto/auth
chmod 0700 /mosquitto/auth
chmod 0600 "$dst"
exec /docker-entrypoint.sh "$@"
1 change: 1 addition & 0 deletions docs/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ This directory contains technical documentation for the home automation system.
- **IMPORTANT**: Always keep the specification and diagram synchronized when making changes

### Vehicle Telemetry
- **[Car-only MQTT user](mqtt-car-user.md)** - The login-only broker listener (port 1884) for the car app, its ACL, the password file the deploy provides and how to add the car user
- **[Kitchen oven](oven.md)** - The Home Connect oven: MQTT topics of the hcpy bridge, the `oven` InfluxDB measurement, and the parents-only oven card (it only hides the card)
- **[Ioniq EV Monitoring & Alerting](ioniq-monitoring-alerting-spec.md)** - Monitoring and alerting specification for the Hyundai Ioniq Electric (battery / 12 V / tires / DTC alerts, Grafana rules, and automations bots over the OBD-logger telemetry)

Expand Down
2 changes: 1 addition & 1 deletion docs/DEPLOYMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -351,7 +351,7 @@ Every service with state keeps it in a host directory under `${DATA_PATH}` (a bi
| Service | Host directory | Container path |
|---|---|---|
| `mongo` | `${DATA_PATH}/mongodb/db`, `${DATA_PATH}/mongodb/configdb` (owned by 999:999) | `/data/db`, `/data/configdb` |
| `broker` | `${DATA_PATH}/mosquitto/data`, `${DATA_PATH}/mosquitto/log` | `/mosquitto/data`, `/mosquitto/log` |
| `broker` | `${DATA_PATH}/mosquitto/data`, `${DATA_PATH}/mosquitto/log`; reads `${SECRETS_PATH}/mosquitto` (password file, [mqtt-car-user.md](mqtt-car-user.md)) | `/mosquitto/data`, `/mosquitto/log`; `/mosquitto/secrets` |
| every `modbus-serial` service, every ya-modbus adapter (`tetriary-adapter`, `main-adapter`) and `mqtt-ndjson-ioniq` (raw readings, #1622) | `${RAW_DATA_PATH}` = `${DATA_PATH}/raw`, owned by 1000:1000, shared by all of them | `/data/raw` |

**The raw directory must be a plain subdirectory of `${DATA_PATH}`, on the same ZFS dataset — not a dataset of its own**, even though it grows by about 770 MB a day. `snapshot.sh` stops when the writable mounts are on more than one dataset, and it counts a child dataset as a different one: a separate dataset for it would stop every deploy at the snapshot step.
Expand Down
71 changes: 71 additions & 0 deletions docs/mqtt-car-user.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# The car-only MQTT user

The car app keeps its MQTT user name and password in plain text on its
device. So the user it holds may do very little (#1962).

## Two listeners

The broker (`config/mosquitto/broker.conf`) has two listeners, each with its
own settings (`per_listener_settings true`):

| Port | Login | Rights | Used by |
|---|---|---|---|
| 1883 | none (anonymous) | everything | every service on the docker networks (`broker:1883`), and the clients that use the published port today |
| 1884 | required | only what `config/mosquitto/car.acl` gives | the car app |

Both ports are published on routy. Port 1883 stays anonymous: other clients
use the published port without a login today, so a login there would stop
them. Closing 1883 to everything outside the docker networks is a later
step, after those clients have their own logins.

## What the car user may do (`car.acl`)

User `ioniq` (the user name the car app already sends):

- **read and write** the car app's own topics: `ioniq/parsed/#`,
`ioniq/raw/#`, `ioniq/log` and its will/status topic `ioniq/status`. Not
other `ioniq/` topics: `ioniq/derived/#` comes from the automations.
- **read only** `homy/ioniq/journeys`, `homy/ioniq/road_check` and
`homy/ioniq/home`, which ev-journal publishes for the car.
- nothing else: no write to any `homy/ioniq/` topic, and no other topic.

On 1884 the broker uses the user name as the client id
(`use_username_as_clientid`), so the car cannot take the id of another client.

A user on port 1884 that `car.acl` does not name may do nothing.

## The password file the deploy must provide

`${SECRETS_PATH}/mosquitto/passwd`, a mosquitto password file. It is never
in the repo. `docker-compose.yml` mounts the folder `${SECRETS_PATH}/mosquitto`
read-only, and `docker/mosquitto/entrypoint.sh` copies `passwd` to a place
the broker owns when the broker starts. When the file is missing, the broker
still starts with no users: port 1883 works, and nobody can log in on 1884.

## Add the car user

On routy, in the homy folder (`SECRETS_PATH` from `.env`):

```bash
mkdir -p "$SECRETS_PATH/mosquitto"
# Asks for the password twice. Run again with another user to add more;
# leave out -c then, or it makes a new file.
docker compose run --rm --no-deps -v "$SECRETS_PATH/mosquitto:/out" \
--entrypoint mosquitto_passwd broker -c /out/passwd ioniq
docker compose restart broker
```

Then, in the car app's settings: port 1884, user `ioniq`, and the password.

To change the password, run the same command without `-c`, then restart the
broker. To remove the user, then restart the broker:

```bash
docker compose run --rm --no-deps -v "$SECRETS_PATH/mosquitto:/out" \
--entrypoint mosquitto_passwd broker -D /out/passwd ioniq
```

## Test

`.github/scripts/test-mqtt-car-user/run.sh` (CI: `test-mqtt-car-user.yml`)
starts the real broker image with this config and checks each rule above.
Loading