feat(linux): add persistent Avahi discovery for InfluxDB
Add a Debian NUC installer, IPv4 service definition and usage guide with backup and legacy alias migration. Document the user-confirmed SEN54-to-InfluxDB connection without including credentials.
This commit is contained in:
@@ -0,0 +1,158 @@
|
||||
# InfluxDB auf dem Linux-NUC per Avahi bekannt machen
|
||||
|
||||
Diese Dateien richten eine dauerhafte mDNS/DNS-SD-Ankündigung für die vorhandene
|
||||
ESP32-Firmware ein. Avahi läuft auf dem **Debian-13-NUC**, außerhalb von Docker.
|
||||
Die Konfiguration wird nach einem NUC-Neustart automatisch geladen.
|
||||
|
||||
## Vorgesehener Aufbau
|
||||
|
||||
| Einstellung | Wert |
|
||||
| --- | --- |
|
||||
| NUC-WLAN/AP-Interface | `wlp2s0` |
|
||||
| NUC-WLAN-Adresse | `192.168.50.1/24` |
|
||||
| InfluxDB-URL für den ESP | `http://192.168.50.1:8086` |
|
||||
| Diensttyp | `_influxdb2._tcp.local.` |
|
||||
| Dienstname | `nanoPSX InfluxDB NUC` |
|
||||
| mDNS-Hostname | vorhandener Avahi-Hostname, auf diesem NUC `nuc.local` |
|
||||
|
||||
Der ESP muss mit dem NUC-WLAN verbunden sein. Der InfluxDB-Container muss Port
|
||||
8086 an `192.168.50.1` veröffentlichen; das ist beim untersuchten NUC bereits
|
||||
eingerichtet. Ein fehlender Listener an `127.0.0.1:8086` ist dabei erwartbar.
|
||||
|
||||
Der Dienst verwendet den vorhandenen Avahi-Hostnamen (`nuc.local` auf diesem
|
||||
NUC). Es wird kein zusätzlicher Hostname für dieselbe IP registriert, da dies bei
|
||||
Avahi eine lokale Namenskollision verursachen kann. Auf dem WLAN muss die
|
||||
Auflösung `192.168.50.1` liefern; dies nach der Installation prüfen. Die allgemeine
|
||||
Avahi-Interface-Konfiguration bleibt erhalten. Die Ankündigung kann auch auf
|
||||
anderen von Avahi bedienten Interfaces sichtbar sein. Kein mDNS-Reflector wird
|
||||
eingerichtet.
|
||||
|
||||
## Installation
|
||||
|
||||
1. Das Projekt oder mindestens den vollständigen Ordner `linux-app` auf den NUC
|
||||
kopieren. Die folgenden Befehle dort in einer lokalen Shell ausführen.
|
||||
2. Das frühere Python-mDNS-Skript bzw. dessen Systemdienst für diese
|
||||
InfluxDB-Ankündigung beenden und dessen Autostart deaktivieren. Ebenso einen
|
||||
laufenden Test mit `avahi-publish-service` beenden. Andere mDNS-Dienste erhalten.
|
||||
3. Im Projektverzeichnis ausführen:
|
||||
|
||||
```bash
|
||||
sudo bash linux-app/install-avahi.sh
|
||||
```
|
||||
|
||||
Das Skript prüft die AP-Adresse und InfluxDB `/health`, installiert mit APT
|
||||
`avahi-daemon`, `avahi-utils`, `curl` und `python3`, sichert vorhandene Dateien
|
||||
unter `/var/backups/nanopsx-avahi/install.*` und installiert:
|
||||
|
||||
- `/etc/avahi/services/nanopsx-influxdb.service`
|
||||
- keinen neuen Eintrag in `/etc/avahi/hosts`. Der exakt markierte Alias der ersten
|
||||
Skriptversion wird nach Sicherung entfernt, falls vorhanden.
|
||||
|
||||
Andere Hosteinträge und Dienste bleiben erhalten. Eine unbekannte abweichende
|
||||
Dienstdatei führt zum Abbruch. Die unveränderte erste Version der mitgelieferten
|
||||
Dienstdatei wird anhand ihres SHA-256 erkannt und automatisch aktualisiert.
|
||||
Wiederholtes Ausführen mit unveränderten Einstellungen erzeugt keine doppelten
|
||||
Hosteinträge. Ein fehlgeschlagener Installationslauf ist kein Erfolgsnachweis;
|
||||
die ausgegebenen Fehler zuerst prüfen. Bereits installierte Pakete bleiben bei
|
||||
einem späteren Fehler installiert.
|
||||
|
||||
Es werden weder Docker, Firewall, WireGuard, SSH noch ESP-Firmware geändert.
|
||||
Es sind keine Influx-Tokens oder WLAN-Passwörter in diesen Dateien erforderlich.
|
||||
|
||||
## Funktion prüfen
|
||||
|
||||
Auf dem NUC:
|
||||
|
||||
```bash
|
||||
systemctl is-enabled avahi-daemon.service
|
||||
systemctl is-active avahi-daemon.service
|
||||
curl --noproxy '*' -fsS --max-time 5 http://192.168.50.1:8086/health
|
||||
avahi-browse -r -t _influxdb2._tcp
|
||||
```
|
||||
|
||||
Erwartet: `enabled`, `active`, Health-Status `pass` und beim aufgelösten Dienst
|
||||
auf Interface `wlp2s0` mit IPv4 die Adresse `192.168.50.1`, Port `8086`
|
||||
und Hostname `nuc.local` (sofern der Rechnername nicht geändert wurde).
|
||||
`avahi-browse` unterstützt weder `-4` noch `-i`; die Ausgabe enthält Interface
|
||||
und IP-Protokoll als Spalten.
|
||||
Zusätzlich von einem anderen Linux-Rechner im NUC-WLAN prüfen, sofern verfügbar:
|
||||
|
||||
```bash
|
||||
avahi-browse -r -t _influxdb2._tcp
|
||||
curl --noproxy '*' -fsS --max-time 5 http://192.168.50.1:8086/health
|
||||
```
|
||||
|
||||
Ein lokaler NUC-Test allein beweist noch keine Erreichbarkeit vom ESP.
|
||||
Die Firmware sucht ungefähr alle 60 Sekunden, bis sie einen Dienst gefunden
|
||||
hat, und speichert dessen URL. Hat sie bereits einen anderen Dienst gefunden,
|
||||
den ESP einmal neu starten, nachdem die richtige Ankündigung aktiv ist.
|
||||
|
||||
Die seriellen ESP-Logs sollen anschließend `mDNS URL: http://192.168.50.1:8086`
|
||||
zeigen. Erst erfolgreiche Influx-Schreibvorgänge mit HTTP-Status `204` und
|
||||
aktuelle Messwerte im Influx-Bucket bestätigen die vollständige Verbindung.
|
||||
Organisation, Bucket und ein Token mit Schreibrecht für diesen Bucket müssen
|
||||
zusätzlich im ESP-Konfigurationsportal hinterlegt sein. Tokens dort lokal
|
||||
eingeben und nicht in Git oder Diagnoseausgaben veröffentlichen.
|
||||
|
||||
Avahi kündigt statisch an: Es überwacht die Verfügbarkeit des Containers nicht.
|
||||
Die Installation prüft `/health` einmalig. Nach einem NUC-Neustart kann die
|
||||
Ankündigung schon sichtbar sein, bevor InfluxDB bereit ist; die Firmware muss
|
||||
Verbindungsversuche wiederholen.
|
||||
|
||||
## Fehler untersuchen
|
||||
|
||||
```bash
|
||||
journalctl -u avahi-daemon.service -b --no-pager -n 80
|
||||
ip -br -4 addr
|
||||
ss -ltn '( sport = :8086 )'
|
||||
```
|
||||
|
||||
- Kein Dienst gefunden: Avahi-Status und Logs prüfen. In
|
||||
`/etc/avahi/avahi-daemon.conf` darf `wlp2s0` nicht ausgeschlossen und Publishing
|
||||
nicht deaktiviert sein. Das Installationsskript überschreibt diese Einstellungen
|
||||
bewusst nicht.
|
||||
- Nur lokal sichtbar: Firewall für mDNS (UDP 5353, IPv4-Multicast
|
||||
`224.0.0.251`) auf dem WLAN und mögliche AP-Client-Isolation prüfen.
|
||||
- HTTP-Timeout: TCP 8086 vom WLAN, Docker-Portfreigabe und Firewall prüfen.
|
||||
- HTTP 401/403: Influx-Token und dessen Bucket-Schreibrechte prüfen.
|
||||
- Mehrere Influx-Dienste: Die Firmware nimmt einen passenden Treffer. Alte
|
||||
konkurrierende Ankündigungen entfernen, bevor die Erkennung erneut startet.
|
||||
|
||||
Keine Firewall-Regeln pauschal löschen und keine unbekannten Dienste abschalten.
|
||||
Für einen anderen AP die Adresse und das Interface im Installationsskript
|
||||
gezielt anpassen und die Auflösung auf dem neuen WLAN prüfen.
|
||||
|
||||
## Ankündigung entfernen
|
||||
|
||||
Nur die von dieser Einrichtung angelegten Einträge entfernen:
|
||||
|
||||
```bash
|
||||
sudo rm /etc/avahi/services/nanopsx-influxdb.service
|
||||
sudo systemctl reload avahi-daemon.service
|
||||
```
|
||||
|
||||
Falls die Dateien inzwischen manuell geändert wurden, vor dem Entfernen prüfen.
|
||||
Vorhandene Hosteinträge bleiben erhalten. Avahi und seine anderen Dienste bleiben aktiv. Die Sicherung enthält
|
||||
die vorherigen Dateien; diese nicht pauschal zurückkopieren, wenn inzwischen
|
||||
weitere Änderungen vorgenommen wurden.
|
||||
|
||||
## Referenzen
|
||||
|
||||
- [Debian: statische Avahi-Dienste](https://manpages.debian.org/trixie/avahi-daemon/avahi.service.5.en.html)
|
||||
- [Debian: avahi-browse und gültige Optionen](https://manpages.debian.org/trixie/avahi-utils/avahi-browse.1.en.html)
|
||||
- [InfluxDB: Health-Prüfung](https://docs.influxdata.com/influxdb/v2/api/health/)
|
||||
|
||||
## Getesteter Stand (2026-11-07)
|
||||
|
||||
Skriptsyntax, XML, Installation und Migration der ersten Konfiguration wurden
|
||||
im Entwicklungscontainer mit isolierten Systemaufrufen geprüft. Der Benutzer
|
||||
hat die Konfiguration auf dem Debian-NUC installiert und die korrigierte
|
||||
Dienstdatei ohne zusätzlichen Hostnamen eingesetzt. Seine `avahi-browse`-Ausgabe
|
||||
bestätigt auf `wlp2s0` die Auflösung von `nuc.local` zu `192.168.50.1:8086`.
|
||||
|
||||
Serielle Tests des ESP bestätigten anschließend HTTP-Verbindungen zu dieser
|
||||
Adresse. Nach Einrichtung von Organisation `Home`, Bucket `nanoPSX` und einem
|
||||
passenden Token hat der Benutzer die funktionierende SEN54-Übertragung zu
|
||||
InfluxDB bestätigt. Diese abschließende Funktionsbestätigung stammt vom Benutzer;
|
||||
eine weitere serielle Aufzeichnung mit erfolgreichen Schreibantworten wurde
|
||||
danach nicht erstellt. Zugangsdaten gehören nicht in diese Dokumentation.
|
||||
@@ -0,0 +1,11 @@
|
||||
<?xml version="1.0" standalone="no"?>
|
||||
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
|
||||
<service-group>
|
||||
<name replace-wildcards="no">nanoPSX InfluxDB NUC</name>
|
||||
<service protocol="ipv4">
|
||||
<type>_influxdb2._tcp</type>
|
||||
<domain-name>local</domain-name>
|
||||
<port>8086</port>
|
||||
<txt-record>path=/</txt-record>
|
||||
</service>
|
||||
</service-group>
|
||||
@@ -0,0 +1,80 @@
|
||||
#!/usr/bin/env bash
|
||||
# Auf dem Debian-NUC ausführen, nicht im Codex- oder InfluxDB-Container.
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
|
||||
SOURCE="$SCRIPT_DIR/avahi/nanopsx-influxdb.service"
|
||||
DEST=/etc/avahi/services/nanopsx-influxdb.service
|
||||
HOSTS=/etc/avahi/hosts
|
||||
AP_INTERFACE=wlp2s0
|
||||
AP_ADDRESS=192.168.50.1
|
||||
# Exakter Hash unserer ersten Version: nur diese darf automatisch migriert werden.
|
||||
LEGACY_SERVICE_SHA256=b5dadb78f624dd5e6e4fa8b7243af23b687e1adf9c88712207510a4c52bc7357
|
||||
|
||||
if (( EUID != 0 )); then
|
||||
echo "Bitte auf dem NUC mit sudo bash $0 ausführen." >&2
|
||||
exit 1
|
||||
fi
|
||||
if [[ ! -f /etc/debian_version || ! -d /run/systemd/system ]]; then
|
||||
echo 'Benötigt einen Debian/Ubuntu-Host mit laufendem systemd.' >&2
|
||||
exit 1
|
||||
fi
|
||||
if ! ip -4 -o addr show dev "$AP_INTERFACE" | awk '{print $4}' | cut -d/ -f1 | grep -Fxq "$AP_ADDRESS"; then
|
||||
echo "Die erwartete AP-Adresse $AP_ADDRESS fehlt auf $AP_INTERFACE. Abbruch." >&2
|
||||
exit 1
|
||||
fi
|
||||
for target in "$HOSTS" "$DEST"; do
|
||||
if [[ -L "$target" || ( -e "$target" && ! -f "$target" ) ]]; then
|
||||
echo "Unerwarteter Dateityp: $target. Abbruch." >&2
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
if [[ -e "$DEST" ]] && ! cmp -s "$SOURCE" "$DEST"; then
|
||||
if [[ $(sha256sum "$DEST" | cut -d' ' -f1) != "$LEGACY_SERVICE_SHA256" ]]; then
|
||||
echo "Abweichende Dienstdatei $DEST vorhanden; bitte zuerst manuell prüfen." >&2
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
apt-get update
|
||||
apt-get install -y avahi-daemon avahi-utils curl python3
|
||||
|
||||
# Vor jeder Änderung: InfluxDB muss an der tatsächlich angekündigten IP antworten.
|
||||
curl --noproxy '*' --fail --silent --show-error --max-time 5 \
|
||||
"http://$AP_ADDRESS:8086/health" |
|
||||
python3 -c 'import json, sys; d=json.load(sys.stdin); sys.exit(0 if d.get("status")=="pass" else "InfluxDB health meldet nicht pass; Abbruch.")'
|
||||
|
||||
install -d -m 700 /var/backups/nanopsx-avahi
|
||||
BACKUP=$(mktemp -d /var/backups/nanopsx-avahi/install.XXXXXXXX)
|
||||
for target in "$HOSTS" "$DEST"; do
|
||||
if [[ -e "$target" ]]; then
|
||||
cp -a -- "$target" "$BACKUP/$(basename -- "$target")"
|
||||
else
|
||||
touch "$BACKUP/$(basename -- "$target").was-absent"
|
||||
fi
|
||||
done
|
||||
echo "Sicherung vor Änderungen: $BACKUP"
|
||||
|
||||
install -d -m 755 /etc/avahi/services
|
||||
# Ausschließlich den von unserer ersten Version angelegten Alias entfernen.
|
||||
# Avahi verwendet für den Dienst seinen vorhandenen lokalen Hostnamen.
|
||||
python3 - "$HOSTS" <<'PY'
|
||||
from pathlib import Path
|
||||
import sys
|
||||
|
||||
p = Path(sys.argv[1])
|
||||
if p.exists():
|
||||
original = p.read_bytes()
|
||||
cleaned = b"".join(line for line in original.splitlines(keepends=True)
|
||||
if line.rstrip(b"\r\n") !=
|
||||
b"192.168.50.1 nanopsx-influx.local # nanopsx-avahi")
|
||||
if cleaned != original:
|
||||
p.write_bytes(cleaned)
|
||||
PY
|
||||
install -o root -g root -m 644 "$SOURCE" "$DEST"
|
||||
|
||||
systemctl enable --now avahi-daemon.service
|
||||
systemctl reload avahi-daemon.service
|
||||
systemctl is-active --quiet avahi-daemon.service
|
||||
echo "Avahi läuft und startet beim Booten. Ziel: http://$AP_ADDRESS:8086"
|
||||
echo 'Die erfolgreiche mDNS-Auflösung und ESP-Übertragung jetzt gemäß README prüfen.'
|
||||
Reference in New Issue
Block a user