add warn on dnssd name collision change spec

2026-10-20 10:05:00 +02:00
1 parent 30670de93b
commit 3910ab974c
@@ -0,0 +1,90 @@
+# Tasks
+
+## 1. entrypoint: Erkennung von DNS-SD-Namenskollisionen
+
+- [ ] 1.1 `entrypoint.sh`: Funktion `check_dnssd_name_collisions` ergänzen,
+      aufgerufen nach dem TCP-631-Check und vor
+      `log "ready: CUPS on 631/tcp, mDNS on 5353/udp"`. Queue-Namen und
+      Descriptions via `LC_ALL=C lpstat -l -p` lesen (Locale-fest, live aus
+      cupsd), Shared-Flag je Queue aus `/etc/cups/printers.conf`
+      (`<Printer …>`-Block, `Shared yes`); unbekannter Shared-Status zählt als
+      geteilt. Pro Queue den Anzeigenamen ableiten: Description, sonst
+      Queue-Name.
+      Verifikation: `sh -n entrypoint.sh` läuft fehlerfrei,
+      `grep -n 'check_dnssd_name_collisions' entrypoint.sh` zeigt Definition
+      und Aufruf an der vorgesehenen Stelle.
+- [ ] 1.2 Bei gleichen abgeleiteten Namen pro Kollisionsgruppe über den
+      bestehenden `log()`-Stil warnen (Mehrzeiler, analog zum TCP-631-Block):
+      kollidierender Anzeigename `<basis> @ <host>`, betroffene Queue-Namen,
+      Abhilfe (einzigartige Description je Queue per `lpadmin -D` oder
+      redundante Queue entfernen per `lpadmin -x`, danach Client-Queue auf dem
+      Mac entfernen und neu hinzufügen — Details im README). Bei eindeutigen
+      Namen keine Warnung ausgeben.
+      Verifikation: `grep -n 'warning:' entrypoint.sh` findet die neuen
+      Warnzeilen inkl. `lpadmin -D`-Remedies; das Verhalten selbst prüfen die
+      Aufgaben 3.2 (Kollision) und 3.3 (keine Kollision).
+- [ ] 1.3 Alle Parseschritte abfangen, ohne dass `set -eu` den Start abbricht
+      (`|| true` / geblockte Substitutionen): fehlendes oder unlesbares
+      `printers.conf`,
+      fehlerhaftes `lpstat` → Prüfung still überspringen oder als geteilt
+      annehmen, niemals `exit` und niemals Abbruch der Queue-Einrichtung.
+      Verifikation: `sh -n entrypoint.sh` fehlerfrei; Startverhalten mit
+      fehlendem `printers.conf` ist in 3.4 abgedeckt.
+
+## 2. README: Troubleshooting und PRINTER_NAME-Korrektur
+
+- [ ] 2.1 `README.md`: neuen Troubleshooting-Abschnitt
+      „macOS shows the printer offline after some time" (englisch, Stil der
+      bestehenden `###`-Abschnitte) einfügen: Symptom (Queue existiert,
+      Status offline, erst nach Stunden/Wechseln sichtbar), Ursache
+      (macOS pinnt den exakten DNS-SD-Instanznamen `"<Description> @ <host>"`
+      in die `dnssd://`-Device-URI; zwei Queues mit gleicher Description
+      kollidieren, Avahi registriert nur eine, CUPS 2.4 benennt nicht um),
+      Diagnose-Befehle (`podman logs` Warnung, `dns-sd -B _ipp._tcp`,
+      `avahi-browse -rt _ipp._tcp`, `lpstat -l -p`, `ipptool -tv`), Heilung
+      (eindeutige Description bzw. `-x`, dann Remove/Re-add auf macOS — mit dem
+      Hinweis, warum Restart allein nicht hilft: Kollision ist deterministisch).
+      Verifikation: jeder im Abschnitt stehende Befehl läuft unverändert gegen
+      den laufenden Container (lokal aus 3.1 bzw. gegen podp).
+- [ ] 2.2 `PRINTER_NAME`-Wording korrigieren: README-Tabelle („Also used as
+      the name advertised via AirPrint/DNS-SD") und Fließtext unter
+      *Environment variables* sowie die Kopfkommentarzeile in
+      `entrypoint.sh` („advertised (DNS-SD) name") präzisieren: Der
+      Queue-Name ist nur die Basis, solange keine Description gesetzt ist —
+      `PRINTER_DESCRIPTION` (bzw. `-D`) hat Vorrang für den Anzeigenamen.
+      Verifikation: `grep -n 'PRINTER_NAME' README.md entrypoint.sh` zeigt an
+      allen drei Stellen die korrigierte Formulierung mit Description-Vorrang.
+
+## 3. Integrationstests (podman, lokal)
+
+- [ ] 3.1 Image bauen und ohne Kollision starten.
+      Verifikation: `podman build -t printserver:latest .` endet ohne Fehler;
+      `podman run …` erreicht „ready: CUPS on 631/tcp, mDNS on 5353/udp";
+      `podman logs` enthält KEINE Kollisions-Warnung (falls 631 nicht bindet:
+      `podman machine ssh -- sudo sysctl -w net.ipv4.ip_unprivileged_port_start=631`
+      wie bei der Vorgängeränderung).
+- [ ] 3.2 Kollision erzeugen und Warnung nachweisen.
+      Verifikation: zweite Queue mit der Description des ersten Queues anlegen
+      (`podman exec printserver lpadmin -p dup -E -v socket://192.0.2.1:9100
+      -D "<identische Description>"`), danach `podman restart printserver`:
+      `podman logs` enthält die Warnung mit Anzeigename, beiden Queue-Namen und
+      Remedie, und der Start endet trotzdem mit „ready" (Warnung nicht fatal).
+- [ ] 3.3 Kollision beheben → Warnung verschwindet.
+      Verifikation: `podman exec printserver lpadmin -p dup -D "Dup Queue"`
+      (eindeutige Description), `podman restart printserver`: das Log enthält
+      keine Kollisions-Warnung mehr und endet mit „ready".
+- [ ] 3.4 Fehlendes `printers.conf` darf den Start nicht brechen.
+      Verifikation: `podman exec printserver sh -c 'cp /etc/cups/printers.conf /tmp/pc.bak && rm /etc/cups/printers.conf'`
+      danach `podman restart printserver`: der Container erreicht „ready";
+      anschließend Status wiederherstellen
+      (`podman exec … cp /tmp/pc.bak /etc/cups/printers.conf`) bzw. den
+      Testcontainer verwerfen.
+
+## Workflow follow-up
+
+- README-Abschnitt und Warnung gegen die echte Konstellation auf `podp`
+  prüfen: nach Deploy (Image neu bauen, Quadlet-Restart) muss die Warnung für
+  `laser`/`laserdrucker-im-buero` erscheinen, bis die Descriptions eindeutig
+  gemacht oder die redundante Queue entfernt ist — danach muss sie weg sein.
+- Nach Review und grünem Durchlauf die Änderung mit `/opsx-archive`
+  archivieren und das Ergebnis prüfen.