CUPS
Summary |
---|
Installing and configuring CUPS |
From CUPS' site:
- "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.
Contents
- 1 Installing
- 2 Configuring
- 3 Troubleshooting
- 3.1 Problems resulting from upgrades
- 3.2 USB printers under CUPS 1.4.x
- 3.3 Other
- 3.3.1 CUPS permission errors
- 3.3.2 HPLIP printer sends "/usr/lib/cups/backend/hp failed" error
- 3.3.3 hp-toolbox sends an error, "Unable to communicate with device"
- 3.3.4 CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer
- 3.3.5 Printing fails with unauthorised error
- 3.3.6 Print button greyed-out in GNOME print dialogs
- 3.3.7 Unknown supported format: application/postscript
- 3.3.8 Finding URIs for Windows Print Servers
- 3.3.9 Print-Job client-error-document-format-not-supported
- 4 Appendix
- 5 Resources
1 Installing
These packages are needed:
# pacman -S cups ghostscript gsfonts
- cups - The actual CUPS software
- 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 thread at launchpad/hplip for more information.
Start and enable cups.service.
Alternatively, it is possible to control CUPS activation with a socket. Start and enable cups.socket, while cups.service is disabled. As a result, systemd will listen to the appropriate sockets and start cups.service when requested by a program.
1.1 Printer driver
Here are some of the driver packages. Choosing the right driver depends on the printer:
- CUPS Native Drivers - CUPS already includes a few printer drivers. In that case you can just select it in the list and your printer will likely work.
- '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
- {{Pkg|foomatic-db} and foomatic-db-engine - 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!".
- 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.
- splix - Samsung drivers for SPL (Samsung Printer Language) printers
- 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.
# pacman -S gutenprint foomatic-db foomatic-db-engine \ hplip splix cups-pdf
1.1.1 Download printer PPD
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.
Here is an explanation of what a PPD file is from the Linux PrintiOpang website:
- "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:
- visit the OpenPrinting database and select the manufacturer and model of the printer
- visit the manufacturer's site and search for GNU/Linux drivers
1.2 Driverless installation
It is possible to use CUPS with modern printers over the network without the need to install specific drivers, thanks to IPP. This is also the preferred options as CUPS shifts away from PPD-base setup (refer to CUPS man page).
In order to do that, .local hostname resolution must be setup first. Avahi is used to provide service discovery on local networks through mDNS/DNS-SD.
Install the avahi package.
Install the optional dependency nss-mdns to enable .local hostname resolution with Avahi.
Then, edit the configuration file by adding mdns_minimal [NOTFOUND=return] to the host line, before resolve as below:/etc/nsswitch.conf
host: … mdns_minimal [NOTFOUND=return] resolve …
Finally start and enable avahi-daemon.service.
1.3 Checking connection
1.3.1 USB
To see if your USB printer is detected,
lsusb
(...) Bus 001 Device 007: ID 03f0:1004 Hewlett-Packard DeskJet 970c/970cse
1.3.2 Network
Avahi can be used to discover services on the local networks with the avahi-browse command.
If a dbus error is displayed, installing the optional dependency python-dbus should solve the issue.
2 Configuring
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 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.
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.
2.1 Kernel modules
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 tail command (described below) to see if the printer has already been detected. The lsmod utility can also be used to see what modules have been loaded.
2.1.1 Parallel port printers
If planning on using a parallel port printer, note that 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:
# tail /var/log/messages.log
It should display something like this:
lp0: using parport0 (polling).
2.1.2 Auto-loading
It's 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 /etc/rc.conf and add the appropriate module to the MODULES=()
line. Here is an example:
MODULES=(!usbserial scsi_mod sd_mod snd-ymfpci snd-pcm-oss lp parport parport_pc ide-scsi)
2.2 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 /etc/hosts).
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, chose the appropriate drivers and the configuration is complete.
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.
2.2.1 CUPS administration
A user-name and password will be required when administrating 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 /etc/cups/cupsd.conf in the line of SystemGroup).
If the root account has been locked, it is not possible to log in the CUPS administration interface with the default user-name and password. In this case, it may be needed to change the default SystemGroup in cupsd.conf and read this post.
2.2.2 Remote access to web interface
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 /etc/cups/cupsd.conf file. Replace the line:
Listen localhost:631
with
port 631
so that CUPS listens to incoming requests.
There are three levels of access that can be granted:
<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 Allow statement to that level's section. An Allow statement can take one or more of the forms listed below:
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 /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 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:
DefaultEncryption Never
This should avoid the error: 426 - Upgrade Required when using the CUPS web interface from a remote machine.
3 Troubleshooting
The best way to get printing working is to set 'LogLevel' in /etc/cups/cupsd.conf to:
LogLevel debug
And then viewing the output from /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:
- /var/log/cups/page_log - Echoes a new entry each time a print is successful
- /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 error_log to get a more detailed and correct image of the printing process.
3.1 Problems resulting from upgrades
Issues that appeared after CUPS and related program packages underwent a version increment
3.1.1 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" my result from trying to manage CUPS via localhost:631, for example.
To use the new configuration, copy /etc/cups/cupsd.conf.default to /etc/cups/cupsd.conf (backup the old the configuration if needed):
# cp /etc/cups/cupsd.conf.default /etc/cups/cupsd.conf
and restart CUPS to employ the new settings.
3.1.2 Error with gnutls
If receiving errors such as:
/usr/sbin/cupsd: error while loading shared libraries: libgnutls.so.13: cannot open shared object file: No such file or directory
gnutls may be in need of updating:
# pacman -S gnutls
After updating, there may be a file named cupsd.conf.pacnew in /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.
3.1.3 All jobs are "stopped"
If all jobs sent to the printer become "stopped", delete the printer and add it again. Using the 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.
3.1.4 The PPD version is not compatible with gutenprint
Run:
# /usr/sbin/cups-genppdupdate
And restart CUPS (as pointed out in gutenprint's post-install message)
3.2 USB printers under CUPS 1.4.x
New CUPS 1.4.x introduces many changes:
3.2.1 Configuration file
The syntax of the configuration file cupsd.conf changed. Start with a new cupsd.conf file based on /etc/cups/cupsd.conf.default.
3.2.2 Blacklisting usblp
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.
blacklist usblp
3.2.3 Device node permissions
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:
# hplip and cups 1.4+ use raw USB devices, so permissions should be similar to # the ones from the old usblp kernel module 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.
3.2.3.1 Device node permission troubleshooting
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
cat /etc/udev/rules.d/10-usbprinter.rules ATTR{idVendor}=="04b8", ATTR{idProduct}=="0841", MODE:="0660", GROUP:="lp"
Note that idVendor and idProduct are from the lsusb listing above.
3.2.3.2 Loading firmware
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.
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.
Locate the line matching your printer in /etc/udev/rules.d/11-hpj10xx.rules:
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"
3.3 Other
3.3.1 CUPS permission errors
- 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:
# ls /dev/usb/ lp0 # chgrp lp /dev/usb/lp0
3.3.2 HPLIP printer sends "/usr/lib/cups/backend/hp failed" error
Make sure dbus is installed and running, e.g. check DAEMONS in /etc/rc.conf or run ls /var/run/daemons.
The avahi-daemon might be required if this error persists and the dbus is already running.
3.3.3 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, "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
3.3.4 CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer
If receiving any of the following error messages in /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 the packages mentioned above, net-snmp is also needed. See this forum post.
# pacman -S hplip
3.3.5 Printing fails with unauthorised error
If the user has been added to the lp group, and allowed to print (set in cups.conf), then the problem lies in /etc/cups/printers.conf. This line could be the culprit:
AuthInfoRequired negotiate
Comment it out and restart CUPS.
3.3.6 Print button greyed-out in GNOME print dialogs
Be sure the package: libgnomeprint is installed
Edit /etc/cups/cupsd.conf and add
# HostNameLookups Double
Restart CUPS:
# /etc/rc.d/cups restart
3.3.7 Unknown supported format: application/postscript
Comment the lines:
application/octet-stream application/vnd.cups-raw 0 -
from /etc/cups/mime.convs, and:
application/octet-stream
in /etc/cups/mime.types.
3.3.8 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:
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.
3.3.9 Print-Job client-error-document-format-not-supported
Try installing the foomatic packages and use a foomatic driver.
4 Appendix
4.1 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 /etc/cups/cupsd.conf
SystemGroup sys root <insert here>
- 3. Restart cups, log out and in again (or restart computer)
# 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.
4.2 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 /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 this link.
4.2.1 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".
4.2.1.1 Configuring CUPS-PDF virtual printer
- Set up the cups daemon using the instructions on this page.
- Install 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...