Fail loudly when CUPS cannot bind port 631
ci/woodpecker/push/build Pipeline was successful

The queue was still advertised over mDNS while cupsd never bound TCP 631:
a rootless Podman container on the host network cannot bind the privileged
port. Apple clients then discovered a printer they could not reach and
reported a confusing _ipps connection failure.

* entrypoint.sh: verify that CUPS accepts connections on 631 after startup
  and exit with an actionable message otherwise
* entrypoint.sh: mark the script executable in the repository
* cupsd.conf: drop BrowseRemoteProtocols, which CUPS 2.4 no longer supports
  and which logs an error on every start
* README: add a troubleshooting section for the port-binding failure and the
  _ipps/TLS certificate requirement, and document the /etc/cups bind-mount
  caveat plus the CUPS 3 PPD deprecation
This commit is contained in:
juergen committed 2026-10-18 21:07:35 +02:00
1 parent 4c90ff1290
commit 7f26ca4f2f
3 files changed
+121 -4

No files matched your search

Regular → Executable
+21
View File
@@ -111,6 +111,27 @@ if lpstat -p "${PRINTER_NAME}" >/dev/null 2>&1; then
log "queue ${PRINTER_NAME} is shared and set as default"
fi
# --- Verify CUPS is reachable on the network --------------------------------
# cupsd also runs with nothing but its domain socket, e.g. when it cannot bind
# the privileged port 631 (rootless Podman with host networking). It then still
# advertises the queue over mDNS, so clients see a printer they cannot reach.
# Detect that and fail loudly instead of reporting a healthy server.
if ! curl -fsS --noproxy '*' --max-time 2 -o /dev/null http://127.0.0.1:631/ 2>/dev/null; then
log "ERROR: cupsd is not listening on TCP 631 - network clients (AirPrint/IPP) cannot reach this server"
if [ -f /var/log/cups/error_log ]; then
log " recent CUPS errors:"
tail -n 5 /var/log/cups/error_log | sed 's/^/ /'
fi
log " If the log shows 'Unable to open listen socket for address 0.0.0.0:631 - Permission denied',"
log " port 631 is privileged and this rootless container may not bind it on the host network."
log " Either allow unprivileged binding of 631 (host, needs root), persistently:"
log " echo 'net.ipv4.ip_unprivileged_port_start=631' > /etc/sysctl.d/90-unprivileged-ports.conf"
log " sysctl --system"
log " or run this container as a rootful (system) service."
log " See the Troubleshooting section of the README."
exit 1
fi
log "ready: CUPS on 631/tcp, mDNS on 5353/udp"
# Keep the container running by waiting on cupsd.