Difference between revisions of "CUPS"

From ArchWiki
Jump to: navigation, search
(Installing: install instructions compliance.)
m (Connection Interfaces: style)
(677 intermediate revisions by more than 100 users not shown)
Line 1: Line 1:
[[Category:Printers (English)]]
+
[[Category:Printers]]
{{i18n|CUPS}}
+
[[cs:CUPS]]
{{Article summary start|Summary}}
+
[[de:CUPS]]
{{Article summary text|Installing and configuring CUPS}}
+
[[es:CUPS]]
{{Article summary heading|Related}}
+
[[fr:CUPS]]
{{Article summary wiki|CUPS printer sharing}}
+
[[it:CUPS]]
{{Article summary wiki|CUPS printer-specific problems}}
+
[[ja:CUPS]]
{{Article summary wiki|Samba}}
+
[[pl:CUPS]]
{{Article summary end}}
+
[[ru:CUPS]]
 +
[[th:CUPS]]
 +
[[zh-hans:CUPS]]
 +
[[zh-hant:CUPS]]
 +
{{Related articles start}}
 +
{{Related|CUPS/Printer sharing}}
 +
{{Related|CUPS/Printer-specific problems}}
 +
{{Related|CUPS/Troubleshooting}}
 +
{{Related|Samba}}
 +
{{Related|LPRng}}
 +
{{Related articles end}}
  
From [http://www.cups.org/index.php CUPS' site]:
+
[http://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 Mac 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 ==
  
==Installing==
+
[[Install]] the {{Pkg|cups}} package.
The packages {{Pkg|cups}}, {{Pkg|ghostscript}}, and {{Pkg|gsfonts}} are needed. [[pacman|Install]] them from the [[Official repositories]].
 
  
If regular cups does not work you may try installing {{AUR|cups-usblp}} from the [[AUR]] (Recommended for Samsung USB printers).
+
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/$USER}}. The location can be changed in {{ic|/etc/cups/cups-pdf.conf}}.
  
* '''cups''' - The actual CUPS software
+
[[Enable]] and [[start]] {{ic|org.cups.cupsd.service}}.
* '''ghostscript''' - Interpreter for the Postscript language
 
* '''gsfonts''' - GhostScript standard Type1 fonts
 
* '''hpoj''' - If you are using an HP Officejet, you should also install this package and follow the instructions to avoid problems. Read this [http://answers.launchpad.net/hplip/+question/133425 thread at launchpad/hplip] for more information.
 
  
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}}.
+
== Connection Interfaces ==
 +
Additional steps for printer detection are listed below for various connection interfaces.
  
===Printer driver===
+
{{Note|1=<nowiki></nowiki>
Here are some of the driver packages. Choosing the right driver depends on the printer:
+
* 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|/etc/cups/cups-files.conf}} should have {{ic|User 209}} and {{ic|Group 209}}.
 +
}}
  
