Printing

This document Article description::covers the installation and maintenance of printers using CUPS and Samba. It covers local installation and networked installations and contains instructions on using shared printers from other operating systems. For information about using the or  commands for printing documents see CUPS' excellent upstream documentation.

Use the right tools
Linux has great support for printers; the right tool for the job is called CUPS (Common Unix Printing System). Since the beginning of the project, back in 1999, the installation and maintenance of CUPS has improved dramatically.

In this document we will cover how to use CUPS to setup a local or networked printer. It will not go in too much detail since the project has great documentation available for advanced usage.

Kernel
When a user desires to install a printer on a system the first step is knowing how the printer will be attached to the system. Is it through a local port like LPT or USB, or is it networked? If it is networked, does it use the Internet Printing Protocol (IPP) or the Microsoft Windows CIFS protocol (Microsoft Windows Sharing)?

The next few sections explain what minimal kernel configuration is needed to get a printer connected in Gentoo. Of course, this depends on how the printer is going to be attached to the system, so for convenience the instructions have been separated.

Navigate to and run  to enter the kernel configuration. If was used to configure the kernel, these steps should still be performed to make sure nothing was missed. Do not rely on genkernel to configure everything in the system automatically; printing is an area configuration settings are difficult to automatically set.

In the next configuration examples, the necessary support will be added into the kernel, not as modules. Building the kernel this way is not mandatory; if desired modular support can be easily added, just be sure to remember to load the appropriate modules!

Now go to the appropriate section to configure (or check) the kernel.

Locally attached printer (LPT)
The LPT port is generally used to identify the parallel printer port. You need to enable parallel port support first, then PC-style parallel port support (unless using a SPARC system) after which you enable parallel printer support.

That's it! Exit the kernel configuration and rebuild the kernel.

Now continue with CUPS.

Locally attached printer (USB)
USB printing is supported by CUPS with the USB USE flag enabled. This uses the libusb library for user space USB support.

Some older software titles might still require the in-kernel USB printer support. If built as a module, this module would be called :

However, using the in-kernel USB printer support is considered obsolete. Only pursue this when needed.

Remotely attached printer (IPP and LPD)
To be able to connect to a remotely attached printer through the Internet Printing Protocol or the Line Printer Daemon protocol the kernel needs to have networking support. Assuming the kernel has that already, continue with CUPS.

Remotely attached printer (CIFS)
The kernel must support CIFS:

