juergen
548ae918ea
ci/woodpecker/push/build Pipeline was successful
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.
68 lines
3.3 KiB
Markdown
68 lines
3.3 KiB
Markdown
# 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
|
|
<!-- None: the certificate and restart behaviour extend the existing capability. -->
|
|
|
|
### 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.
|