printserver/openspec/changes/warn-on-dnssd-name-collisions/tasks.md

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.