60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
# Proposal
|
|
|
|
## Why
|
|
|
|
On the live deployment (`podp`), two queues ended up with the identical CUPS
|
|
Description, so both derived the same DNS-SD instance name
|
|
(`"<Description> @ <host>"`). Avahi can register only one of them and CUPS 2.4
|
|
never resolves the collision (upstream `scheduler/dnssd.c` still has
|
|
`/* TODO: Handle collisions with avahi_alternate_service_name */`), so one queue
|
|
showed `printer-is-shared=true` but was never advertised. macOS pins the exact
|
|
instance name into the queue's `dnssd://` device URI; when the pinned name stops
|
|
being announced, the Mac reports the printer **offline**. Because the collision
|
|
is deterministic, container restarts never helped and only remove/re-add on the
|
|
client fixed it — hours of debugging with no server-side signal pointing at the
|
|
cause.
|
|
|
|
## What Changes
|
|
|
|
- **`entrypoint.sh`**: after cupsd is up, derive the DNS-SD instance name of
|
|
every shared queue (`Description` if set, otherwise the queue name, plus
|
|
`@ <host>`) and log a prominent, non-fatal warning when two or more queues
|
|
derive the same instance name — naming the affected queues and the fix
|
|
(give each queue a unique Description, or delete the redundant queue).
|
|
- **`README.md`**: new Troubleshooting entry "macOS shows the printer offline
|
|
after some time" documenting the symptom, root cause (client-side instance
|
|
name pinning + duplicate-Description collision), verification commands
|
|
(`dns-sd -B`, `lpstat -l -p`, `ipptool`), and the fix including the
|
|
remove/re-add step on macOS.
|
|
- **Docs correction**: the `PRINTER_NAME` description in the `entrypoint.sh`
|
|
header and in the README currently claims it is the "advertised (DNS-SD)
|
|
name" — that is only true while no Description is set; the Description
|
|
overrides it. Correct both places, and clarify the matching requirement in
|
|
the `printserver/cups` spec (same claim).
|
|
|
|
Out of scope: changing how queues are configured (no automatic renaming or
|
|
de-duplication), and avoiding the `lpadmin` re-registration churn on restart.
|
|
|
|
## Capabilities
|
|
|
|
### New Capabilities
|
|
|
|
(none)
|
|
|
|
### Modified Capabilities
|
|
|
|
- `printserver/cups`: adds a requirement that the container detects DNS-SD
|
|
instance-name collisions between shared queues at startup and reports them in
|
|
the container log, so a queue that silently loses its advertisement is visible
|
|
to the operator instead of surfacing as an "offline" client hours later.
|
|
|
|
## Impact
|
|
|
|
- `entrypoint.sh` — one additional startup diagnostic block (log output only;
|
|
no change to queue creation, advertisement, or exit behaviour).
|
|
- `README.md` — one new Troubleshooting section; correction of the
|
|
`PRINTER_NAME` wording.
|
|
- No changes to `cupsd.conf`, the `Containerfile`, or runtime behaviour seen by
|
|
clients; the fix for an existing collision is still a manual operator action
|
|
(documented in the README).
|