OpenPrinting CUPS Quick Start

For more detail, see the tutorial (beware, it is not yet updated for Foomatic 4.0).

If you have trouble, see the troubleshooting guide.

Quick Start

In most cases you do not need to go through these steps. Modern Linux distributions have everything prepared for using most printers. For USB printers it is often enough to simply plug them in. The printer gets auto-detected and after some seconds a message pops up on the screen telling that the printer is set up. If this is not the case or for parallel or network printers you simply start the distribution's printer setup tool out of the system administration menu or out of a system administration application, click on a button for adding a new printer and then follow the screen instructions. In certain cases PPDs or drivers are even automatically downloaded from this web site.

If this does not work, usually there is no suitable driver installed on your system. Verify in the OpenPrinting database whether your printer is supposed to work and whether there is a driver or PPD file available.

0. First just give it a try.

Start at Step 5 (Configure CUPS). See if this works before installing new software; most distributions ship many drivers and PPD files.

1. Find and install the driver.

First examine your printer's page in the database to determine if you have a PostScript printer or will be using a driver. If your printer needs a driver, check that the driver for your printer is installed. There are several styles of driver; to see if yours is installed, try:

Ghostscript built-in
Ghostscript is present on most free and many commercial Unix systems. It is not part of Mac OS X as shipped by Apple. Ghostscript contains many "compiled-in" drivers.
You can see the available Ghostscript drivers on your system by running 'gs -h'. If the driver you need is not listed, you need to obtain a new Ghostscript package which includes this driver, or compile Ghostscript yourself. GPL GhostScript includes all known free software built-in drivers and Linux distributions ship it with all drivers actually compiled. Currently such drivers are not developed any more by third parties, as adding these drivers is awkward and there are plenty of interfaces for modular drivers: CUPS Raster, IJS, OpenPrinting Vector, filters, ....
CUPS Raster
CUPS has a native driver style called "CUPS Raster". These are executable programs, installed into CUPS' filter directory, which CUPS drives using a set of filters and Ghostscript. Such drivers are relatively easy to get going with CUPS, so are usually the best choice for CUPS users.
The gimp-print driver is probably the best known third party CUPS driver. Several printer vendors also provide CUPS drivers, typically as part of an installer utility. A few such drivers are included with CUPS.
You can see which CUPS Raster drivers are installed by examining the filters in /usr/lib/cups/filter; usually CUPS Raster drivers have names beginning with "rasterto". Each CUPS Raster driver program will also have one or more PPD files in /usr/share/ppd or /usr/share/cups/model, each containing a reference to the proper CUPS Raster program.
IJS
IJS is a plug-in interface to connect raster driver modules with Ghostscript (or a renderer in general) based on pipes. It was introduced for HP's HPIJS driver but currently it also used by several other drivers. The driver executables are usually installed into the standard search path for programs (/usr/bin or /usr/local/bin).
OpenPrinting Vector
This driver concept is developed by the Japanese members of the OpenPrinting project. It is a plugin interface for Ghostscript and other renderers which supports high-level (vector) graphics. This way modular drivers for printers with proprietary high-level page description languages can be created. Such printers are common on the Japanese market.
Filter
Some drivers are simply a filter into which generic bitmap output of Ghostscript is piped. This was one of the first solutions to make printer drivers without compiling them into Ghostscript. The filter executables are usually installed into the standard search path for programs (/usr/bin or /usr/local/bin).
Uniprint
A few drivers are Uniprint drivers. These consist simply of a upp file containing various parameters; most are included with Ghostscript. Others you will need to obtain and place in your ghostscript library directory (one of the directories listed under "Search path:" at the end of the "gs -h" output).

If your driver is not installed, install it. See whether there is a driver download link for your computer's architecture (normal PCs are "x86 32 bit", newer PCs are "x86 64 bit", older Macs are "Power PC"), on your printer's page in the database. If so, install this package as shown here. If not, the actual installation procedure varies by driver and distribution. Look first for a prepackaged binary kit of any sort; failing that look for generic installation instructions provided from the driver website.

