Printing and Scanning

LuxOS sets up USB printers and scanners without asking. A new printer on the network is offered in a notification ("Printer “X” found on the network" with Add) and gets a queue only after you click Add. Drivers are not needed where possible (IPP Everywhere / AirPrint / Mopria, and ipp-usb for USB). Classic USB printers get the best installed driver. Scanners work through SANE with eSCL (sane-airscan). All of this is in the package luxos-printing, which also provides the apps Printers & Scanners (luxos-printers) and Scanner (luxos-scan).

Components

Part Path Role
CUPS cups.socket print server, started on first use
Avahi + nss-mdns avahi-daemon.service finds network printers and scanners; .local names
ipp-usb started by udev makes IPP-over-USB printers look like network printers
watcher luxos-printing-watch.service → /usr/lib/luxos/printing/luxos-printing-watch listens to avahi-browse for new _ipp._tcp and _uscan._tcp services and runs the helper; every 30 s runs luxos-printing-helper autoresume, but only while CUPS is running or a queue is stopped
USB trigger /usr/lib/udev/rules.d/99-zz-luxos-printing.rules → luxos-printing-sync.service runs the helper when a USB printer or scanner is plugged in
helper (root) /usr/lib/luxos/printing/luxos-printing-helper creates the queues and installs drivers
admin entry /usr/lib/luxos/printing/luxos-printing-admin the same helper for removing a queue and cancelling another user's job
notifications /usr/lib/luxos/printing/luxos-printing-notify "Printer “X” is ready" etc. in the user session
mDNS in nsswitch /usr/lib/luxos/printing/luxos-nsswitch-mdns (+ libalpm hook) adds mdns_minimal to the hosts: line of /etc/nsswitch.conf
polkit org.luxos.printing.manage lets the active user run the helper through pkexec without a password (add, default, resume, discover)
polkit org.luxos.printing.admin removing a printer and cancelling another user's job ask for an administrator password (auth_admin_keep, remembered for a few minutes)

The package's install script enables cups.socket, avahi-daemon.service and luxos-printing-watch.service. The print-queue applet (system-config-printer-applet) is disabled on purpose.

How printers are added