After configuration for CIFS is complete, exit the kernel configuration and rebuild the kernel. Do not forget to copy the new kernel image to the location (and don't forget to mount  if needed) and update the boot loader configuration prior to rebooting the system. Note the root commands in the LPT Printer Configuration step above for how to perform these steps.

Now continue with the next steps in the CUPS installation process.

USE flags
Some packages are aware of the USE flag. CUPS has a few optional features that might be of interest. To enable or disable those features, use the USE flags associated with them.

Check the current USE flag settings. To deviate from the current USE settings for CUPS alone, add the appropriate USE flags to file.

Emerge
When happy with the result, ask Portage to install CUPS:

Samba
To enable SAMBA support, needs to be installed with CUPS support. Update the file or directory to enable the   USE flag:

Then (re)install Samba:

Avahi
CUPS uses Avahi internally when built with the  USE flag to scan for printers on the local network. To use Avahi hostnames to connect to networked printers, set up .local hostname resolution and restart the CUPS service. CUPS and cups-filters need to be built with the  USE flag as well. Use the command for listing available printers.

Printing group
Any user that needs to print should be added to the group:

In order to be able to add printers and edit them via CUPS's web interface, any system user that is allowed to edit these settings should be in the group:

OpenRC
If the printer is attached to the system locally, and the printer needs to be available every boot, the CUPS daemon will need to load automatically on start-up. Make sure the printer is attached and powered on before the CUPS daemon is started.

systemd
To start the CUPS daemon immediately and to make it start when the system boots, issue:

HTTP interface
Once the service is started, printers can be added by authenticated users. root is available by default and any member of the group. Open up the following URL in a web browser:

http://localhost:631/

Files
The default CUPS server configuration located in is sufficient for most users. However, some users might need to make changes to the CUPS configuration.

In the next section covers a few changes that are often needed:


 * Allow other systems to use the printer attached to this Linux workstation.
 * Grant access to the CUPS administration from remote systems.
 * Configure CUPS to support Windows PCL drivers. This is advised for Windows systems to be able to use a SAMBA-shared printer since most Windows drivers are PCL drivers.
 * Configure this system to use a printer attached to another system (not Windows share).

Remote printer access
For other systems to use the printer through IPP, explicit access to the printer must be granted in the file. To share the printer using SAMBA, this change is not needed.

Open up in a favorite text editor and add in an   line for the system(s) that should be able to reach to the printer. In the next example, access is granted to the printer from localhost and from any system whose IP address starts with.

This line broadcasts browsing information to the clients on the network; it will let network users know when the printer is available:

The port CUPS listens to will also need to be specified so that it will respond to printing requests from other machines on the network:

The CUPS server reject a hostname or server alias in the HTTP request with "Bad request" message. It works with IP-addresses by default. So if you want to print or browse CUPS interface by using a hostname or domain, add the ServerAlias parameter:

CUPS remote administration
If remote administration is needed, then access to the CUPS administration will need to be granted from more systems than the localhost. Edit the file and have explicit access granted to each system that requires access. For instance, to grant access to a system with an IP address of 192.168.0.3:

Do not forget to restart the CUPS daemon after making changes to by issuing the  command (for OpenRC users) or  (for systemd users).

Enable support for Windows PCL drivers
PCL drivers send raw data to the print server. To enable raw printing on CUPS, edit and uncomment the   line if it is not already uncommented. Then edit and do the same, if it is not already uncommented.

Do not forget to restart the CUPS daemon after making these changes by running (for OpenRC users) or  (for systemd users).

Setting up a remote printer
If the printers are attached to a remote CUPS-powered server the system can be easily configured to use the remote printer by modifying the file.

Assuming the printer is attached to a system called, open up  with a favorite text editor and set the   directive:

The remote system will have a default printer setting which will be used. To change the default printer, use the command.

First list the available printers:

Set the HP LaserJet 5P as the default printer:

Introduction
If the printer to be configured is remotely available through a different print server (running CUPS) then the following instructions are not needed. Instead, read Setting up a Remote Printer.

Detecting the printer
If a USB printer or parallel port printer was powered on when the Linux system booted, it might be possible to retrieve information from the kernel stating successful detection of the printer. This is merely an indication of print detection and not a requirement.

For a USB connected printer:

Listing available drivers
To list all available drivers, execute the following command:

is not chatty and can be a little tricky to use. If any issue arises, see for more information.

Installing the printer
To have the printer installed on the system, fire up a browser and point it to http://localhost:631. The CUPS web interface should be displayed from which all administrative tasks can be performed.

Go to and enter the root login and password information of the box. Then, when the administrative interface has been reached, click on. A new screen will be displayed allowing the following information to be entered:


 * The spooler name, a short but descriptive name used on the system to identify the printer. This name should not contain spaces or any special characters. For instance, for the HP LaserJet 5P could be titled.
 * The location, a description where the printer is physically located (for instance "bedroom", or "in the kitchen right next to the dish washer", etc.). This is to aid in maintaining several printers.
 * The description, a full description of the printer. A common use is the full printer name (like "HP LaserJet 5P").

The next screen requests the device the printer listens to. The choice of several devices will be presented. The next table covers a few possible devices, but the list is not exhaustive.

If installing a remote printer, the URL to the printer will be queried:


 * An LPD printer server requires a  syntax.
 * An HP JetDirect printer requires a  syntax.
 * An IPP printer requires a  or   syntax.

Next, select the printer manufacturer in the adjoining screen along with the model type and number in the subsequent screen. For many printers multiple drivers will be available. Select one now or search on OpenPrinting Printer List for a good driver. Drivers are easily able to be changed later.

Once the driver is selected, CUPS will inform that the printer has been added successfully to the system. Navigate to the printer management page on the administration interface and select to change the printer's settings (resolution, page format, ...).

Testing and reconfiguring the printer
To verify if the printer is working correctly, go to the printer administration page, select the printer and click on.

If the printer does not seem to work correctly, click on to reconfigure the printer. The same screens as during the first installation will appear but the defaults will now be the current configuration.

If the printer does not function, clues may be found by looking at the CUPS error log located at. In the next example a permission error is discovered, probably due to a wrong setting in the  file.

Installing the best driver
Many printer drivers exist; to find out which one has the best performance the job, visit the OpenPrinting Printer List. Select the brand and type/model of the printer to find out what driver the site recommends. For instance, for the HP LaserJet 5P, the site recommends the  driver.

Download the PPD file from the site and place it in then run  (for OpenRC users) or  (for systemd users) as root. This will make the driver available through the CUPS web interface. Now reconfigure the printer as described above.

Enabling job accounting in for Xerox printers
High-end Xerox printers (if you see a gray, cabinet sized device, it's it) use XCPT PDL, and XML based, and poorly documented XPIF ticketing instruction format.

XCPT filter in Cups never made it to a release grade, and the work on it was eventually dropped as I remember. This way all XPIF have to be input into PPD manually. Luckily, it's largely a direct copy of IPP, using XML syntax! After peeking into docs available online, we can craft an arbitrary XPIF command using corresponding IPP attributes.

If you need XPIF solely for ticketing/accounting, you can drop the following into any PPD. It will draw a dropdown box in any printing ui compliant with CUPS PPD extensions for you to enter your id.

The long term solution would still be for Xerox to fully publish XPIF, and XCPT specifications, to allow for a proper XPIF cups filter to be developed.

Introduction
Some printers require specific drivers or provide additional features that are not enabled through the regular configuration process (described above). This chapter will discuss a selection of printers and how they are made to work with Gentoo Linux.

Gutenprint driver
The Gutenprint drivers are high-quality, open source printer drivers for various Canon, Epson, HP, Lexmark, Sony, Olympus and PCL printers supporting CUPS. They also support ghostscript, The Gimp, and other applications.

Gentoo's Portage tree contains an ebuild for the gutenprint drivers. Run to install them. Note the ebuild requests to quite a few USE flags. At minimum  and   must enabled for gutenprint drivers to work properly.

When the emerge process has finished, the gutenprint drivers will be available through the CUPS web interface.

HPLIP driver
See HPLIP Driver.

PNM2PPA driver
PPA is an HP technology that focuses on sending low-level processing to the system instead of the printer which makes the printer cheaper but more resource consuming.

If the OpenPrinting site informs the pnm2ppa driver is the best option, then the filter will need to be installed on the system:

Once installed, download the PPD file for the printer OpenPrinting and put it in the folder. Then configure the printer using the steps explained above.

SpliX driver
SpliX is a set of CUPS printer drivers for SPL (Samsung Printer Language) printers. While SpliX drivers are available through OpenPrinting as well, the package allows for quick portage-managed installation of these drivers. To install, run:

and restart.

Brother printer drivers
See Brother networked printer.

Canon printer drivers
See the specific pages:
 * Canon CAPT drivers
 * Canon Pixma drivers

Configuring a Windows client for IPP
Microsoft Windows supports IPP. To install a printer on Windows that is attached to a Linux box, fire up the wizard and select. When asked for the URI, use the  syntax.

Configuring a Windows client for a Samba shared printer
To share the printer on the CIFS network SAMBA must be installed and configured correctly. Doing this is beyond the scope of this article, however a quick configuration of SAMBA for shared printers will be covered.

Open with a favorite text editor and add a   section to it:

Navigate to the top of the file until inside the   section. Locate the  and   settings and set each of them to   (see the example below):

Make sure to enable Windows PCL support in CUPS. Then, restart the smb service to have the changes take effect.

Configuring a Linux client for a Windows print server
First make sure the printer is shared on Windows systems and that has been emerged with the   USE flag enabled (as instructed above).

To find the desired printer's URI, run the following command, substituting  with the computer that is to probe for samba-shared printers:

In the CUPS web interface, configure the printer as previously described. Notice CUPS has added another driver called. Select it and use the  or   syntax for the URI.

Introduction
Many tools exist to help configure a printer, use additional printing filters, add features to printing capabilities, etc. This chapter will list a few of them. Be aware the list is not exhaustive and not meant to discuss each tool in great detail.

Gtk-LP - A GTK-powered printer configuration tool
With, the installation, modification and configuration of a printer can be performed from a stand-alone GTK application. It uses CUPS and provides all standard CUPS capabilities. It is definitely worth checking out if the CUPS Web interface is disliked or if a stand-alone application for day-to-day printing routines is desired.

Install via:

Printer configuration tool for KDE Plasma
KDE Plasma also has a printer config tool called. It works with CUPS and provides a user-friendly interface to configure printers. Install it as follows:

USE flags
Packages that are currently installed with the  USE flag must be modified. Search through to see if any packages explicitly have the   flag and remove it.

Next, it may be necessary to remove the  value from 's USE variable if it had been previously set.

Unmerge
Finally, clean the system of any packages that are no longer needed as a result of CUPS being removed.

Debugging
See archlinux wiki

Error: Unable to convert file 0 to printable format
While having printing troubles and shows this message:

Re-emerge with the   USE flag. You can either add  to the system USE flags in  or enable it only for ghostscript-gpl as shown:

Then run. When it has finished compiling, be sure to restart afterward.

When using OpenRC:

When using systemd:

USB Printer is not detected
Assuming that cups is built with the  USE flag, verify that the printer's character device has the correct permissions. For example:

There should be a character device for this printer at.

In this example, over-zealously modified the permissions. This is. Lets try fixing them:

Now we should see:

The printer likely is detected now. You should be able to add it, configure it (provided that you have a working driver) and print a test page. This implies a permissions problem. Assuming that your system uses udev/eudev for managing its /dev directory, you can make this change permanent by making a udev file:

Our device is "ID 04e8:3297" according to the earlier lsusb output. We split that into idVendor and idProduct as demonstrated in the example. Now udev should ensure that the correct permissions are set at every boot and at every hotplug.

External resources

 * Using Network Printers - Documentation at CUPS.org.
 * Command-Line Printing and Options - Documentation at CUPS.org.