Important: You are required to change your passwords used for Gentoo services and set an email address for your Wiki account if you haven't done so. See the full announcement and Wiki email policy change for more information.


From Gentoo Wiki
Jump to: navigation, search
Other languages:English 100% • ‎русский 100%

This document covers the installation and maintenance of printers using CUPS and Samba. It covers local installation and networked installations and you'll also find instructions on using shared printers from other operating systems.

Printing and Gentoo Linux

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. We will not go in too much detail since the project has great documentation available for advanced usage.

Configure your Kernel


When you want to install a printer on your system you need to know how your printer will be attached to your system. Is it through a local port like LPT or USB, or is it networked? And if it is, does it use the Internet Printing Protocol (IPP) or is it through the Microsoft Windows SMB-CIFS protocol (Microsoft Windows Sharing)?

The next few sections explain what minimal kernel configuration you need. Of course, this depends on how your printer is going to be attached to your system, so for your convenience we have separated the instructions.

So navigate to /usr/src/linux and run make menuconfig to enter the kernel configuration. If you used genkernel to configure your kernel, you should still perform these steps just to make sure nothing was missed out.

In the next configuration examples, we will add the necessary support in the kernel, not as modules. This is not mandatory; if you want you can easily use modular support. Don't forget to load the appropriate modules afterwards.

Now go to the appropriate section to configure (or check) your 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 you are a SPARC user) after which you enable parallel printer support.

Kernel configurationParallel Port Printer Configuration

Device Drivers -->
  <*> Parallel port support
  <*>   PC-style hardware
Device Drivers -->
  Character Devices -->
    <*> Parallel printer support
       [*]      IEEE 1284 transfer modes)
Some users might need to enable other options in the Parallel port support section. Check the kernel configuration Help function for more information.

