0 Fork 0

Files

T

ci/woodpecker/push/build Pipeline was successful

Details

Archive the advertise-valid-ipps-certificate change

Moves the completed change to
openspec/changes/archive/2026-10-18-advertise-valid-ipps-certificate/ and syncs
the printserver/cups capability into openspec/specs/: the image dependency
requirement now mentions the TLS tooling, and two requirements are added for the
name-valid _ipps certificate and for starting cleanly on stale runtime state.

2026-10-18 22:39:16 +02:00

3.3 KiB

Raw Blame History

Proposal

Why

macOS adds the shared queue as its bundled Generic PostScript Printer instead of driverlessly over AirPrint, so the print dialog offers no duplex, no colour and no tray selection — while iOS, which queries the printer live, does offer them. The cause is the secure _ipps service: CUPS serves a certificate issued for the container's host name, which is not the <host>.local name Avahi advertises and that clients validate. Anything that checks the name (macOS/iOS AirPrint, curl) rejects the secure add and macOS silently falls back to the generic driver; CUPS' own tools are lenient, so the server looks healthy.

Testing the fix surfaced a second, independent defect: restarting the container (podman restart, or a systemd Restart= of the quadlet) leaves stale D-Bus and Avahi PID files and sockets in /run. Both daemons then refuse to start and set -e stops the entrypoint, so the print server stays dead until the container is recreated.

What Changes

Generate and install the _ipps certificate in the entrypoint: self-signed, with SANs covering the container host name, <host name>.local, the name Avahi advertises, localhost, localhost.localdomain, host.containers.internal and 127.0.0.1, plus whatever CERT_EXTRA_NAMES lists; CERT_DAYS sets its validity.
Install the certificate where CUPS actually looks for it: as ServerCertificate/ServerKey (added to cupsd.conf when missing, also repairing a file rewritten by cupsctl) and as <name>.crt/.key for the host name and the Avahi FQDN, because CUPS 2.4 keeps serving its own <host name>.crt even when ServerCertificate is set.
Reuse an existing certificate when it already covers every required name, so a restart does not reissue it and clients that trusted it do not have to trust it again.
Add openssl explicitly to the image; it was only a transitive dependency of ca-certificates.
Remove stale D-Bus and Avahi runtime state (socket, PID file) before starting those daemons, and warn instead of exiting when Avahi cannot start.
Document the certificate, CERT_EXTRA_NAMES/CERT_DAYS, the client trust step and the macOS generic-driver fallback in the README. Documentation only, no spec behaviour.

Non-goals: shipping a publicly trusted certificate or a private CA, changing the _ipp (plain) service, and changing how jobs are converted or sent to the printer.

Capabilities

New Capabilities

Modified Capabilities

printserver/cups: the image dependency requirement now includes the TLS tooling, and the capability gains requirements for a secure AirPrint certificate that matches the advertised name and for starting cleanly when stale runtime state is left behind by a previous run.

Impact

entrypoint.sh: certificate generation/installation, D-Bus and Avahi startup.
Containerfile: explicit openssl.
README.md: CERT_EXTRA_NAMES/CERT_DAYS, a certificate section, and the macOS generic-driver fallback under Troubleshooting.
Clients: macOS/iOS can validate the secure service; plain IPP and existing client-side Windows driver setups are unaffected.
Existing deployments: an existing /etc/cups volume is repaired on the next start (the stale certificate is replaced); no volume reset is needed.

3.3 KiB Raw Blame History