luxos-printing-helper sync finds devices and handles each kind like this:

  • Network or IPP-USB printers with driverless support get a queue with lpadmin -m everywhere. IPP-USB printers (plugged in) are added right away. A network printer is only offered in a notification with Add (luxos-printing-helper add KEY), once per printer: anyone on the same network (also in a café or hotel) can announce a printer, so no queue and no default printer is created without your click. Queues are not shared. mDNS announcements are not authenticated, so everything from them is checked first: only _ipp/_ipps services in the local domain, DNS-SD names up to 63 bytes without control characters, the UUID only in UUID format (anything else is dropped, never put into the dnssd:// URI), the queue URI must have exactly the dnssd://NAME._ipp._tcp.local/?uuid=… shape. At most 5 network printers are offered per hour; others can be added with + in Printers & Scanners. The watcher runs sync at most every 10 seconds, also when the network floods it with announcements. Drivers are never installed because of a network announcement - only for USB printers. Network queues use printer-error-policy=retry-job, USB queues (classic and IPP-USB) retry-current-job (see Printer unplugged or turned off).
  • Classic USB printers get the best matching installed PPD driver. If none fits, the helper installs hplip (HP) or gutenprint (others) through lux (lux_alpm.py; it waits if the package database is busy). If that is not possible either, it uses a generic PostScript or PCL driver.
  • Printers that need a manufacturer driver (Samsung SPL/QPDL lasers such as the Xpress M2020/M2026, Brother, Canon UFR II, Epson inkjets) get it from the repository [luxos-drivers]: verified driver packages built by LuxOS from the AUR (see Verified drivers). The helper looks the printer model up in /usr/share/luxos/drivers-index.json (package luxos-drivers-index, installed by the helper when missing; luxos_printing.verified_driver), installs the driver as root through lux and creates the queue - no AUR build, no password. The Samsung PPD is per series ("M2020 Series" covers M2026).
  • Only when the driver is not in the configured repositories (old lux.conf without [luxos-drivers], or the repository database not downloaded yet) the printer gets no queue and the notification "needs a driver from the manufacturer" has an Install Driver button: it opens Terminal with lux install samsung-unified-driver-printer and then runs pkexec luxos-printing-helper sync. "Add" in Printers & Scanners offers the same.
  • Some HP models need HP's proprietary plugin. The notification then says: "Open Terminal and run: hp-plugin".
  • A network printer without driverless support gets no queue automatically. The notification says "needs to be set up… Open Printers & Scanners and choose Advanced…".
  • With no internet, a needed driver is installed later ("LuxOS will set it up automatically once you are connected to the internet").

The helper remembers the queues it created in /var/lib/luxos-printing/state.json. It never touches queues created by someone else, and it does not re-add a printer you removed.

Other helper commands (root, or through pkexec):

luxos-printing-helper discover        # JSON of all found printers
luxos-printing-helper add KEY         # add one from discover (also a removed one)
luxos-printing-helper remove QUEUE    # remove (and do not add again) - via pkexec only luxos-printing-admin
luxos-printing-helper default QUEUE   # default printer
luxos-printing-helper resume QUEUE    # re-enable a paused queue
luxos-printing-helper cancel ID       # cancel a print job (any user) - via pkexec only luxos-printing-admin
luxos-printing-helper autoresume      # resume queues paused because the printer was away (watcher)
luxos-printing-helper migrate         # one-time error policy update of older queues (package upgrade)

Printer unplugged or turned off

A document printed while the printer is off or unplugged waits and prints by itself as soon as the printer is back - no button to press.

  • Error policy. CUPS (and Arch) default to stop-printer: after any backend error the queue is stopped and never started again by CUPS itself. USB queues created by LuxOS use retry-current-job: when the cable is pulled or the printer is turned off during a job, the job starts again at once and the CUPS usb backend waits for the printer ("Waiting for printer to become available"). retry-job is not used for USB because CUPS discards the job after JobRetryLimit (5) × JobRetryInterval (300 s). Network queues keep retry-job: the ipp backend already waits for a printer that is off (up to 7 days), so a failure there is a real printer error and the limited retries cannot loop forever.
  • Migration. On upgrade (luxos-printing-helper migrate, otherwise at the first check) LuxOS sets retry-current-job once on its own USB queues and on USB queues created by another tool that still have the CUPS default stop-printer. A policy someone chose (for example abort-job) is kept. The state is policy_version in /var/lib/luxos-printing/state.json.
  • Paused queues are resumed automatically. A queue can still be stopped: by CUPS when the backend reports a fatal error ("Printer stopped due to backend errors", "unrecoverable USB error") or, on older installs, by system-config-printer's udev-configure-printer when the printer was unplugged ("Unplugged or turned off"; LuxOS masks its udev rule, which also removed the part that re-enabled the queue). luxos-printing-helper autoresume runs cupsenable (and cupsaccept) for such queues as soon as their printer is present, and releases jobs held because the printer was unavailable. It runs after every sync (a USB printer plugged in, a network or IPP-USB printer announced by Avahi), at start and every 30 s from the watcher.
  • USB: the serial number from the queue's usb://…?serial= URI is matched against /sys/bus/usb/devices (printer interface class 07); without a serial number lpinfo decides. Network and IPP-USB: the service (UUID or name) must be visible in Avahi.
  • Only queues stopped because the printer was missing are resumed. A queue paused by you ("Paused" or your own reason) stays paused - use Resume.
  • If CUPS stops the queue again right away (for example a broken driver), the next attempt waits 5, 10, 20 … minutes (at most 6 hours).
  • The watcher does not wake CUPS: when cups.service is not running there are no jobs, and it only reads /etc/cups/printers.conf until a stopped queue's printer is actually back.
  • Notifications. When a document waits for a printer that is not connected, a short notification says "Printer “X” is not connected – Connect the USB cable or turn the printer on. The document will print automatically." (for a network printer: turn it on and connect it to the same network). It is a status message (transient hint) and does not stay in the bell. Only when the document is still waiting after 5 minutes does one more notification stay in the bell ("A document is waiting for printer “X”"). When a paused queue is resumed with documents waiting: "Printer “X” is connected again – Waiting documents are printing now."

Printers & Scanners app

Run luxos-printers (or luxos-printers --add to open Add Printer, --scanner to select the first scanner). It is in Launchpad and Settings.

  • Printers list with state: Ready, Printing…, N documents waiting, Paused, "Not connected" for a network printer that is not reachable now (turned off or on another network; with "· N documents waiting" when documents wait), "Not connected – connect the USB cable or turn the printer on" (USB; checked every 2 s in sysfs) and, when documents wait or the queue was paused because the USB printer was away, "… Documents will print automatically." (the job then shows "Waiting for the printer" instead of "Printing…"). A network printer counts as reachable only when it is announced on the network (mDNS) and answers a short connection to its address (ipp://, ipps://, socket:// queues: the address and port from the URI); this is checked off the main thread every 12 s while the window is open and right after a network change - CUPS alone reports a driverless queue as ready until a job fails. Ink and toner levels, and the print queue with per-job Cancel and Cancel All.
  • Per-printer actions: Default printer, Print Test Page, Resume (only when the printer is paused for another reason than being unplugged or turned off - that resumes by itself), Remove Printer….
  • Add Printer… is a fallback for when the printer was not added automatically. It shows "Printers nearby" (USB and network) with an Add button. Advanced… opens system-config-printer for printers that need special setup (LPD, Windows sharing, manual drivers).
  • Scanners tab: Kind, Quality, Source, Preview, Scan. It saves as a PDF document or JPEG pictures and supports several pages.

Scanner app

Run luxos-scan (optionally --device <SANE device>). It is a simple scanner with one Scan button.

  • The scanner is picked automatically. A list appears only when there are several. eSCL is preferred over WSD when the same scanner shows up through several backends.
  • Scan as Document (300 dpi) or Photo (600 dpi). Colours: Colour or Black & white. Paper size. Source: Glass (flatbed), Document feeder, or Document feeder, both sides.
  • Pages can be reordered and removed, and "Scan Another Page" adds more. Save as a PDF document (multi-page), JPEG picture or PNG picture, or Print….
  • Files are named like Scan 2026-10-22 14.03 and saved to the Documents folder (xdg-user-dir DOCUMENTS, otherwise ~/Documents). Temporary pages are kept in ~/.cache/luxos-scan.
  • Scanning runs scanimage in a background thread. Cancel sends SIGTERM.
  • The laptop camera (SANE v4l backend) is never listed as a scanner.
  • With no scanner found the app keeps looking every few seconds, so a scanner switched on later appears by itself. The refresh button in the title bar searches again at any time.

Troubleshooting

  • Printer not added: make sure it is on and on the same network. Open Printers & Scanners › Add Printer… › Search Again. Check the services: systemctl status cups.socket avahi-daemon luxos-printing-watch, and the log: journalctl -u luxos-printing-watch -u luxos-printing-sync.
  • See what the system finds: avahi-browse -rt _ipp._tcp (network printers), lpstat -v (queues), pkexec /usr/lib/luxos/printing/luxos-printing-helper discover.
  • .local names do not resolve: the hosts: line of /etc/nsswitch.conf must contain mdns_minimal. Repair (root): /usr/lib/luxos/printing/luxos-nsswitch-mdns.
  • Printer "needs a driver": connect to the internet. The helper installs hplip or gutenprint itself. You can also install them by hand: lux install hplip.
  • HP printer needs a plugin: run hp-plugin in a terminal.
  • Printer not driverless (old network printer): use Advanced… (system-config-printer).
  • Paused printer: a printer paused because it was unplugged or off resumes by itself when it is connected again (log: journalctl -u luxos-printing-watch -u luxos-printing-sync, "queue resumed"). Otherwise the Resume button in the app, or luxos-printing-helper resume QUEUE.
  • "Not connected" although the cable is in: lsusb must list the printer; if it does not, try another cable or USB port, and turn the printer off and on.
  • Scanner not found: scanimage -L. The Scanner app says "Scanning support is not installed" when SANE is missing (install luxos-printing). It says "The scanner does not respond" when the device is off or busy.
  • The LuxOS firewall lets printer and scanner discovery through (mDNS, SSDP, WS-Discovery, SNMP, Canon BJNP and Epson replies from this network) and printing itself is an outgoing connection. Sharing your printers with other computers opens TCP 631 automatically once CUPS shares them. See firewall.md.