2. Install a PPD file.

CUPS requires a PPD file to define how it will use the printer and driver (if any). PPD files come from several sources, be sure you get yours from the right place:

If you have a PostScript printer
Obtain the PPD file from your printer's vendor. Several vendors post PPDs on the OpenPrinting web site. Go to your printer's entry and look whether a driver named "Postscript-<vendor name>" is available. Take the PPD from this driver entry. Other sources are the printer manuafacturer's web site (look for a package for Linux or Unix, Windows and Mac packages are often not simple to extract on a Linux machine) on the driver CDs which come with the printer, or on a Windows or Mac OS X partition if the printer was already set up on that operating system. You do not need a driver (Step 1), just the PPD file.
If you do not have a PostScript printer
You will need a driver. The OpenPrinting database can help yopu find a suitable one. Several drivers can be downloaded there as a ready-to-use binary package for all LSB-compliant distributions. In any case, you find links to driver project pages. If the driver does not ship a PPD file, use the PPD file offered to you by the OpenPrinting database. Follow the "download PPD" link in such a case. Save downloaded PPD files in /usr/share/ppd, /usr/share/cups/model, or wherever your CUPS setup has its PPD directory. The PPD file does not need to be executable, but it should be world-readable and should have the file name extension ".ppd".
3. Restart the CUPS daemon (Only CUPS 1.1.x and older).

Log in as root and enter one of the following commands:

killall -HUP cupsd
/etc/init.d/cups restart
sudo /etc/init.d/cups restart
/etc/software/init.d/cups restart

The actual command depends on the operating system distribution which you are running and may be different from these.

4. Install the foomatic-filters package.

(If you are using a native CUPS Raster driver, or are using a PostScript printer with a PPD from your printer vendor, you probably do not need Foomatic and should skip this step). Usually, your Linux distribution ships the foomatic-filters package (you have /usr/lib/cups/filter/foomatic-rip and /usr/bin/foomatic-rip then). If not, get the foomatic-filters package from here. You need a C compiler and the Ghostscript shared library to build it. See the USAGE file in the foomatic-filters package for more information.

5. Configure CUPS.

If the printer is a USB printer, turn it off and turn it on again. On some distros an automatic setup of the printer gets triggered. Otherwise use your distribution's printer setup tool or the CUPS web interface at http://localhost:631/admin and go through the steps of the add printer wizard.
CUPS also includes a command line administration tool; consult the CUPS documentation if you prefer to use that.

6. Adjust the print margins.

(If you are not using Foomatic or if the margins on your printouts are correct, skip this step). Download the files align.ps and alignmargins, then run alignmargins as root and follow the instructions:

cd /tmp
wget http://www.openprinting.org/download/printing/align.ps
wget http://www.openprinting.org/download/printing/alignmargins
chmod 755 alignmargins

su
./alignmargins

   OR

sudo alignmargins

This will add the Margins print option so you can turn on ("lpr -o Margins=Custom printfile", default setting) or off ("lpr -o Margins=Default printfile") your adjustments.
Note that this does not work for all drivers.

7. Avoid your print queue being automatically disabled (CUPS 1.2.x or older)

It is recommended to install beh - the Backend Error Handler. This makes the behaviour of CUPS on errors during the communication with the printer (e. g. printer turned off) configurable instead of CUPS simply disabling the queue.
See the beh page for more information and for setup instructions.

Printing

Most modern application programs support CUPS directly. Your printer(s) are listed in the printing dialogs and you can change option settings by clicking a "Properties" button and/or clicking the tabs in the dialogs.

For printing from the command line or out of shell scripts use the CUPS lp(1) and lpr(1) commands. For example:

$ lp -d foo1 -o PageSize=Letter /etc/motd

