For more detail, see the tutorial  (beware, it is not yet updated for Foomatic 4.0).
If you have trouble, see the troubleshooting guide .
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:
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:
|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.
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.
|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.
|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.
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
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.