Linux Printing

CUPS provides an Internet Printing Protocol (IPP) client and scheduler. A CUPS destination is a named printer queue or class; a physical or network printer is the device reached by that queue. Consequently, queue state, job state, and device reachability are separate diagnostic concerns.

Queues, Printers, and IPP #

Clients encode job documents and attributes in IPP requests. A local client commonly connects to the scheduler over a Unix-domain socket, while a remote client uses ipp:// or encrypted ipps://, conventionally on TCP port 631. The scheduler spools the job, selects a destination, converts data when required, and sends output through a backend or a driverless IPP connection.

Modern IPP Everywhere printers advertise formats and finishing capabilities directly. Legacy queues can instead use PPD-driven filter chains and backends. The queue remains the stable client-facing object in either case.

Submit Jobs #

lp supplies the System V interface, while lpr supplies the BSD-compatible interface. Both submit through CUPS:

lp report.pdf
lp -d office report.pdf
lpr -P office report.pdf
printf 'status report\n' | lp -d office

lp -d and lpr -P require an explicit destination. For lp, CUPS chooses the default from LPDEST, then PRINTER, then the per-user lpoptions default, and finally the server default.

Pass IPP job-template attributes with -o; query the destination first because printer-specific values differ:

lpoptions -p office -l
lp -d office -n 2 \
  -o media=A4 \
  -o sides=two-sided-long-edge \
  -o print-quality=4 report.pdf

lpoptions -p office -o name=value saves a default for subsequent jobs. lp -o name=value changes only the submitted job. CUPS also supports named printer instances such as office/duplex for saved option sets.

Inspect Queues and Printers #

Use separate status views to identify where work stopped:

lpstat -r                 # scheduler running
lpstat -p -d              # printer queues and default
lpstat -a                 # whether queues accept jobs
lpstat -v                 # queue device URIs
lpstat -o office          # incomplete jobs for one destination
lpstat -W completed -o office
lpq -P office             # BSD-compatible queue view

lpstat -p reports whether a queue is enabled for printing, while lpstat -a reports whether it accepts new jobs. A disabled queue can still retain jobs, and a nonaccepting queue can continue processing work already present.

Cancel and Control Jobs #

The submission response and lpstat -o provide identifiers such as office-42. Cancel one job with either interface:

cancel office-42
lprm -P office 42

cancel -a office cancels every job on the destination and therefore normally requires administrative authorization. lp -i office-42 -H resume releases a held job. Queue administration is separate: cupsdisable/cupsenable stop or start printing, while cupsreject/cupsaccept reject or accept submissions.

Diagnose Filters and Backends #

Start with lpstat -t, then inspect the affected job and queue. A stopped queue often records a filter exit, backend connection failure, authentication failure, or unsupported document format. CUPS writes scheduler and job messages to error_log; the configured ErrorLog can be a file, standard error, or the system journal. cupsctl --debug-logging enables additional diagnostics and should be disabled after reproducing the failure because logs can contain document names, user names, and device details.

For legacy pipelines, confirm that each filter exists and is executable, and test conversion with cupsfilter where available. For device failures, compare lpstat -v with the intended URI, resolve and connect to the endpoint, then inspect backend messages. The queue’s ErrorPolicy determines whether CUPS aborts, retries, or stops the printer after a backend or filter failure.

Permissions and Remote Servers #

Users can normally submit and cancel their own jobs. Server policy in cupsd.conf controls printer administration and cancellation of other users’ jobs; membership in a distribution-specific group is only one possible policy mechanism. -U NAME selects the asserted authentication username but does not bypass authentication.

Select another scheduler with -h server[:port] on CUPS commands or with the CUPS_SERVER environment variable:

lpstat -h print.example.com:631 -p -d
lp -h print.example.com:631 -E -d office report.pdf

-E forces transport encryption. The remote server must listen on a reachable interface, advertise or configure the destination, and authorize the requested IPP operation.

The upstream command-line printing guide, lpstat(1), and cupsd-logs(5) document these interfaces.