This will print the message of the day on letter paper. For many drivers, you'll want to use the lpadmin(9) or lpoptions(1) command to lock down a set of sensible defaults for you. This is especially true for free drivers, which tend to have a large number of options.

To see the options available for your setup, run the 'lpoptions -p foo1 -l' command or send a print job with only the option '<tt>docs', like this: 'lp -d foo1 -o docs /etc/hosts'. The former shows the option list on the screen, the latter prints it. You can also download and install lphelp (Usage: 'lphelp <printer> | less') to display the options nicely on the screen.

Usually, you can also use the media=..., sides=..., and duplex "standard" CUPS options as documented in the CUPS user manual; they should work if there are InputSlot, MediaType, and/or Duplex options for your driver.

Options can also be supplied only to selected pages when Foomatic is used. To apply an option to specific pages prepend the option with a page specification separated by a colon:

$ lp -d foo1 -o 1:InputSlot=Letterhead -o InputSlot=Standard file
$ lp -d foo1 -o even:Watermark=on -o odd:ColorMode=Gray file
$ lp -d foo1 -o 1,6-10,15,20-:MediaType=YellowPaper file

The syntax is "even", "odd", or giving comma-separated page numbers or page ranges. Option settings with page selection override option settings for the whole document on the appropriate pages. More specific (less pages selected) settings override less specific settings on the appropriate pages.

The first line in the example prints the first page on letter head paper and the rest on standard paper. The second line prints the even-numbered pages with watermark and the odd-numbered pages in grayscale. The third line prints the first, the 6th to the 10th, the 15th, the 20th, and all later pages on yellow paper, the rest on standard paper.

Page-specific option settings cannot be set as default in the PPD files, but they can be set by editing the ~/.cups/lpoptions or /etc/cups/lpoptions files.

With some printer/driver combos it is also possible to use arbitrary, custom page sizes (as long as they fit into the printer). Then you have a "Custom" setting for the "PageSize" option which you can use as follows:

$ lp -d foo1 -o PageSize=Custom.20x30cm file.ps

You give always at first the width, then the height and in the end one of the units "pt" (PostScript points, 1/72 inch), "in" (inches), "cm" (centimeters), or "mm" (millimeters). If you leave out the unit, "pt" will be used as default. The numbers do not need to be integers, something like "4.3x5.5in" is allowed.

Note that options with a user-provided integer, float. string, or password value are not supported by the PPD syntax. With Foomatic-based printers, you may specify these options on the command line, and CUPS will just sort of pass them along.

For more information on using CUPS and defining print queues, consult the CUPS documentation. If it doesn't work, turn on the debug flag in /etc/foomatic/filter.conf and examine the debugging output in the file /tmp/foomatic-rip.log. Read also the Troubleshooting-CUPS-and-Asking-for-Help-HOWTO. And feel free to contact us for help.

How does it work?

The filtering chain for CUPS (for versions 1.1.15 or later) and how foomatic-rip fits into the picture:
 
   "foomatic-rip" constructs an appropriate commandline and executes Ghostscript to generate
   print-ready raster data  (the CUPS daemon controls  the execution of  the other filters,
   and calls foomatic-rip as the last filter of the chain, because a "*cupsFilter" entry in
   the PPD tells it to do so):
   =========================================================================================
 
   [SOMETHING]-FILEFORMAT
        |
        |   [something]tops
        V
   APPLICATION/POSTSCRIPT
        |
        |   pstops
        V
   APPLICATION/VND.CUPS-POSTSCRIPT-----------+
                                             |
                    +------------------------v------------------------------+
                    |                                                       |
                    |       Ghostscript at work....                         |
                    |          (= a "postscript interpreter")               |
                    |                                                       |
                    | * * * * * * * * * * * * * * * * * * * * * * * * * * * |
                    |                        *                              |
                    |  run with commandline  *                              |
                    |  parameter             *                              |
                    |       "-sDEVICE=cups"  *                              |
                    |                        *                              |
                    |  called by pstoraster  *   run with commandline       |
                    | (CUPS standard filter) *   parameter                  |
                    |                        *        "-sDEVICE=[s.th.]"    |
                    +------------------v-----+                              |
                                       |     |                              |
   APPLICATION/VND.CUPS-RASTER <-------+     |                              |
        |                                    |   called by foomatic-rip     |
        |  rasterto[something]               | (openprinting.org extension)|
        |   (= "raster driver")              |                              |
        |                                    +----------------v-------------+
        |                                                     |
   SOMETHING-DEVICE-SPECIFIC <--------------------------------+
        |
        V
       backend

 

