20040 - Drucker: CUPS im Heimnetz freigeben
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ansible/2-betrieb-hardware/20040-printer.md
Drucker: CUPS im Heimnetz freigeben
Zwei Drucker laufen über denselben cupsd auf dem Homeserver
(192.168.178.94), verwaltet von der Ansible-Rolle cups_print_server:
- Samsung Xpress M2026 — hängt per USB-Kabel direkt am Homeserver.
- Samsung ML-1630W — hängt per USB an einer FritzBox im
Mesh/Repeater-Modus (192.168.178.57) und wird von dieser als
Netzwerkdrucker über Raw-TCP Port 9100 geteilt (siehe
Abschnitt weiter unten).
cups_print_server installiert CUPS + Treiber-Pakete und gibt beide
Warteschlangen per IPP (Windows/Linux/macOS) und
AirPrint/IPP-Everywhere via Avahi/mDNS (iOS, Android, macOS) im
gesamten Heimnetz frei — inklusive Tailnet, dank der bereits bestehenden
Tailscale-Subnet-Route auf local_subnet (siehe
../c-netzwerk-dns/c0010-tailscale.md).
Architektur
┌────────────────────── homeserver (192.168.178.94) ──────────────────────┐
│ │
│ Samsung Xpress M2026 ──USB──▶ cupsd (Port 631) │
│ (meldet sich als USB-Device ├─ Warteschlange "Samsung_M2026" │
│ "M2020 Series") ├─ IPP-Sharing (cupsctl --share-printers)│
│ └─ Treiber: selbst gebauter QPDL-Filter│
│ (siehe "Warum QPDL" unten) │
│ │
│ avahi-daemon ──mDNS/DNS-SD──▶ bewirbt die Warteschlange als │
│ AirPrint/IPP-Everywhere-Ziel │
└─────────────────────────────┬────────────────────────────────────────────┘
│ LAN (UFW: local_subnet bereits erlaubt)
│ Tailnet (UFW: 100.64.0.0/10 bereits erlaubt)
┌───────────────┼───────────────┬────────────────────┐
▼ ▼ ▼ ▼
iPhone/iPad Android Windows/Linux Tailscale-Client
(AirPrint, (Mopria/ (IPP-URL manuell (unterwegs, über
Auto-Discovery) Auto-Discovery) hinzufügen) Subnet-Route)
Warum keine eigenen UFW-Regeln? Die common-Rolle erlaubt bereits
jeglichen Traffic aus local_subnet und dem Tailscale-Netz
(100.64.0.0/10) — Port 631 (IPP/CUPS-Web-UI) und mDNS (UDP 5353) sind
darüber schon abgedeckt, siehe
capulus-ansible/roles/common/tasks/main.yml.
Warum cupsctl statt cupsd.conf templaten? cupsctl ändert die
laufende Konfiguration live über die vom cups-Paket gepflegte Datei,
statt sie per Ansible-Template zu überschreiben — vermeidet Konflikte
mit künftigen CUPS-Paket-Updates und ist idempotent prüfbar (Rolle liest
den aktuellen Stand vorher per cupsctl ohne Argumente aus).
Beteiligte Rollen
| Rolle | Läuft auf | Zweck |
|---|---|---|
cups_print_server |
homeserver | Installiert CUPS + Treiber, aktiviert Sharing, legt die Warteschlange an |
Voraussetzungen
- Drucker per USB an den Homeserver anschließen und einschalten.
make installbzw.make cups-print-servereinmal ohne gesetzte
cups_print_server_ppdlaufen lassen — installiert Pakete + Sharing,
baut (fallscups_print_server_build_qpdl_driver: true) den
QPDL-Treiber, und zeigt am Ende per Debug-Ausgabe alle erkannten
Device-URIs (lpinfo -v) sowie zum Samsung/SPL passende PPDs
(lpinfo -m) an.- Den passenden PPD-Wert aus Schritt 2 in
capulus-ansible/group_vars/all.ymleintragen (Device-URI ist für den M2026
bereits eingetragen):cups_print_server_ppd: "samsung/m2020.ppd" # bestätigter Treffer für den M2026 make cups-print-servererneut laufen lassen — legt jetzt die
Warteschlange an, aktiviert sie und setzt sie als System-Default.
Deployment
make install # site.yml: komplettes Setup inkl. cups_print_server
make cups-print-server # nur die Rolle neu deployen (z.B. nach PPD-Änderung)
Treiber-Hinweise für den M2026
Der M2026 meldet sich per USB als generische "M2020 Series" — viele
günstige Samsung-SPL2-Modelle (M2020/M2021/M2022/M2026) teilen sich
denselben USB-Controller-Chip und damit dieselbe USB-Produktkennung.
Weder printer-driver-splix noch hplip unterstützen dieses Modell:
lpinfo -m | grep -i samsungimprinter-driver-splix-Katalog zeigt
nur ältere Modelle (ML-/CLP-/CLX-/SCX-Serien bis ca. 2013) — die
M2020-Serie fehlt komplett.sudo hp-setup -ierkennt das USB-Gerät nicht mal als unterstütztes
HPLIP-Modell ("No device selected/specified or that supports this
functionality").- Grund: Die M2020-Serie spricht ein neueres Protokoll namens QPDL
(nicht das ältere SPL2/SPLc, das splix abdeckt). Das ist der eigentliche
Grund, warum dieses sehr verbreitete Billig-Modell unter Linux
notorisch schwer einzurichten ist.
Lösung: selbst gebauter QPDL-Filter (opt-in, standardmäßig aktiviert
für dieses Deployment über cups_print_server_build_qpdl_driver: true
in group_vars/all.yml).
Es gibt einen QPDL-Treiber-Patch für splix, der nie ins offizielle
OpenPrinting/splix-Repo gemergt
wurde (letzter offizieller Release: 2.0.2, das ist auch, was Ubuntu
paketiert hat). Der Patch liegt auf
gitlab.com/ScumCoder/splix
(Branch patches) und wird von der Rolle auf einen festen Commit
gepinnt gebaut:
f97086c367d926dc4b6f84facabc9c3029729cba ("Fix m2020 being excluded
from built artifacts").
Warum dieser Fremdcode vertrauenswürdig genug ist
Bevor das in die Rolle eingebaut wurde, wurde der tatsächliche
Filter-Quellcode geprüft (nicht nur die PPD-Textdatei):
- Gleicher GPLv2-Lizenzkopf und Autoren-Handschrift ("Aurélien Croc
(AP²C)") wie im offiziellen splix — es ist strukturell dieselbe
Codebasis, nur um eine zusätzliche Protokoll-Variante (qpdl.cpp,
rastertoqpdl.cpp, analog zu den offiziellenspl2.cpp/splc.cpp)
erweitert. - Keine Netzwerk-Calls, kein
curl/wget, keine Obfuskation. Die
einzigenfork()/exec()-Aufrufe (pstoqpdl.cpp) sind normales
CUPS-Filter-Chaining (PostScript → Raster → QPDL-Pipeline), exakt wie
es jeder andere CUPS-Treiber auch macht. - Der gepinnte Commit stammt von einem erkennbaren Maintainer
([email protected]) und behebt exakt dieses eine bekannte Problem
("m2020 excluded from built artifacts") — kein Bulk-Import
unbekannten Codes. - CUPS-Filter laufen ohnehin nicht als root —
cupsdstartet sie
standardmäßig als unprivilegierterlp-User. - Der Commit ist bewusst gepinnt (nicht der Branch-
HEAD), damit ein
späterer Push auf den Branch nicht unbemerkt anderen Code einschleust.
Trotzdem bleibt es inoffizieller, nie überprüfter Community-Code —
wer das nicht auf dem eigenen Homeserver haben möchte, setzt
cups_print_server_build_qpdl_driver: false und nutzt stattdessen einen
der Fallbacks unten.
Nach dem Build zeigt lpinfo -m | grep -i -E 'samsung|spl' einen
neuen Treffer samsung/m2020.ppd Samsung M2020 Series (statische PPD,
kein drv://-Bundle-Eintrag) — dieser String kommt in
cups_print_server_ppd (bereits für den M2026 eingetragen:
samsung/m2020.ppd).
Falls der QPDL-Build nicht gewünscht ist (Fallback-Optionen):
- Raw-Queue:
cups_print_server_ppd: "raw"— druckt ohne
Treiber-Rasterung, funktioniert nur zuverlässig für reinen Text, keine
Formatierung/Grafik. - Original-Samsung-Treiber (ULD-Tarball): taucht nur noch auf
Drittanbieter-Treiberseiten auf (driverguide.com, printerdrivers.com)
— bewusst nicht empfohlen, solche Seiten sind für
Adware/fragwürdige Downloads bekannt. - Alternative: Warteschlange als raw teilen und von einem Windows-PC
mit echtem Samsung-Treiber aus drucken (Windows rendert dann lokal und
schickt fertige Rohdaten an die geteilte Rohqueue) — Workaround aus
den Community-Foren, nur falls alles andere scheitert.
Client-Einrichtung
iOS / Android / macOS (empfohlen, kein manuelles Setup):
Drucken-Dialog öffnen → "Samsung_M2026" erscheint automatisch per
AirPrint (iOS/macOS) bzw. Mopria/Default Print Service (Android) —
funktioniert nur, wenn das Gerät im selben LAN/WLAN oder per
Tailscale-Subnet-Route verbunden ist.
Windows:
Drucker hinzufügen → "Der gewünschte Drucker ist nicht aufgeführt" →
URL eintragen:
http://homeserver:631/printers/Samsung_M2026
(Fallback ohne Split-DNS: http://192.168.178.94:631/printers/Samsung_M2026)
Linux (CUPS-Client):
lpadmin -p Samsung_M2026 -E -v ipp://homeserver:631/printers/Samsung_M2026 -m everywhere
CUPS-Web-UI (Warteschlangen-Status, Jobs, manuelle Konfiguration):
http://homeserver:631
Testen
# Auf dem Homeserver: Status aller Warteschlangen
lpstat -t
# Testdruck von einer beliebigen Maschine mit installiertem CUPS-Client
lp -h homeserver:631 -d Samsung_M2026 /etc/hostname
Fehlerbehebung
QPDL-Build schlägt fehl (make / make install Fehler):
Build-Log direkt auf dem Homeserver reproduzieren:
cd /usr/local/src/splix-qpdl/splix
make DISABLE_JBIG=1
Meist fehlende Build-Abhängigkeiten (die Rolle installiert
build-essential, libcups2-dev, pkg-config — bei CUPS-Versionen, bei
denen libcupsimage nicht mehr in libcups2-dev enthalten ist, zusätzlich
libcupsimage2-dev installieren und erneut versuchen). Nach einem Fix
make cups-print-server erneut laufen lassen — der creates:-Guard in
der Rolle baut nur neu, wenn optimized/rastertoqpdl noch fehlt (ggf.
manuell rm -rf /usr/local/src/splix-qpdl für einen sauberen Rebuild).
Job wird angenommen, Drucker bleibt aber stumm (kein Papierauswurf):
sudo grep -i "error\|SpliX" /var/log/cups/error_log | tail -n 40
Bekannter Fall: "SpliX Cannot get paper size information. Operation aborted." — der QPDL-Filter (Printer::loadInformation() in
printer.cpp) verlangt eine explizit im Job aufgelöste
PageSize/Media-Option. Der PPD-eigene *DefaultPageSize allein reicht
unter dem modernen cups-filters-2.x-Kompatibilitäts-Layer
(ppdFilterEmitJCL, sichtbar im Log) nicht aus — ohne explizite Option
liefert der Filter leere/keine Seiten.
Behoben durch cups_print_server_media_size (Default A4), das die
Rolle als Queue-Default per lpadmin -o PageSize=... setzt. Wichtig:
bewusst PageSize (der literale PPD-Options-Name), nicht media — mit
lpadmin -o media=... reproduzierbar getestet, dass der Wert beim
Anlegen der Warteschlange NICHT in der PPD markiert wird (der
IPP-Alias media → PageSize wird nur bei der Job-Verarbeitung von
lp/lpr aufgelöst, nicht von lpadmin); lp -o media=A4 ... als
expliziter Job-Parameter funktioniert dagegen sofort. Betrifft nur
Warteschlangen, die vor diesem Fix angelegt wurden — make cups-print-server erneut laufen lassen, um den Queue-Default
nachzuziehen. Manueller Workaround pro Job, falls weiterhin nötig:
lp -o media=A4 ... (oder -o PageSize=A4).
Der Fallback griff nur, wenn der Job gar keine PageSize auflöste —
schickte ein Client stattdessen explizit eine andere/nicht passende
Größe, blieb der Fehler bestehen. Der Patch in printer.cpp erzwingt
deshalb paperType jetzt immer aus *DefaultPageSize der PPD,
unabhängig davon, was der Job anfragt. Dadurch druckt die
Samsung_M2026-Warteschlange jeden Job in der in
cups_print_server_media_size konfigurierten Größe — ein Client kann
für diese Warteschlange keine andere Papiergröße mehr erzwingen. Wer
gelegentlich ein anderes Format braucht, muss cups_print_server_media_size
ändern und make cups-print-server erneut laufen lassen.
Drucker taucht nicht in lpinfo -v auf:
USB-Kabel/Steckplatz prüfen, lsusb auf dem Homeserver (Paket
usbutils wird von der Rolle installiert) — der M2026 sollte als
Samsung-Gerät gelistet sein. Danach sudo systemctl restart cups und
lpinfo -v erneut prüfen.
Warteschlange angelegt, aber Druckjob bleibt hängen ("processing"):
sudo journalctl -u cups -n 100
lpstat -p Samsung_M2026 -l
Meist ein Treiber-/PPD-Mismatch — anderen PPD-Treffer aus
lpinfo -m | grep -i samsung probieren (siehe
Treiber-Hinweise).
Kein AirPrint-Eintrag auf iPhone/Android sichtbar:
sudo systemctl status avahi-daemon
avahi-browse -a | grep -i samsung
Prüfen, ob cups_print_server_share_printers auf true steht und die
Warteschlange per -o printer-is-shared=true freigegeben wurde
(lpstat -p Samsung_M2026 -l zeigt "Sharing: Yes/No" nicht direkt an —
stattdessen lpoptions -p Samsung_M2026 | grep shared bzw. erneut
make cups-print-server laufen lassen).
Drucken funktioniert im LAN, aber nicht über Tailscale unterwegs:
Subnet-Route (local_subnet) im
Tailscale-Admin-Panel
approved? Siehe ../c-netzwerk-dns/c0010-tailscale.md.
Verschlüsselter Druck (ipps://, z.B. via AirPrint/cups-browsed) schlägt
mit "Unable to encrypt connection: A TLS fatal alert has been received."
im error_log fehl, Job bleibt lokal mit Backend stopped with status 4 /
resources-are-not-ready hängen:
cupsd bestimmt seinen eigenen Namen für das selbstsignierte TLS-Zertifikat
per Reverse-Lookup der eigenen IP — und dieser Lookup ist auf dem Homeserver
mehrdeutig: avahi (mDNS, liefert z.B. homeserver.local), dnsmasq
(address=/homeserver/192.168.178.94 matcht auch logs-write.tech.homeserver
aus der journal_upload-Rolle) und die FritzBox (DHCP-PTR, liefert
homeserver.fritz.box) beantworten dieselbe Reverse-Anfrage unterschiedlich,
je nachdem was zuletzt neu gestartet wurde. Welchen Namen cupsd gerade
"glaubt" zu haben, sieht man an den Dateinamen in /etc/cups/ssl/*.crt — für
jeden neu gesehenen Namen legt cupsd automatisch ein neues, selbstsigniertes
Zertifikat an, das dann nicht zu homeserver passt und von TLS-prüfenden
Clients abgelehnt wird.
Statt diese Mehrdeutigkeit aufzulösen (bricht bei jedem Neustart von
cupsd/avahi/dnsmasq wieder), erzeugt die Rolle ein einziges
Zertifikat mit allen bekannten Selbst-Identifikationsnamen als Subject
Alternative Names (cups_print_server_tls_names) und legt es unter jedem
dieser Namen in /etc/cups/ssl/ ab — welchen Namen cupsd auch wählt, das
gefundene Zertifikat passt immer. Taucht nach einem hostname- oder
DNS/mDNS-Wechsel ein neuer, bisher unbekannter Name auf, cups_print_server_tls_names
um diesen Namen ergänzen und make cups-print-server erneut laufen lassen.
Zweiter Drucker: Samsung ML-1630W über FritzBox
┌──────────── FritzBox Mesh/Repeater (192.168.178.57) ────────────┐
│ Samsung ML-1630W ──USB──▶ teilt Drucker als Netzwerkdrucker │
│ über Raw-TCP Port 9100 │
└──────────────────────────────┬────────────────────────────────────┘
│ LAN (gleiches Hauptnetz, keine
│ Gast-WLAN-Isolation)
▼
┌────────────────────── homeserver (192.168.178.94) ──────────────────────┐
│ cupsd ──▶ Warteschlange "Samsung_ML-1630" │
│ Device-URI: socket://192.168.178.57:9100 │
│ Treiber: printer-driver-splix (SPL2, bereits als Paket │
│ installiert — kein QPDL-Build nötig, anders als beim M2026) │
└──────────────────────────────┬────────────────────────────────────────────┘
│ LAN + Tailnet (wie oben, IPP/AirPrint)
▼
iPhone/Android/Windows/Linux/Tailscale-Client
Warum keine eigene Rolle/ArgoCD-App? Der Homeserver betreibt bereits
einen cupsd für den M2026. Ein zweiter cupsd (z.B. als Container über
ArgoCD) würde auf Port 631 kollidieren und für denselben Zweck (Sharing
eines bereits fertigen Netzwerkdruckers) unnötig doppelte Infrastruktur
bedeuten — der ML-1630W braucht keinen USB-Passthrough, nur eine
zusätzliche Warteschlange mit socket://-Device-URI. Die Rolle
cups_print_server wurde daher um eine generische, vom M2026-Codepfad
unabhängige Liste cups_print_server_extra_queues erweitert (siehe
capulus-ansible/roles/cups_print_server/tasks/main.yml) —
QPDL-Build und PageSize-Patch bleiben ausschließlich dem M2026 vorbehalten
und werden vom ML-1630W-Setup nicht berührt.
Warum kein Vault? Die Ziel-IP der FritzBox ist kein Secret (analog zur
Device-URI des M2026, die ebenfalls im Klartext in group_vars/all.yml
steht) — Vault wird in diesem Repo ausschließlich für echte Secrets
(Passwörter, Tokens) genutzt.
Einrichtung
cups_print_server_extra_queues in capulus-ansible/group_vars/all.yml enthält
bereits den vollständigen Eintrag für Samsung_ML-1630 —
device_uri: "socket://192.168.178.57:9100" und ppd: "drv:///splix-samsung.drv/ml1630.ppd" (exakter Treffer im
printer-driver-splix-Katalog für genau dieses Modell, per lpinfo -m | grep -i -E 'splix|samsung|ml.?16|ml-?1630' auf dem Homeserver bestätigt).
make cups-print-server laufen lassen — legt die Warteschlange direkt an,
aktiviert sie und teilt sie im LAN/Tailnet.
Falls der Eintrag doch mal ohne ppd läuft (z.B. bei einem künftigen
dritten Drucker): die Rolle installiert dann nur Pakete + Sharing und
zeigt eine Warnung, ohne die Warteschlange anzulegen — passenden PPD-String
aus der Debug-Ausgabe "Extra-Queues: Splix-Katalog nach passenden PPDs
durchsuchen" (lpinfo -m, gefiltert auf (?i)splix|samsung|spl)
übernehmen und erneut laufen lassen.
Client-Einrichtung, Testen und Fehlerbehebung funktionieren analog zum
M2026-Abschnitt oben (Warteschlangenname Samsung_ML-1630 statt
Samsung_M2026).