* '''{{Pkg|gutenprint}}''' - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostSscript, CUPS, Foomatic, and the [[GIMP]]
+
=== USB ===
* '''{{Pkg|foomatic-db}}, {{Pkg|foomatic-db-engine}}, {{Pkg|foomatic-db-nonfree}}, and {{Pkg|foomatic-filters}}''' - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix. Installing foomatic-filters should solve problems if the cups error_log is reporting "stopped with status 22!".
+
To see if your USB printer is detected:
* '''{{AUR|foo2zjs}}''' - Drivers for ZjStream protocol printers such as the HP Laserjet 1018. More info [http://foo2zjs.rkkda.com here], Foo2zsj is available in the {{AUR|foo2zjs}}.
+
{{hc|$ lsusb|
* '''{{Pkg|hplip}}''' - HP GNU/Linux driver. Provides support for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models, as well as a number of Brother printers.
+
(...)
* '''{{Pkg|splix}}''' - Samsung drivers for SPL (Samsung Printer Language) printers (for USB printers use with {{AUR|cups-usblp}} from the [[AUR]])
+
Bus 001 Device 007: ID 03f0:1004 Hewlett-Packard DeskJet 970c/970cse
* '''{{AUR|ufr2}}''' - Canon UFR2 driver with support for LBP, iR and MF series printers. Package is available in the [[AUR]].
+
}}
* '''{{Pkg|cups-pdf}}''' - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it
 
  
If unsure of what driver package to install or if the current driver is not working, it may be easiest to just install all of drivers, since some of the packages are misleading because printers of other makes may rely on them. For instance, the Brother HL-2140 needs the hplip driver installed.
+
=== Parallel port ===
 +
To use a parallel port printer, the {{ic|lp}}, {{ic|parport}} and {{ic|parport_pc}} [[kernel modules]] are required.
  
====Download printer PPD====
+
{{hc|$ dmesg {{!}} grep -i parport|
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.
+
parport0: Printer, Hewlett-Packard HP LaserJet 2100 Series
 +
lp0: using parport0 (polling)
 +
}}
  
Here is an explanation of what a PPD file is from the Linux Printing website:
+
=== Network ===
:"''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.''"
+
[[Avahi]] can be used to scan for printers on the local network. To use [[Avahi]] hostnames to connect to networked printers, set up [[Avahi#Hostname_resolution|.local hostname resolution]] and [[restart]] {{ic|org.cups.cupsd.service}}.
  
If the PPD for the printer is ''not'' already in CUPS, then:
+
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, install the {{Pkg|samba}} package.
*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/}}}}
+
== Printer Drivers ==
 +
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.
  