NOTES:
  • (1) MIME types + file formats are in CAPITAL letters: "[SOMETHING]-FILEFORMAT", "APPLICATION/POSTSCRIPT", "APPLICATION/VND.CUPS-POSTSCRIPT", "APPLICATION/VND.CUPS-RASTER"
  • (2) filters are in lower case letters: "[something]tops", "pstops", "rasterto[something]"
  • (3) Gimp-Print, some other 3rd-Party-Filters (like TurboPrint) for CUPS and ESP PrintPro plug-in where "rasterto[something]" is denoted.

 

To see where this fits into the "big picture" of the complete CUPS filtering environment, go to the complete CUPS-Filter-FlowChart, drawn by Kurt Pfeifle. (Note, that this chart doesn't yet reflect the new names for Foomatic-3.0, like "foomatic-rip" etc., but you might still get the idea from it....)

There are three parts to the Foomatic scheme:

The Database
The database contains a number of XML files which detail exactly how to execute a given printer driver. There are two front-ends which use these files: (1) the human-readable one generates the information shown on all "Execution Details" pages; (2) the PPD-O-Matic PPD generator computes an Adobe-compliant PPD file which you need to configure your print queue.
The PPD File
The PPD file generated by the database contains all information about important printer capabilities, available options and how to build the renderer's (usually Ghostscript's) command line depending on the user's choices for the options. foomatic-rip reads it to know how to execute the print job. GUI frontends read it to build dialog boxes in which the user can adjust the options. Besides the usual stuff the PPD file contains various extra lines beginning with "*Foomatic...". These contain details of the driver command line, the information whether an option accepts arbitrary numbers (and not only the choices listed in the PPD file), and more. CUPS and application programs ignore these extra lines.
The filter
The filter script 'foomatic-rip' is called by CUPS with various inputs; inputs include both the PPD filename and the various options selected by the user. foomatic-rip opens the PPD, extracts all options and their possible settings and also the command line to execute Ghostscript with the appropriate driver. It parses the PostScript print file for option settings. These option setting could have been stuffed in by CUPS or by application programs; foomatic-rip itself also inserts additional PostScript code into the print data stream to set options, if needed. It also massages the standard CUPS option types into the more generic printer/driver-specific format used by the database.

CUPS completely supports normal PPD option types, which include boolean values and enumerated choices. PPDs do not support arbitrary user-inputted numerical arguments, so PPD-O-Matic maps them to a list of up to 100 equally-spaced discrete values out of which the user can choose when he is using a PPD-driven GUI. Independent of this there is nothing stopping the user from explicity saying '-o Gamma=4.3' on the command line and having it work, too. Here the chosen value does not even need to be one of the choices offered in the PPD file, it simply needs to be between the allowed minimum and maximum value. Foomatic PPD also contain the CUPS PPD extensions for custom options. So GUIs which understand these extensions allow the user to enter arbitrary numerical or string values, too. Foomatic understands also CUPS' command line syntax for custom options, for example it also understands '-o Gamma=Custom.4.3'.

There was also added a bunch of special code to pick out the media= and sides= options. These map sensibly to the PageSize, MediaType, InputSlot, and Duplex enumerated selections, if present. It's all a bit ugly if a driver supports an option that happens to be named the same as an existing standard ipp/cups option.

Groups: