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.

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.

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.
|

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

CUPS also includes a command line administration tool; consult the CUPS documentation if you prefer to use that.
|

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.
|

See the ''beh'' page for more information and for setup instructions.
|

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.3×5.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.

\\  
\\    "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.