Gentoo Logo
Gentoo Logo Side

Gentoo Printing Guide


1. Installing CUPS and foomatic

Setting up printing in Gentoo Linux is a relatively painless task, thanks to some great programs such as CUPS (the Common Unix Printing System) and foomatic. Both of these programs are currently in the Portage tree, and they are very easy to set up for the end user.

Please be aware the cups is cross-desktop, i.e. you can follow these directions to get printing working under GNOME or KDE. There are other options, such as KDE's print setup, but I believe that CUPS is the easiest to setup, and the most scalable.

Before emerging CUPS, it is a good idea to add the necessary USE flags to /etc/make.conf.

Code Listing 1.1: Editing /etc/make.conf

add cups, foomaticdb, ppds and usb (if you are using a USB printer connection) to your existing USE var list. 
USE="cups foomaticdb ppds usb other_var1 other_var2"

For more information on USE variables, please see the USE flags chapter in the Gentoo Handbook.

Code Listing 1.2: Emerging necessary packages

# emerge cups
# emerge foomatic 

2. Setting up Kernel Modules


Now that the necessary packages are installed, it is time to install the printer.

Depending on what type of printer connection you will be using, it will be necessary to enable either parallel port or USB port printer connections in the kernel.

Note: This is only needed for local printing, if you want to print via samba, skip this section.

Note: If you are not sure on how to compile the kernel, the specific instructions can be found in the Kernel Howto (currently down for review). Make sure you find out how to compile and install new modules without having to recompile your kernel or restart your computer. It's a real timesaver.

USB Modules 

To enable USB printer support, go to USB support and enable Support for USB and USB Printer support. Enabling them both as modules will install usbcore.o and printer.o in your modules directory. I suggest using modules because you won't have to restart your computer. Users of a 2.6 kernel will find these options under Device Drivers.

After the kernel is built, and your computer restarted, it is time to load the necessary modules:

Code Listing 2.1: Loading USB modules

# modprobe usbcore 

(For 2.4 kernel users:)
# modprobe printer
(For 2.6 kernel users:)
# modprobe usblp

After the modules have loaded successfully, plug in the printer, and check dmesg to see if it was detected.

Code Listing 2.2: Checking Kernel Messages

# dmesg | tail

You should see something like this:

Code Listing 2.3: dmesg Output

hub.c: USB new device connect on bus2/2, assigned device number 2 
printer.c: usblp0: USB bidirectional printer dev 2 if 0 alt 1 proto 2 vid 0x03F0 pid 0x1104

Parallel Port Modules 

To enable Parallel port support, go to Parallel port support and enable Parallel port support and PC-style hardware. Depending on your printer you also have to activate Multi-IO cards (parallel and serial), Support for foreign hardware and IEEE 1284 transfer mode. Then go to Character devices and enable Parallel Printer Support. Users of 2.6 kernels will find these options under Device Drivers.

After the kernel is built, make sure that the printer is plugged in and then restart your computer. Now it is time to load the necessary modules:

Code Listing 2.4: Loading Parallel Port modules

# modprobe lp (Only for 2.6 kernel users)
# modprobe parport 
# modprobe parport_pc

After the modules have loaded successfully, check /var/log/messages to see if the printer was detected.

Note: If you are using something other than sysklogd, your kernel log file will be different.

Code Listing 2.5: Checking Kernel Messages

# tail /var/log/messages

You should see something like this:

Code Listing 2.6: /var/log/messages Output

lp0: using parport0 (polling).

Low-level testing 

Before setting up the printer with CUPS, we can test it with some simple low-level commands.