That's it; quit the kernel configuration and rebuild your kernel. Don't forget to copy the new kernel image to the /boot location (and don't forget to mount /boot if needed) and update your boot loader configuration prior to rebooting your system.

Now continue with CUPS.

Locally Attached Printer (USB)

To enable USB printing, you just need USB support in your kernel:

Kernel configurationUSB Port Printer Configuration

Device Drivers -->
  USB Support -->
    <*> Support for Host-side USB
    --- USB Host Controller Drivers
    (Select the HCD that your system uses. If you do not know which one
     to select, run "lspci -v | grep HCI" from another terminal)
    <*> EHCI HCD (USB 2.0) support ( or )
    <*> OHCI HCD support           ( or )
    <*> UHCI HCD (most Intel and VIA) support

That's it; quit the kernel configuration and rebuild your kernel. Don't forget to copy the new kernel image to the /boot location (and don't forget to mount /boot if needed) and update your boot loader configuration prior to rebooting your system.

Now continue with CUPS.

Remotely Attached Printer (IPP)

To be able to connect to a remotely attached printer through the Internet Printing Protocol your kernel just needs to have networking support. Assuming your kernel has that already, continue with CUPS.

Remotely Attached Printer (SMB-CIFS)

Your kernel must support SMB CIFS:

Kernel configurationSMB-CIFS Printer Configuration

File systems -->
  Network File Systems -->
    <*> SMB file system support (to mount Windows shares etc.)
    <*> CIFS support (advanced network file system for Samba, Windows and other CIFS compliant servers)

That's it; quit the kernel configuration and rebuild your kernel. Don't forget to copy the new kernel image to the /boot location (and don't forget to mount /boot if needed) and update your boot loader configuration prior to rebooting your system.

Now continue with CUPS.

Installing and Configuring CUPS


Installing CUPS with Gentoo is a breeze. CUPS has a few optional features that might interest you. To enable or disable those features, use the USE flags associated with them.

USE flag Impact on CUPS
dbus Adds support for the dbus system message bus.
jpeg Adds support for printing JPEG images.
nls Enable National Language Support. With nls in place, CUPS is able to deliver localized feedback so you can hopefully enjoy CUPS in your native language.
pam If you need print job authentication through the Pluggable Authentication Modules, this will activate PAM support for CUPS.
php Adds support for php scripting.
png Adds support for printing PNG images.
ppds Adds support for automatically generated ppd (printing driver) files. See #Installing_the_Best_Driver .
samba If you want to be able to share locally attached printers to Windows systems on your network using the SMB-CIFS protocol, or you want to be able to use shared printers from Windows systems, you need SAMBA support.
slp In a managed environment the printer might be made available as a service to others. With the Service Location Protocol you can easily find and configure a service on your system. Enable this USE flag if your printer is available as a service or should be made available as one.
ssl If you want remote authentication and/or privacy, you need support for the Secure Socket Layer, allowing for encrypted printing sessions. Support for SSL must be available on all participating systems in your network.
tiff Adds support for printing TIFF images.
X Allows you to use your desktop menu to load the CUPS configuration webpage into your preferred browser.

Check the current USE settings. If you want to deviate from your current USE settings for CUPS alone, add the appropriate USE flags to /etc/portage/package.use .

root # emerge -pv cups
[ebuild N     ] net-print/cups-1.2.6  "X dbus jpeg nls pam png ppds ssl -php -samba -slp -tiff" 0 kB

For instance, to enable SAMBA support for CUPS:


net-print/cups samba

If you are happy with the result, have Portage install CUPS.

root # emerge cups
Any users that need to print should be added to the lp group. Add them by running (as root) gpasswd -a username lp .

If the printer is attached to your system locally, you need to load CUPS automatically on start-up. Make sure your printer is attached and powered on before you start CUPS.

root # /etc/init.d/cupsd start
root #
rc-update add cupsd default


The default CUPS server configuration in /etc/cups/cupsd.conf is sufficient for most users. However, several users might need some changes to the CUPS configuration.

In the next sections we cover a few changes that are often needed:

  • we allow other systems to use the printer attached to this Linux workstation.
  • we grant access to the CUPS administration from remote systems
  • we configure CUPS to support Windows PCL drivers. This is advised if you want Windows systems to be able to use a Samba-shared printer as most Windows drivers are PCL drivers.
  • we configure this system to use a printer attached to another system (not Windows share).

Remote Printer Access

If you want other systems to use your printer through IPP you need to explicitly grant access to the printer in /etc/cups/cupsd.conf . If you want to share your printer using SAMBA, this change is not needed.

Open up /etc/cups/cupsd.conf in your favorite editor and add in an Allow line for the system(s) that should be able to reach to your printer. In the next example, we grant access to the printer from localhost and from any system whose IP address starts with 192.168.0 .

File/etc/cups/cupsd.confAllowing remote access to the printer

<Location />
  Order allow,deny
  Allow localhost
  Allow from 192.168.0.*

This broadcasts browsing information to the clients on the network. This is so that they know the printer is available:

File/etc/cups/cupsd.confBroadcast info

BrowseAddress 192.168.0.*:631

Also, you will need to specify which port CUPS listens to, so that it will respond to printing requests from other machines on your network.

File/etc/cups/cupsd.confPort configuration

Listen *:631
#Listen localhost:631
If you are still using CUPS 1.1 (which is now deprecated), then you will need to use a different syntax for remote printing requests:
CodeDeprecated CUPS 1.1 configuration

Port 631
(Make sure the next two lines are commented out)
#Listen localhost:631

CUPS Remote Administration

If you are interested in remote administration, you need to grant access from other systems than just localhost to the CUPS administration. Edit /etc/cups/cupsd.conf and have it explicitly grant access to the systems you want. For instance, to grant access to the system with IP address of

File/etc/cups/cupsd.confAllowing remote access

<Location /admin>
  Encryption Required
  Order allow,deny
  Allow localhost

Do not forget to restart CUPS after making changes to /etc/cups/cupsd.conf by running /etc/init.d/cupsd restart .

Enable Support for Windows PCL Drivers

PCL drivers send raw data to the print server. To enable raw printing on CUPS, you need to edit /usr/share/cups/mime/mime.types and uncomment the line application/octet-stream if it is not already uncommented. Then you need to edit /usr/share/cups/mime/mime.convs and do the same, if it is not already uncommented.

File/usr/share/cups/mime/mime.typesEnable support for raw printing


application/octet-stream     application/vnd.cups-raw    0    -

Do not forget to restart CUPS after making these changes by running /etc/init.d/cupsd restart .

Setting Up a Remote Printer

If the printers are attached to a remote CUPS-powered server you can easily set up your system to use the remote printer by changing the /etc/cups/client.conf file.

Assuming the printer is attached to a system called printserver.mydomain , open up /etc/cups/client.conf with your favorite editor and set the ServerName directive:


# (Substitute printserver.mydomain with your print server name)
ServerName printserver.mydomain

The remote system will have a default printer setting which you will be using. If you want to change the default printer, use lpoptions :

First list the available printers:

root # lpstat -a
hpljet5p accepting requests since Jan 01 00:00
hpdjet510 accepting requests since Jan 01 00:00

Set the HP LaserJet 5P as the default printer:

root # lpoptions -d hpljet5p

Configuring a Printer


If the printer you want to configure is remotely available through a different print server (running CUPS) you do not need to follow these instructions. Instead, read #Setting_Up_a_Remote_Printer .

Detecting the Printer

If you have a USB printer or your parallel port printer was powered on when you booted your Linux system, you might be able to retrieve information from the kernel stating that it has successfully detected your printer. However this is merely an indication and not a requirement.

user $ dmesg | grep -i print
parport0: Printer, Hewlett-Packard HP LaserJet 2100 Series

For a USB printer:

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

Installing the Printer

To have the printer installed on your system, fire up your browser and have it point to http://localhost:631 . You will be greeted by the CUPS web interface from which you can perform all administrative tasks.

If you use an HTTPS connection to CUPS, the first time you access the interface it may take a very long time before the site comes up. This is because the first request triggers the generation of the CUPS SSL certificates which can be a very time-consuming job.

Go to Administration and enter your root login and password information at the box. Then, when you have reached the administrative interface, click on Add Printer . You will be greeted by a new screen allowing you to enter the following information:

  • The spooler name , a short but descriptive name used on your system to identify the printer. This name should not contain spaces or any special characters. For instance, for the HP LaserJet 5P you could say hpljet5p .
  • The location , a description where the printer is physically located (for instance in your room, or in the kitchen right next to your dish washer, ...). This is to help maintaining several printers.
  • The description in which you should place a full description of the printer. A common use is the full printer name (like "HP LaserJet 5P").

The next screen asks you for the device where the printer listens to. You will have the choice of several devices. The next table covers a few possible devices, but the list is not exhaustive.

Device Description
AppSocket/HP JetDirect This special device allows for network printers to be accessible through a HP JetDirect socket. Only specific printers support this.
Internet Printing Protocol (IPP or HTTP) Use this to reach your remote printer through the IPP protocol either directly (IPP) or through HTTP.
LPD/LPR Host or Printer Select this if the printer is remote and attached to a LPD/LPR server.
Parallel Port #1 Select this when the printer is locally attached to your parallel port (LPT). When the printer is automatically detected its name will be appended to the device as well.
USB Printer #1 Select this when the printer is locally attached to a USB port. The printer name should automatically be appended to the device name.

If you are installing a remote printer, you will be asked for the URI to the printer:

  • An LPD printer server requires a lpd://hostname/queue syntax
  • An HP JetDirect printer requires a socket://hostname syntax
  • An IPP printer requires a ipp://hostname/printers/printername or http://hostname:631/printers/printername syntax.

Next, select the printer manufacturer in the adjoining screen and the model type and number in the subsequent one. For many printers you will find multiple drivers. You can either select one now or search on's Printer List for a good driver. You can change drivers easily later on.

Once the driver is selected, CUPS will inform you that the printer has been added successfully to the system. You can now go to the printer management page on the administration interface and select Configure Printer to change the printer settings (resolution, page format, ...).

Testing and Reconfiguring the Printer

To verify if the printer is working correctly, go to the printer administration page, select your printer and click on Print Test Page .

If the printer does not seem to work correctly, click on Modify Printer to reconfigure the printer. You will be greeted with the same screens as during the first installation but the defaults will now be your current configuration.

If you have no idea why your printer does not function, you might get a clue by looking at /var/log/cups/error_log . In the next example we find out that there is a permission error, probably due to a wrong Allow setting in /etc/cups/cupsd.conf .

root # tail /var/log/cups/error_log
E [11/Jun/2005:10:23:28 +0200] [Job 102] Unable to get printer status (client-error-forbidden)!

Installing the Best Driver

Many printer drivers exist; to find out which one has the best performance for your printer, visit the LinuxPrinting Printer List . Select your brand and type to find out what driver the site recommends. For instance, for the HP LaserJet 5P, the site recommends the ljet4 driver.

Download the PPD file from the site and place it in /usr/share/cups/model , then run /etc/init.d/cupsd restart as root. This will make the driver available through the CUPS web interface. Now reconfigure your printer as described above.

Using Special Printer Drivers


Some printers require specific drivers or provide additional features that are not enabled through the regular configuration process as 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, ghostscript, The Gimp and other applications.

Gentoo's Portage Tree contains an ebuild for the gutenprint drivers. Just use emerge to install them. Note that the ebuild listens to quite a few USE flags (such as cups and ppds ). You must have enabled at least these two flags!

root # emerge --ask gutenprint

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 to the printer which makes the printer cheaper but more resource consuming.

If the LinuxPrinting site informs you that the pnm2ppa driver is your best option, you need to install the pnm2ppa filter on your system:

root # emerge --ask pnm2ppa

Once installed, download the PPD file for your printer from the LinuxPrinting site and put it in /usr/share/cups/model . Next, configure your printer using the steps explained above.

Printing From and To Microsoft Windows

You should read our Samba/CUPS Guide for more detailed information on setting up CUPS with Samba.

Configuring a Windows Client for IPP

Microsoft Windows supports IPP (Windows 9x and ME users need to install it separately). To install a printer that is attached to your Linux box on Windows, fire up the Add Printer wizard and select Network Printer . When you are asked for the URI, use the http://hostname:631/printers/queue syntax.

Configuring a Windows Client for a Samba Shared Printer

To share the printer on the SMB-CIFS network, you must have SAMBA installed and configured correctly. How to do this is beyond the scope of this document, but we will quickly deal with the configuration of SAMBA for shared printers.

Open /etc/samba/smb.conf with your favorite editor and add a [printers] section to it:

CodeAdding a [printers] section

  comment      = All printers
  path         = /var/spool/samba
  browseable   = no
  guest ok     = no
  writable     = no
  printable    = yes
  public       = yes
  printer name = hpljet5p

Now navigate to the top of the smb.conf file until you are inside the [global] section. Then locate the printcap name and printing settings and set each of them to cups :

CodeChanging the [global] section

  printcap name = cups
  printing      = cups

Make sure you enabled the #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 of all, make sure that the printer is shared on your Windows system.

Next, in the CUPS web interface, configure your printer as described previously. You will notice that CUPS has added another driver called Windows Printer via SAMBA . Select it and use the smb://username:password@workgroup/server/printername or smb://server/printername syntax for the URI.

Printing-related Applications


Many tools exist that help you configure a printer, use additional printing filters, add features to your printing capabilities, etc. This chapter lists a few of them. The list is not exhaustive and not meant to discuss each tool in great detail.

Gtk-LP - A Gtk-powered Printer Configuration Tool

With Gtk-LP you can install, modify and configure your printer from a stand-alone Gtk application. It uses CUPS and provides all standard CUPS capabilities as well. Definitely worth checking out if you dislike the CUPS Web interface or want a stand-alone application for your day-to-day printing routines.

To install it, emerge gtklp :

root # emerge --ask gtklp


Error: Unable to convert file 0 to printable format

If you are having printing troubles and /var/log/cups/error_log shows this message:

CodeError log

Unable to convert file 0 to printable format

You need to re-emerge ghostscript-gpl with the cups USE flag. You can either add cups to your USE flags in /etc/portage/make.conf , or you can enable it only for ghostscript-gpl as shown:

root # echo "app-text/ghostscript-gpl cups" >> /etc/portage/package.use

Then emerge ghostscript-gpl. When it has finished compiling, be sure to restart cupsd afterward:

root # /etc/init.d/cupsd restart


We would like to thank the following authors and editors for their contributions to this guide:

  • swift
  • nightmorph