==Configuring==
+
To drive a printer, CUPS needs a PPD file and, for most printers, some [https://www.cups.org/doc/man-filter.html filters].
Now that CUPS is installed, there are a variety of options on how to setup printing solutions. As always, the tried and true command line method is at your disposal. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. However, in order to make this process easy for the largest amount of users, this article will focus on the web interface provided by CUPS.
+
For details on how CUPS uses PPDs and filters, see [https://www.cups.org/doc/postscript-driver.html].
  
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.
+
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.
  
===Kernel modules===
+
When a PPD file is provided to CUPS, the CUPS server will regenerate the PPD files and save them in {{ic|/etc/cups/ppd/}}.
Before using the CUPS web interface, the appropriate kernel modules need to be installed. The following steps are from the Gentoo Printing Guide.
 
  
This section may not be necessary, however, depending on which kernel is being used. The kernel module may load automatically after plugging in the printer. Use the {{ic|tail}} command (described below) to see if the printer has already been detected. The {{ic|lsmod}} utility can also be used to see what modules have been loaded.
+
=== CUPS ===
 +
CUPS provides a few PPDs and filter binaries by default, which should work out of the box. CUPS also provides support for [[wikipedia:AirPrint|AirPrint]] and [http://www.pwg.org/ipp/everywhere.html IPP Everywhere] printers.
  
====USB printers====
+
=== Foomatic ===
USB printer users may need to blacklist the {{ic|usblp}} module. Keep in mind that there seems to be a lot of [http://bbs.archlinux.org/viewtopic.php?pid=660601 uncertainty] regarding blacklisting {{ic|usblp}}, as some USB printers, including some Canon and Epson printer series, are not recognized without it. Several user reported issues with Samsung printers when using {{ic|cups}} with blacklisted {{ic|usblp}} module, the solution was to re-enable {{ic|usblp}} and install {{ic|cups-usblp}} from aur instead of regular {{ic|cups}} package (https://bbs.archlinux.org/viewtopic.php?pid=778104)
+
The [https://wiki.linuxfoundation.org/openprinting/database/foomatic foomatic] project 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].
  
To blacklist the module:
+
To use foomatic, install {{pkg|foomatic-db-engine}}, and at least one of {{pkg|foomatic-db}}, {{pkg|foomatic-db-ppds}}, {{pkg|foomatic-db-nonfree-ppds}}, or {{pkg|foomatic-db-gutenprint-ppds}}.
  
{{hc|/etc/modprobe.d/blacklist.conf|blacklist usblp}}
+
The foomatic PPDs may require additional filters, such as {{pkg|gutenprint}}, {{pkg|ghostscript}}, or another source (for instance {{aur|min12xxw}}).
 +
For {{pkg|ghostscript}}, {{pkg|gsfonts}} may also be required.
  
Custom kernel users may need to manually load the {{ic|usbcore}} module before proceeding:
+
=== Manufacturer-specific drivers ===
# modprobe usbcore
+
Many printer manufacturers supply their own Linux drivers. These are often available in the official Arch repositories or in the [[AUR]].
  
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:
+
Some of those drivers are described in more detail in [[CUPS/Printer-specific problems]].
# 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:
+
== Printer URI ==
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional
 
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E
 
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920
 
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:
+
Listed below are additional steps to manually generate the URI if required.
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====
+
=== USB ===
To use a parallel port printer the configuration is pretty much the same, except for the modules:
 
# modprobe lp
 
# modprobe parport
 
# modprobe parport_pc
 
  
Once again, check the setup by running:
+
CUPS should be able to automatically generate a URI for USB printers, for example {{ic|1=usb://HP/DESKJET%20940C?serial=CN16E6C364BH}}.
# 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 /etc/cups/printers.conf:
+
If it doesn't, see [[CUPS/Troubleshooting#USB printers]] for troubleshooting steps.
DeviceID = parallel:/dev/usb/lp0
 
  
====Auto-loading====
+
=== Parallel port ===
It is convenient to have the system automatically load the kernel module every time the it starts up. To do so, use a text editor to open up {{ic|/etc/[[rc.conf]]}} and add the appropriate module to the {{ic|1=MODULES=()}} line. Here is an example:
 
MODULES=(!usbserial scsi_mod sd_mod snd-ymfpci snd-pcm-oss '''lp parport parport_pc''' ide-scsi)
 
  
===CUPS daemon===
+
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}}.
With the kernel modules installed, the you can now start the [[Daemon#Performing daemon actions manually|start the cupsd daemon]]. Add cupsd to your [[daemons#Starting on Boot|DAEMONS array]] so it starts automatically on boot.
+
If you are using a USB to parallel port adapter, use {{ic|parallel:/dev/usb/lp0}} as the printer URI.
  
=== Web interface and tool-kit ===
+
=== Network ===
  
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/hosts}}).
+
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}}).
  
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 user-name 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.
+
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]].
  
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.
+
Remote CUPS print servers can be accessed through a URI of the form {{ic|ipp://''hostname'':631/printers/''queue_name''}}. See [[CUPS/Printer sharing#Between GNU/Linux systems]] for details on setting up the remote print server.
  
{{Tip|See: [[#Alternative CUPS interfaces]] for other other frontends.}}
+
See [[CUPS/Troubleshooting#Networking issues]] for additional issues and solutions.
{{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.}}
 
  
==== CUPS administration ====
+
{{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'.}}
  
A user-name 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 user-name is the one assigned in the ''sys'' group, or root (change this by editing {{ic|/etc/cups/cupsd.conf}} in the line of ''SystemGroup'').
+
== Usage ==
  
If the root account has been locked (i.e. when using sudo), it is not possible to log in the CUPS administration interface with the default user-name and password. In this case, follow [http://www.cups.org/articles.php?L237+T+Qprintadmin these instructions] on the CUPS FAQ.  You might also want to read [http://bbs.archlinux.org/viewtopic.php?id=35567 this post].
+
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.
  
====Remote access to web interface====
+
* 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.
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:
+
* The ''location'' is a description of the printer's physical location (for instance "bedroom", or "kitchen"). This is to aid in maintaining several printers.
Listen localhost:631
+
* The ''description'' is a full description of the print queue. A common use is a full printer name (like "HP LaserJet 5P").
with
 
port 631
 
so that CUPS listens to incoming requests.
 
  
Three levels of access can be granted:
+
=== CLI tools ===
<Location />          #access to the server
 
<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:
+
See [http://localhost:631/help/options.html CUPS local documentation] for more tips on the command-line tools.
Allow all
 
Allow host.domain.com
 
Allow *.domain.com
 
Allow ip-address
 
Allow ip-address/netmask
 
  
Deny statements can also be used. For example, if wanting to give all hosts on the 192.168.1.0/255.255.255.0 subnet full access, file {{ic|/etc/cups/cupsd.conf}} would include this:
+
{{Note|Command-line switches cannot be grouped}}
# Restrict access to the server...
 
# By default only localhost connections are possible
 
<Location />
 
    Order allow,deny
 
    Allow From localhost
 
    '''Allow From 192.168.1.0/255.255.255.0'''
 
</Location>
 
 
# Restrict access to the admin pages...
 
<Location /admin>
 
    # Encryption disabled by default
 
    #Encryption Required
 
    Order allow,deny
 
    Allow From localhost
 
    '''Allow From 192.168.1.0/255.255.255.0'''
 
</Location>
 
 
# Restrict access to configuration files...
 
<Location /admin/conf>
 
    AuthType Basic
 
    Require user @SYSTEM
 
    Order allow,deny
 
    Allow From localhost
 
    '''Allow From 192.168.1.0/255.255.255.0'''
 
</Location>
 
  
You might also need to add:
+
;List the devices
 +
# lpinfo -v #
 +
$ /usr/lib/cups/backend/snmp ''ip_address'' # Use SNMP to find a URI
  
  DefaultEncryption Never
+
;List the models
 +
  $ lpinfo -m
  
This should avoid the error: 426 - Upgrade Required when using the CUPS web interface from a remote machine.
+
;Add a new queue
 +
# lpadmin -p ''queue_name'' -E -v ''uri'' -m ''model''
  
==Troubleshooting==
+
The ''queue_name'' is up to you.
The best way to get printing working is to set 'LogLevel' in {{ic|/etc/cups/cupsd.conf}} to:
+
Examples:
  LogLevel debug
+
# 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
  
And then viewing the output from {{ic|/var/log/cups/error_log}} like this:
+
{{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}})}}
# tail -n 100 -f /var/log/cups/error_log
 
  
The characters at the left of the output stand for:
+
;Set the default printer
*D=Debug
+
$ lpoptions -d ''queue_name''
*E=Error
 
*I=Information
 
*And so on
 
  
These files may also prove useful:
+
;Change the options
*{{ic|/var/log/cups/page_log}} Echoes a new entry each time a print is successful
+
$ lpoptions -p ''queue_name'' -l # List the options
*{{ic|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity
+
  $ lpoptions -p ''queue_name'' -o ''option''=''value'' # Set an option
  
Of course, it is important to know how CUPS works if wanting to solve related issues:
+
Example:
# 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).
+
$ lpoptions -p HP_DESKJET_940C -o PageSize=A4
# 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.
+
;Check the status
 +
$ lpstat -s
 +
$ lpstat -p ''queue_name''
  
===Problems resulting from upgrades===
+
;Deactivate a printer
''Issues that appeared after CUPS and related program packages underwent a version increment''
+
# cupsdisable ''queue_name''
  
====CUPS stops working====
+
;Activate a printer
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" my result from trying to manage CUPS via localhost:631, for example.
+
# cupsenable ''queue_name''
  
To use the new configuration, copy /etc/cups/cupsd.conf.default to /etc/cups/cupsd.conf (backup the old the configuration if needed):
+
;Set the printer to accept jobs
  # cp /etc/cups/cupsd.conf.default /etc/cups/cupsd.conf
+
  # cupsaccept ''queue_name''
and restart CUPS to employ the new settings.
 
  
====Error with gnutls====
+
;Remove a printer
If receiving errors such as:
+
First set it to reject all incoming entries:
  /usr/sbin/cupsd: error while loading shared libraries: libgnutls.so.13: cannot open shared object file: No such file or directory
+
  # cupsreject ''queue_name''
gnutls may be in need of updating:
+
Then disable it.
  # pacman -S gnutls
+
# cupsdisable ''queue_name''
 +
Finally remove it.
 +
  # lpadmin -x ''queue_name''
  
After updating, there may be a file named {{ic|cupsd.conf.pacnew}} in {{ic|/etc/cups}}. This is the unmodified original configuration file that has been placed as part of the update. Compare it with the currently installed version and adjust to preference.
+
;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.
  
====All jobs are "stopped"====
+
;Check the queue
If all jobs sent to the printer become "stopped", delete the printer and add it again.
+
$ lpq
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.
+
$ lpq -a # on all queues
  
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.
+
;Clear the queue
 +
# lprm  # remove last entry only
 +
# lprm - # remove all entries
  
====All jobs are "The printer is not responding"====
+
=== Web interface ===
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.
 
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
+
The CUPS server can be fully administered through the web interface, available on http://localhost:631/.
  
====The PPD version is not compatible with gutenprint====
+
{{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.}}
Run:
 
# /usr/sbin/cups-genppdupdate
 
  
And restart CUPS (as pointed out in gutenprint's post-install message)
+
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]].
  
===USB printers under CUPS 1.4.x===
+
;Add a queue
New CUPS 1.4.x introduces many changes:
+
Go to the '''Administration''' page.  
  
====Configuration file====
+
;Modify existing queues
The syntax of the configuration file cupsd.conf changed. Start with a new cupsd.conf file based on /etc/cups/cupsd.conf.default.
+
Go to the '''Printers''' page, and select a queue to modify.
  
====Blacklisting usblp====
+
;Test a queue
CUPS now uses libusb and printer USB devices (under /dev/bus/usb/) instead of the usblp generated /dev/usb/lpX ones. In order to get USB printers working, the usblp module needs disabling.  Some users have also reported that they needed to reinstall their printer.
+
Go to the '''Printers''' page, and select a queue.
  
{{hc|/etc/modprobe.d/modprobe.conf|blacklist usblp}}
+
=== GUI applications ===
  
====Device node permissions====
+
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]].
In addition to usblp not being loaded, CUPS also needs the ownership of the USB device file of the printer to be root:lp, and permissions to be 660. E.g.
 
$ ls -l /dev/bus/usb/003/002
 
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002
 
  
This is supposed to be achieved by two udev rules in /lib/udev/rules.d/50-udev-default.rules:
+
* {{App|print-manager|A tool for managing print jobs and printers ([[KDE]]).|https://cgit.kde.org/print-manager.git|{{Pkg|print-manager}}}}
# hplip and cups 1.4+ use raw USB devices, so permissions should be similar to
+
* {{App|system-config-printer|A GTK+ printer configuration tool and status applet|http://cyberelk.net/tim/software/system-config-printer/|{{Pkg|system-config-printer}}}}
# the ones from the old usblp kernel module
+
* {{App|gtklp|GTK+ interface|https://gtklp.sirtobi.com/index.shtml|{{AUR|gtklp}}}}
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}=="", IMPORT{program}="usb_id --export %p"
 
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}==":0701*:", GROUP="lp", MODE="660"
 
  
However, for some devices, in particular combined printer/scanner devices, these rules either do not trigger, or are overwritten by rules of the 'sane' package. In these cases a custom udev rule needs to be added. See below.
+
== Configuration ==
  
=====Device node permission troubleshooting=====
+
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.
Get the printer's device file and its permissions with:
 
$ lsusb
 
...
 
Bus 003 Device 002: ID 04b8:0841 Seiko Epson Corp.
 
$ ls -l /dev/bus/usb/003/002
 
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002
 
  
If the permissions are not already root:lp 660, enforce it by creating a custom udev rule, e.g
+
[[Groups]] with printer administration privileges are defined in {{ic|SystemGroup}} in the {{ic|/etc/cups/cups-files.conf}}. The {{ic|sys}} group is used by default.
cat /etc/udev/rules.d/10-usbprinter.rules
 
ATTR{idVendor}=="04b8", ATTR{idProduct}=="0841", MODE:="0660", GROUP:="lp"
 
  
If you have a multifunction device (printer+scanner) you need to make the device detectable to sane too
+
{{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}}.
cat /etc/udev/rules.d/10-usbprinter.rules
 
ATTR{idVendor}=="04b8", ATTR{idProduct}=="0841", MODE:="0660", GROUP:="lp", ENV{libsane_matched}:="yes"
 
  
Note that idVendor and idProduct are from the lsusb listing above.<br>
+
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.
Note - some printers will need permissions to be 666
 
  
=====Loading firmware=====
+
=== cups-browsed ===
  
Some printers and drivers need to load firmware to the printer (such as HP LaserJet 10xx printers using foo2zjs) and do this by writing directly to the lp device, a functionality provided by usblp. A work around until this issue is resolved is to install the usblp module until the firmware is loaded, then remove the module to allow CUPS to work. This can be accomplished by manually running "$ modprobe usblp", waiting for the firmware to load, then "$ rmmod usblp". You can also not blacklist usblp, then put "rmmod usblp" to /etc/rc.local, allowing the firmware to be loaded on boot before rc.local is run, then removing usblp.
+
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.
 +
{{Note|1=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].}}
  
In case the printer is plugged in or powered on while system is already running, /etc/rc.local does not get executed and usblp module stays loaded. A workaround is to modify the /etc/udev/rules.d/11-hpj10xx.rules provided by foo2zjs so that after the add event we wait e.g. 15 seconds for the firmware to load and then automatically remove usblp. The following example is for HP LaserJet 1018. For other models the value of ATTRS{idProduct} should be changed to match the printer model.
+
=== Print servers and remote administration ===
  
Locate the line matching your printer in /etc/udev/rules.d/11-hpj10xx.rules:
+
See [[CUPS/Printer sharing]] and [[CUPS/Printer sharing#Remote administration]].
ACTION=="add", KERNEL=="lp*", SUBSYSTEM=="usb", ATTRS{idVendor}=="03f0",    \
 
        ATTRS{idProduct}=="4117", RUN+="/sbin/foo2zjs-loadfw 1018 $tempnode"
 
Add the following lines below it, make sure match the product and vendor IDs:
 
ACTION=="add", KERNEL=="lp*", SUBSYSTEM=="usb", ATTRS{idVendor}=="03f0",    \
 
        ATTRS{idProduct}=="4117", RUN+="/usr/bin/sleep 15"
 
ACTION=="add", KERNEL=="lp*", SUBSYSTEM=="usb", ATTRS{idVendor}=="03f0",    \
 
        ATTRS{idProduct}=="4117", RUN+="/sbin/rmmod usblp"
 
  
===Other===
+
=== Allowing admin authentication through PolicyKit ===
  
=====CUPS permission errors=====
+
[[PolicyKit]] can be configured to allow users to configure printers using a GUI without the admin password.
*Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:
 
smb://workgroup/username:password@hostname/printer_name
 
  
*Sometimes, the block device has wrong permissions:
+
{{Note|1=You may need to install {{Pkg|cups-pk-helper}} for working this rules.}}
# ls /dev/usb/
 
lp0
 
# chgrp lp /dev/usb/lp0
 
  
====HPLIP printer sends "/usr/lib/cups/backend/hp failed" error====
+
Here's an example that allows members of the wheel [[group]] to administer printers without a password:
Make sure dbus is installed and running, e.g. check DAEMONS in {{ic|/etc/rc.conf}} or run {{ic|ls /var/run/daemons}}.
 
  
The avahi-daemon might be required if this error persists and the dbus is already running.
+
{{hc|/etc/polkit-1/rules.d/49-allow-passwordless-printer-admin.rules|<nowiki>
 +
polkit.addRule(function(action, subject) {
 +
    if (action.id == "org.opensuse.cupspkhelper.mechanism.all-edit" &&
 +
        subject.isInGroup("wheel")){
 +
        return polkit.Result.YES;
 +
    }
 +
});</nowiki>}}
  
====hp-toolbox sends an error, "Unable to communicate with device"====
+
=== Without a local CUPS server ===
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 add the user to the lp group by running the following command:
 
# gpasswd -a <username> lp
 
  
====CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer====
+
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.
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 '''hplip''' has been installed, in addition to [[#Packages|the packages mentioned above]], '''net-snmp''' is also needed. See [http://bbs.archlinux.org/viewtopic.php?id=65615 this forum post].
 
# pacman -S hplip
 
  
====Printing fails with unauthorised error====
+
{{Warning|Accessing remote printers without a local CUPS server is not recommended by the developers. [http://www.cups.org/pipermail/cups/2015-October/027229.html]}}
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.
+
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):
  
====Print button greyed-out in GNOME print dialogs====
+
$ CUPS_SERVER=printserver.mydomain:port firefox
:''<small>Source: [http://bbs.archlinux.org/viewtopic.php?id=70418 I can't print from gnome applications. - Arch Forums]</small>''
 
  
Be sure the package: '''libgnomeprint''' is installed
+
== Troubleshooting ==
  
Edit {{ic|/etc/cups/cupsd.conf}} and add
+
See [[CUPS/Troubleshooting]].
# HostNameLookups Double
 
  
Restart CUPS:
+
== See also ==
# /etc/rc.d/cupsd restart
 
  
====Unknown supported format: application/postscript====
+
* [http://localhost:631/help Official CUPS documentation], ''locally installed''
Comment the lines:
+
* [[Wikipedia:CUPS]]
application/octet-stream        application/vnd.cups-raw        0      -
+
* [http://www.linuxfoundation.org/collaborate/workgroups/openprinting OpenPrinting homepage]
from {{ic|/etc/cups/mime.convs}}, and:
+
* [https://en.opensuse.org/Concepts_printing OpenSuSE Concepts printing guide - explains the full printing workflow]
application/octet-stream
+
* [https://en.opensuse.org/SDB:CUPS_in_a_Nutshell OpenSuSE CUPS in a Nutshell - a quick CUPS overview]
in {{ic|/etc/cups/mime.types}}.
+
* [https://wiki.gentoo.org/wiki/Printing Gentoo's printing guide]
 
+
* [[debian:Printing|Debian's Printing portal - detailed technical guides]]
====Finding URIs for Windows Print Servers====
+
* [[debian:SystemPrinting|Debian's printing overview - a basic view of the CUPS printing system]]
 
 
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.
 
 
 
====Print-Job client-error-document-format-not-supported====
 
Try installing the foomatic packages and use a foomatic driver.
 
 
 
====/usr/lib/cups/backend/hp failed====
 
Change
 
  SystemGroup sys root
 
to
 
  SystemGroup lp root
 
in /etc/cups/cupsd.conf
 
 
 
 
 
====Samsung Printer won't print certain documents====
 
 
 
Your Samsung printer may work fine with {{ic|cups}} refuse to print certain documents (Inkscape file with text) and even crash completely, causing a restart. The solution is to use mentioned the {{pkg|cups-usblp}} package and to blacklist the {{ic|usblp}} module as described in this article.
 
 
 
====Local USB printer does not show up====
 
In case your printer does not show up you might need to replace cups with cups-usblp from AUR. Then try it again, once with the usblp module loaded and once with the module blacklisted.
 
 
 
===="Unable to get list of printer drivers"====
 
Try to remove Foomatic drivers.
 
 
 
==Appendix==
 
 
 
===Alternative CUPS interfaces===
 
If using [[GNOME]], a possibility is to manage and configure the printer by using system-config-printer-gnome. This package is available through pacman:  
 
# pacman -S system-config-printer-gnome
 
 
 
For system-config-printer to work as it should, running as root may be required, or alternatively set up a "normal" user to administer CUPS (if so '''follow steps 1-3''')
 
 
 
* 1. Create group, and add a user to it
 
# groupadd lpadmin
 
# usermod -aG lpadmin <username>
 
 
 
* 2. Add "lpadmin" (without the quotes) to this line in {{ic|/etc/cups/cupsd.conf}}
 
SystemGroup sys root <insert here>
 
 
 
* 3. Restart cups, log out and in again (or restart computer)
 
{{bc|# rc.d restart cupsd}}
 
 
 
[[KDE]] users can modify their printers from the Control Center. Both should refer to those desktop environments' documentation for more information on how to use the interfaces.
 
 
 
There is also [https://aur.archlinux.org/packages.php?ID=43505 gtklp] in the [[AUR]]
 
 
 
===PDF virtual printer===
 
CUPS-PDF is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. Obviously this package is not necessary, but it can be quite useful.
 
 
 
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 /etc/cups/cups-pdf.conf by changing the line
 
#Out /var/spool/cups-pdf/${USER}
 
 
 
to
 
 
 
Out /home/${USER}
 
 
 
This package can be installed by the following command:
 
# pacman -S cups-pdf
 
 
 
After installing the package, set it up as if it were for any other printer by using the web interface. For the Device, select '''CUPS-PDF (Virtual PDF Printer)'''; Make/Manufacturer, choose '''Generic'''; Model/Driver, select '''Generic postscript color printer''' or '''Generic Cups-PDF Printer'''. Alternatively, provide the PPD file from [http://www.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/cups-pdf-CURRENT/extra/CUPS-PDF.ppd this link].
 
 
 
==== Print to postscript: CUPS-PDF virtual printer trick ====
 
 
 
Printing to PDF in most applications like OpenOffice is no problem; just hit the button. Yet when printing out to postscript, matters take a little more work. For applications like OpenOffice where printing to kprinter is nebulous at best, there has to be another way -- and there is. The CUPS-PDF (Virtual PDF Printer) actually creates a postscript file and then creates the PDF using the ps2pdf utility. To print to postscript, what needs to be done is capturing the intermediate postscript file created by CUPS-PDF. This is easily accomplished with by selecting the "print to file" option in the print dialog. (choose either .ps or .eps as the extension) After selecting the "print to file" checkbox simply enter the filename and click "print".
 
 
 
=====Configuring CUPS-PDF virtual printer=====
 
#Set up the cups daemon using the instructions on this page.
 
#Install {{Pkg|cups-pdf}} from [extra].
 
#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
 
 
 
Now 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...
 
 
 
===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.
 
 
 
==Resources==
 
* [http://localhost:631/documentation.html Official CUPS documentation], ''locally installed''
 
* [http://www.cups.org/ Official CUPS Website]
 
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''
 
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's Printing Guide], ''[http://www.gentoo.org/doc/en  Gentoo Documentation Resources]''
 
* [http://bbs.archlinux.org/ Arch Linux User Forums]
 

Revision as of 09:54, 31 January 2018

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/$USER. The location can be changed in /etc/cups/cups-pdf.conf.

Enable and start org.cups.cupsd.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 /etc/cups/cups-files.conf should have User 209 and Group 209.

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

Avahi can be used to scan for printers on the local network. To use Avahi hostnames to connect to networked printers, set up .local hostname resolution and restart org.cups.cupsd.service.

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, install the samba package.

Printer Drivers

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 provides a few PPDs and filter binaries by default, which should work out of the box. CUPS also provides support for AirPrint and IPP Everywhere printers.

Foomatic

The foomatic project 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 foomatic-db, foomatic-db-ppds, foomatic-db-nonfree-ppds, or foomatic-db-gutenprint-ppds.

The foomatic PPDs may require additional filters, such as gutenprint, ghostscript, or another source (for instance min12xxwAUR). For ghostscript, gsfonts may also be required.

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.

USB

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

If it doesn't, 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.

Remote CUPS print servers can be accessed through a URI of the form ipp://hostname:631/printers/queue_name. See CUPS/Printer sharing#Between GNU/Linux systems 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
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)
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.

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

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.

Groups with printer administration privileges are defined in SystemGroup in the /etc/cups/cups-files.conf. The sys group is 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

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.

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's an example that allows members of the wheel 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