Difference between revisions of "CUPS"

From ArchWiki
Jump to navigation Jump to search
(→‎Other: Added a diagnostic and solution for a problem I encountered. CUPS would find but not print. something with either dnssd or CUPS detection of it is broken.)
(Undo revision 581220 by Guraltsev (talk) CUPS 2.3 includes wheel in SystemGroup by default, https://github.com/apple/cups/releases/tag/v2.3.0)
Tag: Undo
 
(476 intermediate revisions by 81 users not shown)
Line 1: Line 1:
 
[[Category:Printers]]
 
[[Category:Printers]]
 +
[[Category:Servers]]
 
[[cs:CUPS]]
 
[[cs:CUPS]]
 
[[de:CUPS]]
 
[[de:CUPS]]
Line 9: Line 10:
 
[[ru:CUPS]]
 
[[ru:CUPS]]
 
[[th:CUPS]]
 
[[th:CUPS]]
[[tr:CUPS]]
+
[[zh-hans:CUPS]]
[[zh-CN:CUPS]]
+
[[zh-hant:CUPS]]
[[zh-TW:CUPS]]
 
 
{{Related articles start}}
 
{{Related articles start}}
{{Related|CUPS printer sharing}}
+
{{Related|CUPS/Printer sharing}}
{{Related|CUPS printer-specific problems}}
+
{{Related|CUPS/Printer-specific problems}}
 +
{{Related|CUPS/Troubleshooting}}
 
{{Related|Samba}}
 
{{Related|Samba}}
 +
{{Related|LPRng}}
 
{{Related articles end}}
 
{{Related articles end}}
  
From [http://www.cups.org/index.php CUPS' site]:
+
[https://www.cups.org/ CUPS] is the standards-based, open source printing system developed by Apple Inc. for macOS® and other UNIX®-like operating systems.
:"''[[Wikipedia:CUPS|CUPS]] is the standards-based, open source printing system developed by Apple Inc. for OS® X and other UNIX®-like operating systems''".
 
  
Although there are other printing packages such as LPRNG, the Common Unix Printing System is the most popular choice because of its relative ease of use.
+
== Installation ==
  
== CUPS Linux printing workflow ==
+
[[Install]] the {{Pkg|cups}} package.
As of {{Pkg|cups}} version 1.5.3-3, Arch Linux makes use of the new full pdf-based printing workflow. For
 
further reading check [http://www.linuxfoundation.org/collaborate/workgroups/openprinting/pdfasstandardprintjobformat PDF standard printing job format] and an old [https://wiki.linuxfoundation.org/en/OpenPrinting/Database/CUPS-Filter-Chart CUPS filtering chart] for history and fun.
 
A good starting point for general Linux printing questions is [http://www.linuxfoundation.org/collaborate/workgroups/openprinting here].
 
  
There are two ways to setup a printer.
+
If you intend to "print" into a PDF document, also install the {{pkg|cups-pdf}} package. By default, pdf files are stored in {{ic|/var/spool/cups-pdf/''username''/}}. The location can be changed in {{ic|/etc/cups/cups-pdf.conf}}.
* If there's a CUPS server running in your network and sharing a printer you only need to install the client package.
 
* If the printer is connected directly to your system or you have access to an IPP network printer then setup a local CUPS server.
 
  
== Installing the client package ==
+
[[Enable]] and [[start]] {{ic|org.cups.cupsd.service}}.
  
The package {{Pkg|libcups}} is the only required package. [[pacman|Install]] it from the [[official repositories]].
+
=== Socket activation ===
  
Then add your CUPS server's IP address or hostname into {{ic|/etc/cups/client.conf}}, after {{ic|ServerName}}. That is all you need. Every application should quickly find the printer(s) shared by that CUPS server.
+
{{Pkg|cups}} provides a {{ic|org.cups.cupsd.socket}} unit. If {{ic|org.cups.cupsd.socket}} is [[enable]]d (and {{ic|org.cups.cupsd.service}} is [[disable]]d), systemd will not start CUPS immediately, it will just listen to the appropriate sockets. Then, whenever a program attempts to connect to one of these CUPS sockets, systemd will start {{ic|org.cups.cupsd.service}} and transparently hand over control of these ports to the CUPS process.
  
=== Installing CUPS in a 32-bit chroot environment ===
+
This way, CUPS is only started once a program wants to make use of the service.
  
If you have a 64-bit base installation with a [[Install_bundled_32-bit_system_in_Arch64|32-bit chroot environment]], explicit installation of CUPS is not necessary in the 32-bit environment. To access installed CUPS printers from the chroot environment, one needs to bind the {{ic|/var/run/cups}} directory to the same relative location in the chroot environment. Simply create the directory in the chroot (it probably does not exist), mount (with {{ic|-o bind}} passed to the command}}, and printers should be available from 32-bit chroot applications immediately.
+
== Connection Interfaces ==
  
{{bc|# mkdir /path/to/chroot/var/run/cups
+
Additional steps for printer detection are listed below for various connection interfaces.
# Example: # mkdir /opt/arch32/var/run/cups
 
  
# mount -o bind /var/run/cups /path/to/chroot/var/run/cups}}
+
{{Note|1=<nowiki></nowiki>
 +
* CUPS helper programs are run using the {{ic|cups}} user and group. This allows the helper programs to access printer devices and read config files in {{ic|/etc/cups/}}, which are owned by the {{ic|cups}} group.
 +
* Prior to {{Pkg|cups}} 2.2.6-2, the {{ic|lp}} group [https://git.archlinux.org/svntogit/packages.git/commit/trunk?h=packages/cups&id=a209bf21797a239c7ddb4614f0266ba1e5238622 was used instead]. After the upgrade, the files in {{ic|/etc/cups}} should be owned by the {{ic|cups}} group and {{ic|User 209}} and {{ic|Group 209}} set in {{ic|/etc/cups/cups-files.conf}}.
 +
}}
  
== Installing the server packages ==
+
=== USB ===
  
The following packages and some printer drivers are needed. [[pacman|Install]] them from the [[official repositories]].
+
To see if your USB printer is detected:
  
* {{Pkg|cups}} - the actual CUPS daemon
+
{{hc|$ lsusb|
* {{Pkg|ghostscript}} - (optional) PostScript interpreter
+
(...)
* {{Pkg|gsfonts}} - GhostScript standard Type1 fonts
+
Bus 001 Device 007: ID 03f0:1004 Hewlett-Packard DeskJet 970c/970cse
 +
}}
  
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install {{Pkg|samba}}.
+
=== Parallel port ===
  
=== Printer driver ===
+
To use a parallel port printer, the {{ic|lp}}, {{ic|parport}} and {{ic|parport_pc}} [[kernel modules]] are required.
  
Choosing the right driver depends on the printer. Package names may be misleading because printers of other makes can rely on them. Additional printer drivers are available from the [[AUR]].
+
{{hc|$ dmesg {{!}} grep -i parport|
 +
parport0: Printer, Hewlett-Packard HP LaserJet 2100 Series
 +
lp0: using parport0 (polling)
 +
}}
  
* {{AUR|cndrvcups-lb}} - Canon UFR2 driver with support for LBP, iR and MF series printers.
+
=== Network ===
* {{AUR|cnijfilter-mg4200}} - Printer drivers for Canon MG4200
 
* {{Pkg|cups-pdf}} - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it
 
* {{AUR|foo2zjs}} - Drivers for ZjStream protocol printers such as the HP Laserjet 1018. More info [http://foo2zjs.rkkda.com here]. It also includes drivers for HBPL protocol such as the Dell C1765 MFP. More info [http://foo2hbpl.rkkda.com here]
 
* {{Pkg|foomatic-db}}, {{Pkg|foomatic-db-engine}} and {{Pkg|foomatic-db-nonfree}} - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix.
 
* {{Pkg|gutenprint}} - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostScript, CUPS, Foomatic, and the [[GIMP]]
 
* {{Pkg|hplip}} - HP drivers for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models, as well as a number of Brother printers.
 
* {{AUR|hpoj}} - If you are using an HP Officejet, you should also install this package and follow the instructions to avoid problems as in [https://answers.launchpad.net/hplip/+question/133425 this thread].
 
* {{AUR|samsung-unified-driver}} - Unified Linux Driver for Samsung printers and scanners. Required for new printers such as the ML-2160.
 
* {{Pkg|splix}} - Samsung drivers for SPL (Samsung Printer Language) printers.
 
  
==== Download printer PPD ====
+
To discover or share printers using DNS-SD/mDNS, setup [[Avahi#Hostname_resolution|.local hostname resolution]] with [[Avahi]] and [[restart]] {{ic|org.cups.cupsd.service}}.
  
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.
+
{{Note|DNS-SD is only supported when using [[Avahi]]. CUPS does not support using [[systemd-resolved]] for DNS-SD, see [https://github.com/apple/cups/issues/5452 CUPS issue 5452].}}
  
Here is an explanation of what a PPD file is from the Linux Printing website:
+
To share printers with [[Samba]], e.g. if the system is to be a print server for Windows clients, the {{Pkg|samba}} package will be required.
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"
 
  
If the PPD for the printer is ''not'' already in CUPS, then:
+
== Printer Drivers ==
*check [[AUR]] to see if there are packages for the printer/manufacturer
 
*visit the [http://www.openprinting.org/printers OpenPrinting database] and select the manufacturer and model of the printer
 
*visit the manufacturer's site and search for GNU/Linux drivers
 
  
{{Note|PPD files go in {{ic|/usr/share/cups/model/}}}}
+
{{Expansion|CUPS is planning to drop PPD and driver support ([https://github.com/apple/cups/issues/5271 CUPS issue 5271]), instead relying entirely on IPP Everywhere. Explain what is/will be handled by {{Pkg|cups}} and what by {{Pkg|cups-filters}} and/or other software.}}
  
==== Another source for printer drivers ====
 
  
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.
+
The drivers for a printer may come from any of the sources shown below. See [[CUPS/Printer-specific problems]] for an incomplete list of drivers that others have managed to get working.
  
== Hardware support and configuration ==
+
To drive a printer, CUPS needs a PPD file and, for most printers, some [https://www.cups.org/doc/man-filter.html filters].
 +
For details on how CUPS uses PPDs and filters, see [https://www.cups.org/doc/postscript-driver.html].
  
=== USB printers ===
+
The [http://www.openprinting.org/printers OpenPrinting Printer List] provides driver recommendations for many printers. It also supplies PPD files for each printer, but most are available through [[#Foomatic|foomatic]] or the recommended driver package.
  
{{Tip|Most USB printers should work out of the box, you can skip this section and come back if you can not get your printer to work.}}
+
When a PPD file is provided to CUPS, the CUPS server will regenerate the PPD files and save them in {{ic|/etc/cups/ppd/}}.
  
USB printers can get accessed with two methods: The usblp kernel module and libusb. The former is the classic way. It is simple: data is sent to the printer by writing it to a device file as a simple serial data stream. Reading the same device file allows bi-di access, at least for things like reading out ink levels, status, or printer capability information (PJL). It works very well for simple printers, but for multi-function devices (printer/scanner) it is not suitable and manufacturers like HP supply their own backends. Source: [http://lists.linuxfoundation.org/pipermail/printing-architecture/2012/002412.html here].
+
=== CUPS ===
  
==== Blacklisting usblp ====
+
CUPS includes support for [[wikipedia:AirPrint|AirPrint]] and [http://www.pwg.org/ipp/everywhere.html IPP Everywhere] printers.
  
{{Warning|As of {{Pkg|cups}} version 1.6.0, it should no longer be needed to blacklist the {{ic|usblp}} kernel module.
+
=== OpenPrinting CUPS filters ===
  
If you find out this is the only way to fix a remaining issue please report this upstream to the CUPS bug tracker and maybe also get in contact with Till Kamppeter (Debian CUPS maintainer). See [http://cups.org/str.php?L4128 upstream bug] for more info.}}
+
The Linux Foundation's OpenPrinting workgroup provides [https://wiki.linuxfoundation.org/openprinting/cups-filters cups-filters]. Those are backends, filters, and other binaries that were once part of CUPS but are no longer maintained by Apple. They are available in the {{Pkg|cups-filters}} package that is a dependency of {{Pkg|cups}}.
  
If you have problems getting your USB printer to work, you can try [[Kernel modules#Blacklisting|blacklisting]] the {{ic|usblp}} [[kernel module]]:
+
Non-PDF printers require {{pkg|ghostscript}} to be installed. For PostScript printers {{Pkg|gsfonts}} may also be required.
  
{{hc|/etc/modprobe.d/blacklistusblp.conf|
+
=== Foomatic ===
blacklist usblp
 
}}
 
  
Custom kernel users may need to manually load the {{ic|usbcore}} [[kernel module]] before proceeding.
+
The Linux Foundation's OpenPrinting workgroup's [https://wiki.linuxfoundation.org/openprinting/database/foomatic foomatic] provides PPDs for many printer drivers, both free and nonfree. For more information about what foomatic does, see [http://www.openprinting.org/download/kpfeifle/LinuxKongress2002/Tutorial/IV.Foomatic-Developer/IV.tutorial-handout-foomatic-development.html Foomatic from the Developer's View].
  
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:
+
To use foomatic, install {{pkg|foomatic-db-engine}} and at least one of:
# tail /var/log/messages.log
 
or
 
# dmesg
 
  
If you're using {{ic|usblp}}, the output should indicate that the printer has been detected like so:
+
* {{pkg|foomatic-db}} - a collection of XML files used by foomatic-db-engine to generate PPD files.
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional
+
* {{pkg|foomatic-db-ppds}} - prebuilt PPD files.
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E
+
* {{Pkg|foomatic-db-nonfree}} - a collection of XML files from printer manufacturers under non-free licenses used by foomatic-db-engine to generate PPD files.
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920
+
* {{pkg|foomatic-db-nonfree-ppds}} - prebuilt PPD files under non-free licenses.
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver
 
  
If you blacklisted {{ic|usblp}}, you will see something like:
+
The foomatic PPDs may require additional filters, such as {{aur|min12xxw}}.
usb 3-2: new full speed USB device using uhci_hcd and address 3
 
usb 3-2: configuration #1 chosen from 1 choice
 
  
=== Parallel port printers ===
+
=== Gutenprint ===
  
To use a parallel port printer, you will need to load the {{ic|lp}}, {{ic|parport}} and {{ic|parport_pc}} [[kernel modules]].
+
The [http://gimp-print.sourceforge.net/ Gutenprint project] provides drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with CUPS and [[GIMP]].
  
Check the setup by running:
+
Install {{Pkg|gutenprint}} and {{Pkg|foomatic-db-gutenprint-ppds}}.
# tail /var/log/messages.log
 
It should display something like this:
 
lp0: using parport0 (polling).
 
  
If you are using a USB to parallel port adapter, CUPS will not be able to detect the printer. As a workaround, add the printer using a different connection type and then change DeviceID in {{ic|/etc/cups/printers.conf}}:
+
{{Note|When the Gutenprint packages get updated, the printers using Gutenprint drivers will stop working until you run {{ic|cups-genppdupdate}} as root and restart CUPS. ''cups-genppdupdate'' will update the PPD files of the configured printers, see {{man|8|cups-genppdupdate}} for more details.}}
DeviceID = parallel:/dev/usb/lp0
 
  
=== HP Printer ===
+
=== Manufacturer-specific drivers ===
HP printers can also be installed via HP's Linux setup tool. Install it by installing {{Pkg|hplip}} from the [[official repositories]].
 
  
To run with qt frontend:
+
Many printer manufacturers supply their own Linux drivers. These are often available in the official Arch repositories or in the [[AUR]].
# hp-setup -u
 
  
To run with command line:
+
Some of those drivers are described in more detail in [[CUPS/Printer-specific problems]].
# hp-setup -i
 
  
To run systray spool manager:
+
== Printer URI ==
$ hp-systray
 
  
PPD files are in {{ic|/usr/share/ppd/HP/}}.
+
Listed below are additional steps to manually generate the URI if required. Some printers or drivers may need a special URI as described in [[CUPS/Printer-specific problems]].
  
{{Note| If you get errors complaining about missing gobject/dbus dependencies, install {{Pkg|python2-gobject2}} and {{Pkg|python2-dbus}}. For details see this [https://bugs.archlinux.org/task/26666 bug report].}}
+
=== USB ===
  
For printers that require the proprietary HP plugin (like the Laserjet Pro P1102w or 1020), install the {{AUR|hplip-plugin}} package from [[AUR]].
+
CUPS should be able to automatically generate a URI for USB printers, for example {{ic|1=usb://HP/DESKJET%20940C?serial=CN16E6C364BH}}.
  
{{Warning| Due to a bug in hplip-setup, you might get error in sys tray or CUPS logs {{ic|Print job failed - required plug-in not found. Please run hp-plugin}} even after you install the aforementioned {{AUR|hplip-plugin}} package from [[AUR]]. To fix, simply modify the printer in CUPS web interface and select the driver manually (preferably the en,en version). After that restart CUPS service.}}
+
If it does not, see [[CUPS/Troubleshooting#USB printers]] for troubleshooting steps.
  
{{Note|
+
=== Parallel port ===
{{Pkg|hplip}} depends on {{Pkg|foomatic-db-engine}} which prevents the drivers list from appearing when a printer is added to CUPS via the web user interface (following error : "Unable to get list of printer drivers"). The workaround consists of installing {{Pkg|hplip}} first, retrieving the corresponding PPD file from {{ic|/usr/share/ppd/HP/}}, then, removing  {{Pkg|hplip}} entirely and the unnecessary dependencies. Finally, install the printer manually using the CUPS web ui, select the PPD file you retrieved then re-install {{Pkg|hplip}}.  After a reboot, you should have a fully working printer.}}
 
  
== Configuring ==
+
The URI should be of the form {{ic|parallel:''device''}}. For instance, if the printer is connected on {{ic|/dev/lp0}}, use {{ic|parallel:/dev/lp0}}.
 +
If you are using a USB to parallel port adapter, use {{ic|parallel:/dev/usb/lp0}} as the printer URI.
  
Now that CUPS is installed, there are a variety of options on how to set up printing solutions. As always, the tried and true command line method is at your disposal. CUPS also embeds a full-featured web interface. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. Depending on your needs, you may choose one method or the other.
+
=== Network ===
  
If you are planning on connecting to a network printer, rather than one that is directly connected to the computer, you might want to read the [[CUPS printer sharing]] page first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.
+
If you have set up [[Avahi]] as in [[#Network]], CUPS should detect the printer URI. You can also use {{ic|avahi-discover}} to find the name of your printer and its address (for instance, {{ic|BRN30055C6B4C7A.local/10.10.0.155:631}}).
  
=== CUPS daemon ===
+
The URI can also be generated manually, without using [[Avahi]].
 +
A list of the available URI schemes for networked printers is available in the [https://www.cups.org/doc/network.html#PROTOCOLS CUPS documentation]. As exact details of the URIs differ between printers, check either the manual of the printer or [[CUPS/Printer-specific problems]].
  
{{Note|For {{Pkg|cups}} 2.0.0, the service name has been changed to {{ic|org.cups.cupsd.service}} instead of {{ic|cups.service}}. This package is available in extra from October 31, 2014. When upgrading to version 2.0.0, it is necessary to manually disable the old service, otherwise broken symbolic links will be left in {{ic|/etc/systemd/system/}} subdirectories and systemd will warn about non-existent services.}}
+
The URI for printers on [[SMB]] shares is described in the {{man|8|smbspool}} man page.
  
With CUPS installed, you can now start {{ic|org.cups.cupsd.service}} [[systemd#Using units|using systemd]]. Enable it as required.
+
{{Note|Any special characters in the printer URIs need to be appropriately quoted, or, if your Windows printer name or user passwords have spaces, CUPS will throw a {{ic|lpadmin: Bad device-uri}} error.
 +
For example, {{ic|smb://BEN-DESKTOP/HP Color LaserJet CP1510 series PCL6}} becomes {{ic|smb://BEN-DESKTOP/HP%20Color%20LaserJet%20CP1510%20series%20PCL6}}.
 +
 
 +
This result string can be obtained by running the following command:
  
Optionally, CUPS can use Avahi browsing to discover unknown shared printers in your network. This can be useful in large setups where the server is unknown. To use this feature, start the {{ic|cups-browsed.service}} systemd unit.
+
$ python -c 'from urllib.parse import quote; print("smb://" + quote("BEN-DESKTOP/HP Color LaserJet CP1510 series PCL6"))'
  
=== Web interface and tool-kit ===
+
}}
  
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{ic|/etc/hostname}}).
+
Remote CUPS print servers can be accessed through a URI of the form {{ic|ipp://''hostname'':631/printers/''queue_name''}}. See [[CUPS/Printer sharing#Printer sharing]] for details on setting up the remote print server.
  
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''.  When prompted for a username and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label (e.g., next to ''USB Printer #1'' for USB printers). Finally, choose the appropriate drivers and the configuration is complete.
+
See [[CUPS/Troubleshooting#Networking issues]] for additional issues and solutions.
  
Now test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.
+
{{Warning|1=Avoid configuring both the server and the client with a printer filter - either the print queue on the client or the server should be 'raw'. This avoids sending a print job through the filters for a printer twice, which can cause problems (for instance, [https://bbs.archlinux.org/viewtopic.php?pid=1589908#p1589908]). See [[#Usage]] for an example of setting a print queue to 'raw'.}}
  
{{Tip|See: [[#Alternative CUPS interfaces]] for other front-ends.}}
+
== Usage ==
{{Note|
 
* When setting up a USB printer, you should see your printer listed on ''Add Printer'' page. If you can only see a "SCSI printer" option, it probably means that CUPS has failed to recognize your printer.
 
* To enable wireless scanning on certain HP multi-function devices using the {{pkg|hplip}} package, you may need to add the printer as a Network Printer using the HTTP protocol. To determine the proper URI to use, run the {{ic|hp-makeuri}} command.}}
 
  
==== CUPS administration ====
+
CUPS can be fully controlled using the lp* and cups* CLI tools.
 +
Alternatively, the [[#Web interface]] or one of several [[#GUI applications]] can be used.
  
A username and password will be required when administering the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default username is the one assigned in the ''sys'' group, or root. Other admin groups (e.g. ''printadmin'') may be added to the {{ic|SystemGroup}} line in {{ic|/etc/cups/cups-files.conf}} (you might have to add this line).  
+
* The ''queue'' name is a short but descriptive name used on the system to identify the queue. This name should not contain spaces or any special characters. For instance, a print queue corresponding to a HP LaserJet 5P could be named "hpljet5p". More than one queue can be associated with each physical printer.
 +
* The ''location'' is a description of the printer's physical location (for instance "bedroom", or "kitchen"). This is to aid in maintaining several printers.
 +
* The ''description'' is a full description of the print queue. A common use is a full printer name (like "HP LaserJet 5P").
  
Create the group[s] ({{ic|man groupadd}})
+
=== CLI tools ===
  
# groupadd printadmin
+
See [http://localhost:631/help/options.html CUPS local documentation] for more tips on the command-line tools.
# groupadd lp
 
  
and add the users to the group(s) ({{ic|man gpasswd}}).
+
{{Note|Command-line switches cannot be grouped}}
  
# gpasswd -a username printadmin      # for printer administration
+
{{Style|Nonstandard use of definition lists, comments in command line.}}
# gpasswd -a username lp              # for printing priviledges
 
  
  # Administrator user group, used to match @SYSTEM in cupsd.conf policy rules...
+
;List the devices
  SystemGroup sys root '''printadmin'''
+
# lpinfo -v
 +
  $ /usr/lib/cups/backend/snmp ''ip_address'' # Use SNMP to find a URI
  
Restart {{ic|org.cups.cupsd.service}} using systemd. The user must re-login for these changes to take affect.
+
;List the models
 +
$ lpinfo -m
  
Refer to the full cups [http://www.cups.org/documentation.php documentation] for further details.
+
;Add a new queue
 +
# lpadmin -p ''queue_name'' -E -v ''uri'' -m ''model''
  
==== Remote access to web interface ====
+
The ''queue_name'' is up to you.
 +
Examples:
 +
# lpadmin -p HP_DESKJET_940C -E -v "usb://HP/DESKJET%20940C?serial=CN16E6C364BH" -m drv:///HP/hp-deskjet_940c.ppd.gz
 +
# lpadmin -p AirPrint -E -v "ipp://10.0.1.25/ipp/print" -m everywhere    # Driverless queue (Apple AirPrint or IPP Everywhere)
 +
# lpadmin -p SHARED_PRINTER -m raw    # Raw queue; no PPD or filter
 +
# lpadmin -p Test_Printer -E -v "ipp://10.0.1.3/ipp/print" -m pxlmono.ppd    # Specifying a PPD instead of a model
  
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{ic|/etc/cups/cupsd.conf}} file. Replace the line:
+
{{Note|When specifying the PPD, use just the file name and not the full path (for instance, {{ic|pxlmono.ppd}} instead of {{ic|/usr/share/ppd/cupsfilters/pxlmono.ppd}}). Alternatively, the full path can be used with the {{ic|-P}} command line switch.}}
Listen localhost:631
 
with
 
Port 631
 
so that CUPS listens to incoming requests.
 
  
Three levels of access can be granted:
+
;Set the default printer
<Location />          #access to the server
+
  $ lpoptions -d ''queue_name''
<Location /admin> #access to the admin pages
 
<Location /admin/conf> #access to configuration files
 
 
 
To give remote hosts access to one of these levels, add an {{ic|Allow}} statement to that level's section. An {{ic|Allow}} statement can take one or more of the forms listed below:
 
Allow from all
 
Allow from host.domain.com
 
Allow from *.domain.com
 
Allow from ip-address
 
Allow from ip-address/netmask
 
Allow from @LOCAL
 
 
 
Deny statements can also be used. For example, if wanting to give full access to all hosts on your local network interfaces, file {{ic|/etc/cups/cupsd.conf}} would include this:
 
# Restrict access to the server...
 
# By default only localhost connections are possible
 
<Location />
 
    Order allow,deny
 
    '''Allow from @LOCAL'''
 
</Location>
 
 
# Restrict access to the admin pages...
 
<Location /admin>
 
    Order allow,deny
 
    '''Allow from @LOCAL'''
 
</Location>
 
 
  # Restrict access to configuration files...
 
<Location /admin/conf>
 
    AuthType Basic
 
    Require user @SYSTEM
 
    Order allow,deny
 
    '''Allow From @LOCAL'''
 
</Location>
 
 
 
You might also need to add:
 
 
 
DefaultEncryption Never
 
 
 
This should avoid the error: 426 - Upgrade Required when using the CUPS web interface from a remote machine.
 
 
 
=== Command-line configuration ===
 
 
 
CUPS can be fully controlled from command-line with nice tools, ''i.e.'' the lp* and the cups* command families.
 
 
 
On Arch Linux, most commands support auto-completion with common shells.
 
Also note that command-line switches cannot be grouped.
 
 
 
;List the devices
 
# lpinfo -v
 
 
 
;List the drivers
 
# lpinfo -m
 
  
;Add a new printer
+
;Change the options
  # lpadmin -p ''printer'' -E -v ''device'' -P ''ppd''
+
  $ lpoptions -p ''queue_name'' -l # List the options
 +
$ lpoptions -p ''queue_name'' -o ''option''=''value'' # Set an option
  
The ''printer'' is up to you. The device can be retrieved from the 'lpinfo -v' command.
 
 
Example:
 
Example:
  # lpadmin -p HP_DESKJET_940C -E -v "usb://HP/DESKJET%20940C?serial=CN16E6C364BH"  -P /usr/share/ppd/HP/hp-deskjet_940c.ppd.gz
+
  $ lpoptions -p HP_DESKJET_940C -o PageSize=A4
 
 
In the following, the ''printer'' references the name you have used here to set up the printer.
 
 
 
;Set the default printer
 
$ lpoptions -d ''printer''
 
  
 
;Check the status
 
;Check the status
 
  $ lpstat -s
 
  $ lpstat -s
  $ lpstat -p ''printer''
+
  $ lpstat -p ''queue_name''
  
 
;Deactivate a printer
 
;Deactivate a printer
  # cupsdisable ''printer''
+
  # cupsdisable ''queue_name''
  
 
;Activate a printer
 
;Activate a printer
  # cupsenable ''printer''
+
  # cupsenable ''queue_name''
 +
 
 +
;Set the printer to accept jobs
 +
# cupsaccept ''queue_name''
  
 
;Remove a printer
 
;Remove a printer
 
First set it to reject all incoming entries:
 
First set it to reject all incoming entries:
  # cupsreject ''printer''
+
  # cupsreject ''queue_name''
 
Then disable it.
 
Then disable it.
  # cupsdisable ''printer''
+
  # cupsdisable ''queue_name''
 
Finally remove it.
 
Finally remove it.
  # lpadmin -x ''printer''
+
  # lpadmin -x ''queue_name''
  
 
;Print a file
 
;Print a file
 
  $ lpr ''file''
 
  $ lpr ''file''
  $ lpr -# 17 ''file''             # print the file 17 times
+
  $ lpr -# 17 ''file''           # print the file 17 times
  $ echo "Hello, world!" | lpr -p # print the result of a command. The -p switch adds a header.
+
  $ echo 'Hello, world!' | lpr -p # print the result of a command. The -p switch adds a header.
  
;Check the printing queue
+
;Check the queue
 
  $ lpq
 
  $ lpq
  $ lpq -a # on all printers
+
  $ lpq -a # on all queues
  
;Clear the printing queue
+
;Clear the queue
 
  # lprm  # remove last entry only
 
  # lprm  # remove last entry only
 
  # lprm - # remove all entries
 
  # lprm - # remove all entries
  
=== Alternative CUPS interfaces ===
+
=== Web interface ===
 
 
==== GNOME ====
 
 
 
You can configure and manage printers by [[pacman|installing]] {{Pkg|system-config-printer}}. This program does pull in some gnome dependencies.
 
 
 
If your user does not have sufficient priviliges to administer the cups scheduler, system-config-printer will request the root password when it starts. You can avoid this by performing the following instructions.
 
 
 
1. Create a group for administering the cups scheduler:
 
 
 
# groupadd lpadmin
 
 
 
2. Add yourself to the newly created group:
 
 
 
# usermod -aG lpadmin ''username''
 
 
 
3. Tell cups to respect the newly created group:
 
 
 
{{hc|/etc/cups/cups-files.conf|
 
...
 
SystemGroup sys root '''lpadmin'''
 
...}}
 
 
 
4. Restart cups {{ic|org.cups.cupsd.service}} using systemd.
 
 
 
5. Log out and log in again or restart your computer.
 
 
 
==== KDE ====
 
 
 
[[KDE]] users can modify their printers from the Control Center. The {{Pkg|kdeutils-print-manager}} package may need be installed if the Printers interface isn't found in the Hardware group. KDE users should refer to the desktop environments' documentation for more information on how to use the interface.
 
 
 
==== Other ====
 
 
 
There is also {{AUR|gtklp}} in the [[AUR]].
 
 
 
== PDF virtual printer ==
 
{{Note| With GNOME, it is now possible to directly print into a PDF or Postscript file, therefore CUPS-PDF is no longer required on such system. }}
 
 
 
{{Pkg|cups-pdf}} is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. This package is not necessary, but it can be quite useful.
 
 
 
After installing the package, set it up as if it were for any other printer by using the web interface. Access the cups print manager: http://localhost:631 and select:
 
Administration -> Add Printer
 
Select CUPS-PDF (Virtual PDF), choose for the make and driver:
 
Make: Generic
 
Driver: Generic CUPS-PDF Printer
 
 
 
Find generated PDF documents in a sub-directory located at {{ic|/var/spool/cups-pdf}}. Normally, the subdirectory is named after the user who performed the job. A little tweak helps you to find your printed PDF documents more easily. Edit {{ic|/etc/cups/cups-pdf.conf}} by changing the line
 
#Out /var/spool/cups-pdf/${USER}
 
 
 
to
 
 
 
Out ${HOME}
 
 
 
=== Print to PostScript ===
 
 
 
The CUPS-PDF (Virtual PDF Printer) actually creates a PostScript file and then creates the PDF using the ps2pdf utility. To print to PostScript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...
 
 
 
== Troubleshooting ==
 
 
 
The best way to get printing working is to set 'LogLevel' in {{ic|/etc/cups/cupsd.conf}} to:
 
LogLevel debug
 
 
 
And then viewing the output from {{ic|/var/log/cups/error_log}} like this:
 
# tail -n 100 -f /var/log/cups/error_log
 
 
 
The characters at the left of the output stand for:
 
*D=Debug
 
*E=Error
 
*I=Information
 
*And so on
 
 
 
These files may also prove useful:
 
*{{ic|/var/log/cups/page_log}} -  Echoes a new entry each time a print is successful
 
*{{ic|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity
 
 
 
Of course, it is important to know how CUPS works if wanting to solve related issues:
 
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).
 
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.
 
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.
 
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.
 
 
 
Print a document and watch {{ic|error_log}} to get a more detailed and correct image of the printing process.
 
 
 
=== Problems resulting from upgrades ===
 
 
 
''Issues that appeared after CUPS and related program packages underwent a version increment''
 
 
 
==== CUPS stops working ====
 
 
 
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" may result from trying to manage CUPS via localhost:631, for example.
 
 
 
To use the new configuration, copy {{ic|/etc/cups/cupsd.conf.default}} to {{ic|/etc/cups/cupsd.conf}} (backup the old configuration if needed) and restart CUPS to employ the new settings.
 
 
 
==== All jobs are "stopped" ====
 
 
 
If all jobs sent to the printer become "stopped", delete the printer and add it again.
 
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.
 
 
 
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.
 
  
==== All jobs are "The printer is not responding" ====
+
The CUPS server can be fully administered through the web interface, available on http://localhost:631/.
  
On networked printers, you should check that the name that CUPS uses as its connection URI resolves to the printer's IP via DNS, e.g.
+
{{Note|If an HTTPS connection to CUPS is used, it ''may'' take a very long time before the interface appears the first time it is accessed. This is because the first request triggers the generation of SSL certificates which can be a time-consuming job.}}
If your printer's connection looks like this:
 
lpd://BRN_020554/BINARY_P1
 
  
then the hostname 'BRN_020554' needs to resolve to the printer's IP from the server running CUPS
+
To perform administrative tasks from the web interface authentication is required. Authenticate either as {{ic|root}} or make sure your user is member of a group with printer administration privileges, see [[#Configuration]].
  
==== The PPD version is not compatible with gutenprint ====
+
;Add a queue
 +
Go to the '''Administration''' page.
  
Run:
+
;Modify existing queues
# /usr/bin/cups-genppdupdate
+
Go to the '''Printers''' page, and select a queue to modify.
  
And restart CUPS (as pointed out in gutenprint's post-install message)
+
;Test a queue
 +
Go to the '''Printers''' page, and select a queue.
  
=== Other ===
+
=== GUI applications ===
  
==== Printer "Paused" or "Stopped" with Status "Rendering completed" ====
+
If your user does not have sufficient privileges to administer CUPS, the applications will request the root password when they start. To give users administrative privileges without needing root access, see [[#Configuration]].
  
When low on ink, some printers will get stuck in "Rendering completed" status and, if it is a network printer, the printer may even become unreachable from CUPS' perspective despite being properly connected to the network. Replacing the low/depleted ink cartridge(s) in this setting will return the printer to "Ready" status and, if it is a network printer, will make the printer available to CUPS again.
+
* {{App|GtkLP|GTK interface for CUPS.|https://gtklp.sirtobi.com/index.shtml|{{AUR|gtklp}}}}
 +
* {{App|print-manager|Tool for managing print jobs and printers ([[KDE]]).|https://cgit.kde.org/print-manager.git|{{Pkg|print-manager}}}}
 +
* {{App|system-config-printer|GTK printer configuration tool and status applet.|http://cyberelk.net/tim/software/system-config-printer/|{{Pkg|system-config-printer}}}}
  
{{Note|If you use third-party ink cartridges, the ink levels reported by the printer may be inaccurate. If you use third-party ink and your printer used to work fine but is now getting stuck on "Rendering completed" status, replace the ink cartridges regardless of the reported ink levels before trying other fixes.}}
+
== Configuration ==
  
 +
The CUPS server configuration is located in {{ic|/etc/cups/cupsd.conf}} and {{ic|/etc/cups/cups-files.conf}} (see {{man|5|cupsd.conf}} and {{man|5|cups-files.conf}}). After editing either file, [[restart]] {{ic|org.cups.cupsd.service}} to apply any changes. The default configuration is sufficient for most users.
  
If low ink is not the issue, check the "Group ID" of files in {{ic|/etc/cups}}, {{ic|/var/log/cups}}, and, if you have "root" permission, {{ic|/var/spool/cups}}. The files should have GID {{ic|lp}}. If some files have GID {{ic|nobody}}, then check the named groups in the "Group" and "SystemGroup" directives in the file {{ic|/etc/cups/cups-files.conf}}. Typically there will be {{ic|Group lp}} and {{ic|SystemGroup lpadmin sys root}}. Make sure that the group in "Group" is NOT also in "SystemGroup". In particular, make sure that the name {{ic|lp}} is NOT listed in the "SystemGroup" directive, when it is used in the "Group" directive.  This is counter to recommendations made in the CUPS and KDE wiki pages in the past. If you had added {{ic|lp}} to the "SystemGroup" directive, as had been suggested, remove {{ic|lp}} from the "SystemGroup", or run the following command and change {{ic|lp}} to {{ic|lpadmin}} in the "SystemGroup" directive.
+
[[User group]]s with printer administration privileges are defined in {{ic|SystemGroup}} in the {{ic|/etc/cups/cups-files.conf}}. The {{ic|sys}} and {{ic|root}} and {{ic|wheel}} [[groups]] are used by default.
# groupadd -g107 lpadmin
 
  
===== Explanation of the GID issue =====
+
{{pkg|cups}} is built with {{pkg|libpaper}} support and libpaper defaults to the '''Letter''' paper size. To avoid having to change the paper size for each print queue you add, edit {{ic|/etc/papersize}} and set your system default paper size. See {{man|5|papersize}}.
For security reasons, {{ic|cupsd}} does not allow external CUPS helper programs, which are run with the GID selected with the "Group" directive, to run with any GID of the administrative groups, which are those GIDs listed in the "SystemGroup" directive. If the named group in the Group directive is also in the SystemGroup directive, then {{ic|cupsd}} will instead run the helper programs with GID {{ic|nobody}}, without warning. Note that the printer devices in {{ic|/dev/}}, for instance {{ic|/dev/parport0}}, are created with user {{ic|root}} and group {{ic|lp}}. When {{ic|cupsd}} then tries to print, it "pauses" or "stops" because it does not have permission to write the printer device file, and does not provide any useful error message. The printer device files can be made "world writable" to bypass the problem, but that is insecure and is not the proper solution.
 
  
As of CUPS version 2.0.0-2, if the group in the Group directive is also in the SystemGroup directive, {{ic|cupsd}} will exit immediately after starting, and, at a log level of "notice" or higher, will log an error message to the default error log, but not to the system log.
+
By default, all logs are sent to files in {{ic|/var/log/cups/}}. By changing the values of the {{ic|AccessLog}}, {{ic|ErrorLog}}, and {{ic|PageLog}} directives in {{ic|/etc/cups/cups-files.conf}} to {{ic|syslog}}, CUPS can be made to log to the [[systemd journal]] instead. See [https://fedoraproject.org/wiki/Changes/CupsJournalLogging the fedora wiki page] for information on the original proposed change.
{{hc|/var/log/cups/error_log|Group and SystemGroup cannot use the same groups.}}
 
This solves the problem of {{ic|cupsd}} running in a non-functional state and failing to print without explanation.
 
  
At the default log level of "warn", no group collision error message is logged.  To see this error message, increase the log level to "notice", "info", "debug", or "debug2".
+
=== cups-browsed ===
{{hc|/etc/cups/cupsd.conf|LogLevel notice}}
 
Error messages can be sent to the systemd-journald log instead of to the default {{ic|/var/log/cups/error_log}}, but not to both, by explicitly setting the ErrorLog directive.
 
{{hc|/etc/cups/cups-files.conf|ErrorLog syslog}}
 
Currently, even then, the command {{ic|systemctl status org.cups.cupsd.service}} will not properly display the final group collision error message, but the error message can still be seen in the journal, with for instance, {{ic|sudo journalctl -f}}.
 
  
==== CUPS permission errors ====
+
{{Out of date|{{ic|cups-browsed.service}} is not required to discover printers advertised over DNS-SD, that is done by {{ic|org.cups.cupsd.service}}. The service is only required to discover printers on an LDAP server and those using the legacy CUPS protocol (CUPS servers ≤ 1.5).}}
  
* Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:
+
CUPS can use [[Avahi]] browsing to discover unknown shared printers in your network. This can be useful in large setups where the server is unknown. To use this feature, set up [[Avahi#Hostname_resolution|.local hostname resolution]], and start both {{ic|avahi-daemon.service}} and {{ic|cups-browsed.service}}. Jobs are sent directly to the printer without any processing so the created queues may not work, however driverless printers such as those supporting [http://www.pwg.org/ipp/everywhere.html IPP Everywhere] or [[wikipedia:AirPrint|AirPrint]] should work out of the box.
smb://workgroup/username:password@hostname/printer_name
 
  
* Sometimes, the block device has wrong permissions:
+
{{Note|1=<nowiki></nowiki>
# ls /dev/usb/
+
* Searching for network printers [https://bbs.archlinux.org/viewtopic.php?pid=1720219#p1720219 may significantly increase the time it takes for your computer to boot].
lp0
+
* {{ic|cups-browsed.service}} is only needed to dynamically add and remove printers as they appear and disappear from a network. It is not required if you simply want to add a an DNS-SD/mDNS supporting network printer to CUPS.
# chgrp lp /dev/usb/lp0
 
 
 
==== HPLIP printer sends "/usr/lib/cups/backend/hp failed" error ====
 
 
 
Make sure dbus is installed and running. If the error persists, try starting avahi-daemon.
 
 
 
Try adding the printer as a Network Printer using the http:// protocol. Generate the printer URI with {{ic|hp-makeuri}}.
 
 
 
{{Note|There might need to set permissions issues right. Follow indications here: [[CUPS#Device node permissions]].}}
 
 
 
==== HPLIP printer claims job is complete but printer does nothing ====
 
 
 
This happens on HP printers when you select the (old) hpijs driver (e.g. the Deskjet D1600 series). Instead, use the hpcups driver when adding the printer.
 
 
 
Some HP printers (e.g HP LaserJet) require their firmware to be downloaded from the computer every time the printer is switched on. If there is an issue with udev (or equivalent) and the firmware download rule is never fired, you may experience this issue.
 
As a workaround, you can manually download the firmware to the printer. Ensure the printer is plugged in and switched on, then enter
 
hp-firmware -n
 
 
 
==== hp-setup asks to specify the PPD file for the discovered printer ====
 
 
 
Install CUPS before running hp-setup.
 
 
 
==== I have installed Qt, but hp-setup reports "Qt/PyQt 4 initialization failed" ====
 
 
 
"hp-check -t" won't give you useful information to find the required package. You have to install all the "Dependent Packages" prefixed with "python2" in https://www.archlinux.org/packages/extra/x86_64/hplip/
 
 
 
==== hp-setup finds the printer automatically but reports "Unable to communicate with device" when printing test page immediately afterwards ====
 
 
 
This at least happens to hplip 3.13.5-2 for HP Officejet 6500A through local network connection. To solve the problem, specify the IP address of the HP printer for hp-setup to locate the printer.
 
 
 
==== hp-toolbox sends an error, "Unable to communicate with device" ====
 
 
 
If running hp-toolbox as a regular user results in:
 
# hp-toolbox
 
# error: Unable to communicate with device (code=12): hp:/usb/''printer id''
 
or, "{{ic|Unable to communicate with device"}}", then it may be needed to [[Groups#Group management|add the user to the lp and sys groups]].
 
 
 
This can also be caused by printers such as the P1102 that provide a virtual CD-ROM drive for MS Windows drivers. The lp dev appears and then disappears. In that case, try the '''usb-modeswitch''' and '''usb-modeswitch-data''' packages, that lets one switch off the "Smart Drive" (udev rules included in said packages).
 
 
 
This can also occur with network attached printers if the [[Avahi|avahi-daemon]] is not running. Another possibility is the specification of the printer's IP address in ''hp-setup'' fails to locate the printer because the IP address of the the printer changed due to DHCP. If this is the case, consider adding a DHCP reservation for the printer in the DHCP server's configuration.
 
 
 
==== CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer ====
 
 
 
If receiving any of the following error messages in {{ic|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':
 
Filter "foomatic-rip" for printer ''printer_name'' not available: No such file or director
 
or:
 
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!
 
make sure {{pkg|hplip}} has been [[pacman|installed]], in addition to [[#Packages|the packages mentioned above]]. See [https://bbs.archlinux.org/viewtopic.php?id=65615 this forum post] for more information.
 
 
 
==== Printing fails with unauthorised error ====
 
 
 
If the user has been added to the lp group, and allowed to print (set in {{ic|cupsd.conf}}), then the problem lies in {{ic|/etc/cups/printers.conf}}. This line could be the culprit:
 
AuthInfoRequired negotiate
 
 
 
Comment it out and restart CUPS.
 
 
 
==== Unknown supported format: application/postscript ====
 
 
 
Comment the lines:
 
application/octet-stream        application/vnd.cups-raw        0      -
 
from {{ic|/etc/cups/mime.convs}}, and:
 
application/octet-stream
 
in {{ic|/etc/cups/mime.types}}.
 
 
 
==== Finding URIs for Windows print servers ====
 
 
 
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations).  If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:
 
$ smbtree -U ''windowsusername''
 
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:
 
{{bc| WORKGROUP
 
\\REGULATOR-PC 
 
\\REGULATOR-PC\Z             
 
\\REGULATOR-PC\Public       
 
\\REGULATOR-PC\print$        Printer Drivers
 
\\REGULATOR-PC\G             
 
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series}}
 
What is needed here is first part of the last line, the resource matching the printer description.  So to print to the EPSON Stylus printer, one would enter:
 
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series
 
as the URI into CUPS.  Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.
 
If it won't work try '%20' instead of spaces.
 
 
 
==== Print-Job client-error-document-format-not-supported ====
 
 
 
Try installing the foomatic packages and use a foomatic driver.
 
 
 
==== Unable to get list of printer drivers ====
 
 
 
* Check the {{ic|ServerName}} in {{ic|/etc/cups/client.conf}} is written without http://
 
ServerName localhost:631
 
* Try to remove Foomatic drivers or refer to [[#HP_Printer]] for a workaround.
 
 
 
==== lp: Error - Scheduler Not Responding ====
 
 
 
If you get this error when printing a document using:
 
 
 
$ lp document-to-print
 
 
 
Try setting the {{ic|CUPS_SERVER}} environment variable:
 
 
 
$ export CUPS_SERVER=localhost
 
 
 
If this solves your problem, make the solution permanent by adding the export line above to {{ic|~/.bash_profile}}.
 
 
 
==== CUPS prints only an empty and an error-message page on HP LaserJet ====
 
 
 
There is a bug that causes CUPS to fail when printing images on HP LaserJet (in my case 3380). The bug has been reported and fixed by [https://bugs.launchpad.net/ubuntu/+source/cups-filters/+bug/998087 Ubuntu].
 
The first page is empty, the second page contains the following error message:
 
  ERROR:
 
  invalidaccess
 
  OFFENDING COMMAND:
 
  filter
 
  STACK:
 
  /SubFileDecode
 
  endstream
 
  ...
 
 
 
In order to fix the issue, run the following command as root:
 
# lpadmin -p ''printer'' -o pdftops-renderer-default=pdftops
 
 
 
==== "Using invalid Host" error message ====
 
 
 
Try adding {{ic|ServerAlias *}} into {{ic|/etc/cups/cupsd.conf}}.
 
 
 
==== Printer doesn't print with an "Filter failed" message on CUPS web interface (HP printer) ====
 
 
 
Change the permissions of the printer USB port. Get the bus and device number from {{ic|lsusb}}, then set the permission using:
 
 
 
{{hc| lsusb |
 
Bus <BUSID> Device <DEVID>: ID <PRINTERID>:<VENDOR> Hewlett-Packard DeskJet D1360}}
 
 
 
Then substitute the provided device information to the
 
 
 
# chmod 0666 /dev/bus/usb/<BUSID>/<DEVID>
 
 
 
To make the persistent permission change that will be triggered automatically each time the computer is rebooted, add the following line.
 
 
 
{{hc|/etc/udev/rules.d/10-local.rules|2=
 
SUBSYSTEM=="usb", ATTRS{idVendor}=="<VENDOR>", ATTRS{idProduct}=="<PRINTERID>", GROUP="lp", MODE:="666"
 
 
}}
 
}}
 
Each system may vary, so consult [[udev#List_attributes_of_a_device]] wiki page.
 
  
==== Printer does not print with a "Filter failed" message on CUPS web interface (HP printer connected over network) ====
+
=== Print servers and remote administration ===
  
Start, enable, and restart the {{ic|avahi-daemon}} service.
+
See [[CUPS/Printer sharing]] and [[CUPS/Printer sharing#Remote administration]].
  
==== HPLIP 3.13: Plugin is installed, but HP Device Manager complains it is not ====
+
=== Allowing admin authentication through PolicyKit ===
  
The issue might have to do with the file permission change that had been made to {{ic|/var/lib/hp/hplip.state}}. To correct the issue, a simple {{ic|chmod 644 /var/lib/hp/hplip.state}} and {{ic|chmod 755 /var/lib/hp}} should be sufficient. For further information, please read this [https://bugs.launchpad.net/hplip/+bug/1131596 link].
+
[[PolicyKit]] can be configured to allow users to configure printers using a GUI without the admin password.
  
==== Printer is not recognized by CUPS ====
+
{{Note|1=You may need to install {{Pkg|cups-pk-helper}} for working this rules.}}
  
If your printer is not listed in the "Add Printers" page of the CUPS web interface, nor by {{ic|lpinfo -v}}, try the following (suggested in [https://bbs.archlinux.org/viewtopic.php?pid=1037279#p1037279 this thread]):
+
Here is an example that allows members of the wheel [[user group]] to administer printers without a password:
  
* Remove {{ic|usblp}} from blacklist
+
{{hc|/etc/polkit-1/rules.d/49-allow-passwordless-printer-admin.rules|<nowiki>
* Load {{ic|usblp}} module
+
polkit.addRule(function(action, subject) {
# modprobe usblp
+
    if (action.id == "org.opensuse.cupspkhelper.mechanism.all-edit" &&
* Stop CUPS
+
        subject.isInGroup("wheel")){
* Add the following udev rule in a new rule file:
+
        return polkit.Result.YES;
{{hc|/etc/udev/rules.d/10-cups_device_link.rules|2=
+
    }  
KERNEL=="lp[0-9]", SYMLINK+="%k", GROUP="lp"
+
});
}}
+
</nowiki>}}
* Reload udev rules:
 
# udevadm control --reload-rules
 
* Unplug the printer, and plug it in again.
 
* Wait a few seconds, and then start the CUPS service.
 
  
==== Cannot load /etc/samba/smb.conf ====
+
=== Without a local CUPS server ===
  
If you are printing to a remote printer over SMB and get this error message: "Can't load /etc/samba/smb.conf - run testparm to debug it", then create an empty {{ic|/etc/samba/smb.conf}} file:
+
CUPS can be configured to directly connect to remote printer servers instead of running a local print server. This requires [[install]]ation of the {{Pkg|libcups}} package. Some applications will still require the {{Pkg|cups}} package for printing.
  
# mkdir /etc/samba
+
{{Warning|Accessing remote printers without a local CUPS server is not recommended by the developers. [https://lists.cups.org/pipermail/cups/2015-October/027229.html]}}
# touch /etc/samba/smb.conf
 
  
and restart the CUPS service.
+
To use a remote CUPS server, set the {{ic|CUPS_SERVER}} [[environment variable]] to {{ic|printerserver.mydomain:port}}. For instance, if you want to use a different print server for a single [[Firefox]] instance (substitute {{ic|printserver.mydomain:port}} with your print server name/port):
  
==== CUPS' systemd service does not start even though it is enabled ====
+
$ CUPS_SERVER=printserver.mydomain:port firefox
  
The systemd service file provided by CUPS uses socket activation, meaning the service is only started when an application connects to CUPS' socket. However, the systemd socket file provided by CUPS only works for the local
+
== Troubleshooting ==
{{ic|/run/cups/cups.sock}} socket.
 
 
 
In order to have the CUPS service start when initiating a print job over the network, create the following file:
 
 
 
{{hc|1=/etc/systemd/system/org.cups.cupsd.socket|2=
 
.include /usr/lib/systemd/system/org.cups.cupsd.socket
 
 
 
[Socket]
 
ListenDatagram=0.0.0.0:631
 
}}
 
 
 
Then reload systemd:
 
 
 
# systemctl --system daemon-reload
 
 
 
Confirm that everything is working correctly:
 
 
 
{{bc|
 
# systemctl is-enabled org.cups.cupsd.service &#124;&#124; systemctl enable org.cups.cupsd.service
 
# systemctl status org.cups.cupsd.socket
 
org.cups.cupsd.socket - CUPS Printing Service Sockets
 
        Loaded: loaded (/etc/systemd/system/org.cups.cupsd.socket; enabled)
 
        Active: inactive (dead)
 
        Listen: /run/cups/cups.sock (Stream)
 
                0.0.0.0:631 (Stream)
 
                0.0.0.0:631 (Datagram)
 
}}
 
 
 
CUPS should now start automatically when printing locally or over the network.
 
 
 
==== "Forbidden" error when adding a printer ====
 
 
 
If adding a printer through the web interface returns an error: ''Forbidden'', the most likely reason is that the privileges are not set correctly. One way to fix it is to add the administering user to the group {{ic|sys}}. For example,
 
# usermod -a -G sys ''username''
 
 
 
==== CUPS identifies printer but cannot connect to it ====
 
 
 
Enable debug logging. If you see <code>Executing backend "/usr/lib/cups/backend/dnssd"...</code> over and over switch from dnssd to socket in the printer configuration.
 
  
Example: <code>socket://192.168.11.6:9100</code>. The port number can be confirmed via nmap or `telnet your-printer-ip 9100`
+
See [[CUPS/Troubleshooting]].
  
 
== See also ==
 
== See also ==
  
 
* [http://localhost:631/help Official CUPS documentation], ''locally installed''
 
* [http://localhost:631/help Official CUPS documentation], ''locally installed''
* [http://www.cups.org/ Official CUPS website]
+
* [[Wikipedia:CUPS]]
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''
+
* [http://www.linuxfoundation.org/collaborate/workgroups/openprinting OpenPrinting homepage]
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's printing guide], ''[http://www.gentoo.org/doc/en  Gentoo Documentation resources]''
+
* [https://en.opensuse.org/Concepts_printing OpenSuSE Concepts printing guide - explains the full printing workflow]
* [http://wiki.gotux.net/tutorials/software/hp-printer Install HP printers easy way]{{Dead link|2014|11|13}}
+
* [https://en.opensuse.org/SDB:CUPS_in_a_Nutshell OpenSuSE CUPS in a Nutshell - a quick CUPS overview]
 +
* [https://wiki.gentoo.org/wiki/Printing Gentoo's printing guide]
 +
* [[debian:Printing|Debian's Printing portal - detailed technical guides]]
 +
* [[debian:SystemPrinting|Debian's printing overview - a basic view of the CUPS printing system]]

Latest revision as of 16:10, 30 August 2019

CUPS is the standards-based, open source printing system developed by Apple Inc. for macOS® and other UNIX®-like operating systems.

Installation

Install the cups package.

If you intend to "print" into a PDF document, also install the cups-pdf package. By default, pdf files are stored in /var/spool/cups-pdf/username/. The location can be changed in /etc/cups/cups-pdf.conf.

Enable and start org.cups.cupsd.service.

Socket activation

cups provides a org.cups.cupsd.socket unit. If org.cups.cupsd.socket is enabled (and org.cups.cupsd.service is disabled), systemd will not start CUPS immediately, it will just listen to the appropriate sockets. Then, whenever a program attempts to connect to one of these CUPS sockets, systemd will start org.cups.cupsd.service and transparently hand over control of these ports to the CUPS process.

This way, CUPS is only started once a program wants to make use of the service.

Connection Interfaces

Additional steps for printer detection are listed below for various connection interfaces.

Note:
  • CUPS helper programs are run using the cups user and group. This allows the helper programs to access printer devices and read config files in /etc/cups/, which are owned by the cups group.
  • Prior to cups 2.2.6-2, the lp group was used instead. After the upgrade, the files in /etc/cups should be owned by the cups group and User 209 and Group 209 set in /etc/cups/cups-files.conf.

USB

To see if your USB printer is detected:

$ lsusb
(...)
Bus 001 Device 007: ID 03f0:1004 Hewlett-Packard DeskJet 970c/970cse

Parallel port

To use a parallel port printer, the lp, parport and parport_pc kernel modules are required.

$ dmesg | grep -i parport
 parport0: Printer, Hewlett-Packard HP LaserJet 2100 Series
 lp0: using parport0 (polling)

Network

To discover or share printers using DNS-SD/mDNS, setup .local hostname resolution with Avahi and restart org.cups.cupsd.service.

Note: DNS-SD is only supported when using Avahi. CUPS does not support using systemd-resolved for DNS-SD, see CUPS issue 5452.

To share printers with Samba, e.g. if the system is to be a print server for Windows clients, the samba package will be required.

Printer Drivers

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: CUPS is planning to drop PPD and driver support (CUPS issue 5271), instead relying entirely on IPP Everywhere. Explain what is/will be handled by cups and what by cups-filters and/or other software. (Discuss in Talk:CUPS#)


The drivers for a printer may come from any of the sources shown below. See CUPS/Printer-specific problems for an incomplete list of drivers that others have managed to get working.

To drive a printer, CUPS needs a PPD file and, for most printers, some filters. For details on how CUPS uses PPDs and filters, see [1].

The OpenPrinting Printer List provides driver recommendations for many printers. It also supplies PPD files for each printer, but most are available through foomatic or the recommended driver package.

When a PPD file is provided to CUPS, the CUPS server will regenerate the PPD files and save them in /etc/cups/ppd/.

CUPS

CUPS includes support for AirPrint and IPP Everywhere printers.

OpenPrinting CUPS filters

The Linux Foundation's OpenPrinting workgroup provides cups-filters. Those are backends, filters, and other binaries that were once part of CUPS but are no longer maintained by Apple. They are available in the cups-filters package that is a dependency of cups.

Non-PDF printers require ghostscript to be installed. For PostScript printers gsfonts may also be required.

Foomatic

The Linux Foundation's OpenPrinting workgroup's foomatic provides PPDs for many printer drivers, both free and nonfree. For more information about what foomatic does, see Foomatic from the Developer's View.

To use foomatic, install foomatic-db-engine and at least one of:

The foomatic PPDs may require additional filters, such as min12xxwAUR.

Gutenprint

The Gutenprint project provides drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with CUPS and GIMP.

Install gutenprint and foomatic-db-gutenprint-ppds.

Note: When the Gutenprint packages get updated, the printers using Gutenprint drivers will stop working until you run cups-genppdupdate as root and restart CUPS. cups-genppdupdate will update the PPD files of the configured printers, see cups-genppdupdate(8) for more details.

Manufacturer-specific drivers

Many printer manufacturers supply their own Linux drivers. These are often available in the official Arch repositories or in the AUR.

Some of those drivers are described in more detail in CUPS/Printer-specific problems.

Printer URI

Listed below are additional steps to manually generate the URI if required. Some printers or drivers may need a special URI as described in CUPS/Printer-specific problems.

USB

CUPS should be able to automatically generate a URI for USB printers, for example usb://HP/DESKJET%20940C?serial=CN16E6C364BH.

If it does not, see CUPS/Troubleshooting#USB printers for troubleshooting steps.

Parallel port

The URI should be of the form parallel:device. For instance, if the printer is connected on /dev/lp0, use parallel:/dev/lp0. If you are using a USB to parallel port adapter, use parallel:/dev/usb/lp0 as the printer URI.

Network

If you have set up Avahi as in #Network, CUPS should detect the printer URI. You can also use avahi-discover to find the name of your printer and its address (for instance, BRN30055C6B4C7A.local/10.10.0.155:631).

The URI can also be generated manually, without using Avahi. A list of the available URI schemes for networked printers is available in the CUPS documentation. As exact details of the URIs differ between printers, check either the manual of the printer or CUPS/Printer-specific problems.

The URI for printers on SMB shares is described in the smbspool(8) man page.

Note: Any special characters in the printer URIs need to be appropriately quoted, or, if your Windows printer name or user passwords have spaces, CUPS will throw a lpadmin: Bad device-uri error.

For example, smb://BEN-DESKTOP/HP Color LaserJet CP1510 series PCL6 becomes smb://BEN-DESKTOP/HP%20Color%20LaserJet%20CP1510%20series%20PCL6.

This result string can be obtained by running the following command:

$ python -c 'from urllib.parse import quote; print("smb://" + quote("BEN-DESKTOP/HP Color LaserJet CP1510 series PCL6"))'

Remote CUPS print servers can be accessed through a URI of the form ipp://hostname:631/printers/queue_name. See CUPS/Printer sharing#Printer sharing for details on setting up the remote print server.

See CUPS/Troubleshooting#Networking issues for additional issues and solutions.

Warning: Avoid configuring both the server and the client with a printer filter - either the print queue on the client or the server should be 'raw'. This avoids sending a print job through the filters for a printer twice, which can cause problems (for instance, [2]). See #Usage for an example of setting a print queue to 'raw'.

Usage

CUPS can be fully controlled using the lp* and cups* CLI tools. Alternatively, the #Web interface or one of several #GUI applications can be used.

  • The queue name is a short but descriptive name used on the system to identify the queue. This name should not contain spaces or any special characters. For instance, a print queue corresponding to a HP LaserJet 5P could be named "hpljet5p". More than one queue can be associated with each physical printer.
  • The location is a description of the printer's physical location (for instance "bedroom", or "kitchen"). This is to aid in maintaining several printers.
  • The description is a full description of the print queue. A common use is a full printer name (like "HP LaserJet 5P").

CLI tools

See CUPS local documentation for more tips on the command-line tools.

Note: Command-line switches cannot be grouped

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements. See Help:Style for reference.Tango-edit-clear.png

Reason: Nonstandard use of definition lists, comments in command line. (Discuss in Talk:CUPS#)
List the devices
# lpinfo -v
$ /usr/lib/cups/backend/snmp ip_address  # Use SNMP to find a URI
List the models
$ lpinfo -m
Add a new queue
# lpadmin -p queue_name -E -v uri -m model

The queue_name is up to you. Examples:

# lpadmin -p HP_DESKJET_940C -E -v "usb://HP/DESKJET%20940C?serial=CN16E6C364BH" -m drv:///HP/hp-deskjet_940c.ppd.gz
# lpadmin -p AirPrint -E -v "ipp://10.0.1.25/ipp/print" -m everywhere    # Driverless queue (Apple AirPrint or IPP Everywhere)
# lpadmin -p SHARED_PRINTER -m raw    # Raw queue; no PPD or filter
# lpadmin -p Test_Printer -E -v "ipp://10.0.1.3/ipp/print" -m pxlmono.ppd    # Specifying a PPD instead of a model
Note: When specifying the PPD, use just the file name and not the full path (for instance, pxlmono.ppd instead of /usr/share/ppd/cupsfilters/pxlmono.ppd). Alternatively, the full path can be used with the -P command line switch.
Set the default printer
$ lpoptions -d queue_name
Change the options
$ lpoptions -p queue_name -l # List the options
$ lpoptions -p queue_name -o option=value # Set an option

Example:

$ lpoptions -p HP_DESKJET_940C -o PageSize=A4
Check the status
$ lpstat -s
$ lpstat -p queue_name
Deactivate a printer
# cupsdisable queue_name
Activate a printer
# cupsenable queue_name
Set the printer to accept jobs
# cupsaccept queue_name
Remove a printer

First set it to reject all incoming entries:

# cupsreject queue_name

Then disable it.

# cupsdisable queue_name

Finally remove it.

# lpadmin -x queue_name
Print a file
$ lpr file
$ lpr -# 17 file            # print the file 17 times
$ echo 'Hello, world!' | lpr -p # print the result of a command. The -p switch adds a header.
Check the queue
$ lpq
$ lpq -a # on all queues
Clear the queue
# lprm   # remove last entry only
# lprm - # remove all entries

Web interface

The CUPS server can be fully administered through the web interface, available on http://localhost:631/.

Note: If an HTTPS connection to CUPS is used, it may take a very long time before the interface appears the first time it is accessed. This is because the first request triggers the generation of SSL certificates which can be a time-consuming job.

To perform administrative tasks from the web interface authentication is required. Authenticate either as root or make sure your user is member of a group with printer administration privileges, see #Configuration.

Add a queue

Go to the Administration page.

Modify existing queues

Go to the Printers page, and select a queue to modify.

Test a queue

Go to the Printers page, and select a queue.

GUI applications

If your user does not have sufficient privileges to administer CUPS, the applications will request the root password when they start. To give users administrative privileges without needing root access, see #Configuration.

  • GtkLP — GTK interface for CUPS.
https://gtklp.sirtobi.com/index.shtml || gtklpAUR
  • print-manager — Tool for managing print jobs and printers (KDE).
https://cgit.kde.org/print-manager.git || print-manager
  • system-config-printer — GTK printer configuration tool and status applet.
http://cyberelk.net/tim/software/system-config-printer/ || system-config-printer

Configuration

The CUPS server configuration is located in /etc/cups/cupsd.conf and /etc/cups/cups-files.conf (see cupsd.conf(5) and cups-files.conf(5)). After editing either file, restart org.cups.cupsd.service to apply any changes. The default configuration is sufficient for most users.

User groups with printer administration privileges are defined in SystemGroup in the /etc/cups/cups-files.conf. The sys and root and wheel groups are used by default.

cups is built with libpaper support and libpaper defaults to the Letter paper size. To avoid having to change the paper size for each print queue you add, edit /etc/papersize and set your system default paper size. See papersize(5).

By default, all logs are sent to files in /var/log/cups/. By changing the values of the AccessLog, ErrorLog, and PageLog directives in /etc/cups/cups-files.conf to syslog, CUPS can be made to log to the systemd journal instead. See the fedora wiki page for information on the original proposed change.

cups-browsed

Tango-view-refresh-red.pngThis article or section is out of date.Tango-view-refresh-red.png

Reason: cups-browsed.service is not required to discover printers advertised over DNS-SD, that is done by org.cups.cupsd.service. The service is only required to discover printers on an LDAP server and those using the legacy CUPS protocol (CUPS servers ≤ 1.5). (Discuss in Talk:CUPS#)

CUPS can use Avahi browsing to discover unknown shared printers in your network. This can be useful in large setups where the server is unknown. To use this feature, set up .local hostname resolution, and start both avahi-daemon.service and cups-browsed.service. Jobs are sent directly to the printer without any processing so the created queues may not work, however driverless printers such as those supporting IPP Everywhere or AirPrint should work out of the box.

Note:

Print servers and remote administration

See CUPS/Printer sharing and CUPS/Printer sharing#Remote administration.

Allowing admin authentication through PolicyKit

PolicyKit can be configured to allow users to configure printers using a GUI without the admin password.

Note: You may need to install cups-pk-helper for working this rules.

Here is an example that allows members of the wheel user group to administer printers without a password:

/etc/polkit-1/rules.d/49-allow-passwordless-printer-admin.rules
polkit.addRule(function(action, subject) { 
    if (action.id == "org.opensuse.cupspkhelper.mechanism.all-edit" && 
        subject.isInGroup("wheel")){ 
        return polkit.Result.YES; 
    } 
});

Without a local CUPS server

CUPS can be configured to directly connect to remote printer servers instead of running a local print server. This requires installation of the libcups package. Some applications will still require the cups package for printing.

Warning: Accessing remote printers without a local CUPS server is not recommended by the developers. [3]

To use a remote CUPS server, set the CUPS_SERVER environment variable to printerserver.mydomain:port. For instance, if you want to use a different print server for a single Firefox instance (substitute printserver.mydomain:port with your print server name/port):

$ CUPS_SERVER=printserver.mydomain:port firefox

Troubleshooting

See CUPS/Troubleshooting.

See also