Note: Some printers (especially the PPA-based ones like HP's 720 series, 820 series and 1000 series) don't accept ASCII-feed. If you have such a printer, remember that you have a PPA-based printer and that this test will fail even if the printer works.

Note: Some printers (e.g. several HP LaserJets) need a ^L (Control-L) at the end of the file to trigger printing. Without the ^L the cat succeeds, but the printer absorbs the data, then sits and does nothing.

Code Listing 2.7: Printer Testing Using cat

# touch test.txt
# echo "Hello World" > test.txt
# cat test.txt > /dev/usb/lp0 

 Alternatively, for parallel port printers: 
# cat test.txt > /dev/lp0 

3. Special Printer Drivers

Before you use foomatic to generate a PPD file, it may be necessary to locate the third party drivers for your printer. For example, Epson provides several printer drivers for open source operating systems. However, as with Epson's, many of these special drivers are not open source.

The following printing drivers are available as ebuilds in Portage: gimp-print, omni, hpijs, pnm2ppa.

For most printers besides HP Inkjets, you will be able to use the standard Linux printer drivers. Visit the printer support database to find information on your specific printer. Make sure you read the documentation provided with any driver you download for installation and licensing information.

If you are using an HP Inkjet printer, it is necessary to emerge the hpijs printer driver. This driver handles all of the Postscript interpretation necessary to make the HP printer work. The hpijs driver is for HP Inkjet printers only, but is available through Portage for your convenience. The documentation from HP for the hpijs driver will be placed in /usr/share/doc/hpijs-<version>. The author highly recommends reading this.

If you are using a PPA-based printer it is necessary to emerge the pnm2ppa printer driver.

Code Listing 3.1: Emerging hpijs

# emerge hpijs

Note: If you are using a HP Laserjet, support may already be available via the GNOME printing system. If you are using a non HP Inkjet printer, you do not need to install this special printer driver.

4. PPD File Configuration

Now it is time to configure the printer and CUPS. In order for your printer to interpret Postscript correctly, CUPS needs a PPD (Printer Postscript Definition) file. The easiest way to generate a PPD is through foomatic.

Note: Another way is to download a PPD file from and place it in /usr/share/cups/model. If you use this method, you can skip the rest of this section and continue with CUPS Configuration.

Three pieces of information are necessary in order to make the below command work; you need your printer ID, printer device, and your print driver (this would be hpijs if you needed to install the special driver above). The printer ID and driver can be grepped from foomatic's database, and the print device is what device node your printer is connected to (i.e. file:/dev/lp0, file:/dev/usb/lp0 or for samba printers smb://user:[email protected]/share).

Before using foomatic-configure, please remember to start cupsd.

Code Listing 4.1: Starting cupsd

# /etc/init.d/cupsd start

Code Listing 4.2: General Usage of foomatic

(Fill in your printer model in $printer_model and printer ID in $printer_ID)
(Use the output of the first two grep statements to fill in the last foomatic-configure command)
# grep $printer_model /usr/share/foomatic/db/source/printer/* 
# grep $printer_ID /usr/share/foomatic/db/source/driver/* 
# foomatic-configure -s cups -p $printer_model_number -c file:$print_device_path -n queue name -d driver 

If grepping for the driver doesn't work, you can search for your printer on and check what drivers it is known to work with. Then pick one of those drivers and install:

Code Listing 4.3: Installing a PPD driver

(If you have multiple printers, use separate queue names. Otherwise an
easy-to-remember queuename, such as "default", suffices)
# foomatic-configure -s cups -p <printer model> -c file:<printer device> -n <queue name> -d <driver>

Now, here's a more specific example. The following code assumes that you have an Epson Stylus Color 980. Of course, you should replace this with your actual printer model.

Code Listing 4.4: Specific Usage of foomatic with Stylus Color 980

# grep "Stylus Color 980" /usr/share/foomatic/db/source/printer/* 
 Now look for the line which reads: 
/usr/share/foomatic/db/source/printer/Epson-Stylus_Color_980.xml:   <model>Stylus Color 980</model>
 Epson-Stylus_Color_980 is your printer ID. 

# grep Epson-Stylus_Color_980 /usr/share/foomatic/db/source/driver/* 
/usr/share/foomatic/db/source/driver/gimp-print-ijs.xml:  <printer><id>printer/Epson-Stylus_Color_980</id></printer>
 Here, your print driver is gimp-print-ijs.

# foomatic-configure -s cups -p Epson-Stylus_Color_980 -c file:/dev/lp0 -n Epson -d gimp-print-ijs 

5. CUPS Configuration

Since the printer itself is now configured, now CUPS must be setup to handle the printer queueing. CUPS can be accessed via web browser on port 631 of the printer server.

CUPS has a built in configuration file for the daemon that should at least be modified to allow for URI-like device naming. Open up /etc/cups/cupsd.conf with your favorite editor and set FileDevice to Yes:

Code Listing 5.1: Changing FileDevice to Yes

# nano -w /etc/cups/cupsd.conf
(Set FileDevice to Yes)

For those who want to set up clients using the new print server please look in /etc/cupsd/client.conf on the client machine and point the ServerName parameter to the network name of the print server.

Code Listing 5.2: Adding CUPS to default runlevel, and restarting CUPS

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

The CUPS daemon should now be running, so open up your favorite browser, point it to http://localhost:631 and click on Manage Printer. Here you can find your newly installed printer, configure it or print a test page. Make sure you set the default page size to the page size you use (e.g. A4 instead of Letter).

Note: If the printer does not work for some reason, go to the directory where you told your CUPS logs to be stored, and look through error_log.

6. Configuring programs to print using CUPS.


Most programs today have a native cups interface, so you need not change anything, just try to print in the program.


To be able to print documents using The Gimp, you have to (re)install the gimp package with the "gimpprint" USE variable enabled. This will install gimp-print if it isn't already done.

Code Listing 6.1: Emerging gimp with printing capabilities

(Be sure to have USE="gimpprint" enabled)
# emerge gimp

Now, open up The GIMP, and open an existing picture, or just some blank pic, it really doesn't matter because all we are looking for is the File menu. Right click on the image and go to File/Print The dialog for printing should come up, and when it does, click on new printer. If your printer is not already listed, type in the name of your printer, then select your printer type. Ok, you are now setup to print from The GIMP. Play with the settings and have some fun.

7. Using Linux as a Windows Compatible Print Server

Linux makes a great print server, then again, it makes a great everything server. The first thing to do is edit /etc/samba/smb.conf to fit your settings. The smb.conf file contains all of the settings that will make your Linux box look like a Windows NT server to any Windows machine. I have included an very utilitarian example smb.conf below. Edit as needed to fit your network environment.

Code Listing 7.1: Sample smb.conf


workgroup = YOUR_WORKGROUP
server string = Gentoo Linux Server
encrypt passwords = True
security = user
smb passwd file = /etc/samba/private/smbpasswd
log file = /var/log/samba/log.%m
domain master = Yes
local master = Yes
preferred master = Yes
os level = 65
dns proxy = No
name resolve order = lmhosts host bcast
bind interfaces only = True
interfaces = eth0
hosts deny = ALL
hosts allow = (list of allow hosts here) 
debug level = 1
create mask = 0644
directory mask = 0755
level2 oplocks = True
read raw = no
write cache size = 262144

comment = All Printer
path = /var/spool/samba
browseable = no

Most Windows drivers are PCL drivers. Jobs sent from Windows should be interpreted by CUPS as application/octet-stream and printed as raw file. So if you use CUPS, open up /etc/cups/mime.types and uncomment the following line:

Code Listing 7.2: Uncomment a line in /etc/cups/mime.types


Do the same for the following line in /etc/cups/mime.convs:

Code Listing 7.3: Uncomment a line in /etc/cups/mime.convs

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

Now that the SAMBA is configured, restart samba, go to your Windows machine and install a network printer. Piece of cake, eh?

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.
Updated October 25, 2004
John P. Davis

Wesley Leggette

Carl Anderson

Heinrich Wendel

Sven Vermeulen

Phil Bordelon

Summary:  A comprehensive printing guide for Gentoo Linux. This document covers both local and network printing.
The Gentoo Linux Store
Copyright 2001-2004 Gentoo Foundation, Inc. Questions, Comments, Corrections? Email [email protected].