From The Linux Foundation
Contents |
OpenPrinting CUPS Quick Start
For more detail, see the tutorial (beware, it is not yet updated for Foomatic 3.0).
If you have trouble, see the troubleshooting guide.
Quick Start
Before you even try, verify from the database that your printer is supposed to work.
| 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", most 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:
Save the PPD file in the directory /usr/share/cups/model/ (this may be a different location for you, but it will be called "something/cups/model/"). 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. Log in as root and enter one of the following commands: killall -HUP cupsd /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 scripts. (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). Download foomatic-rip and foomatic-gswrapper: cd /usr/bin wget http://www.linuxprinting.org/foomatic-rip wget http://www.linuxprinting.org/foomatic-gswrapper chmod 755 foomatic-rip foomatic-gswrapper ln -s /usr/bin/foomatic-rip /usr/lib/cups/filter/foomatic-rip The location of the CUPS filter directory may differ on other installations; look around for it. Also, be sure that your Perl interpreter is in /usr/bin (if not, edit the first line of the scripts). |
| 5. | Configure CUPS. The simplest way is to walk through the Add Printer wizard in the CUPS web interface at http://localhost:631/admin. KDE users may instead use the KDE Printing Manager's "Add Printer" wizard. |
| 6. | Adjust the print margins.
(If you are not using Foomatic, skip this step). Download the files align.ps and alignmargins, then run alignmargins as root and follow the instructions: cd /tmp wget http://www.linuxprinting.org/download/printing/align.ps wget http://www.linuxprinting.org/download/printing/alignmargins chmod 755 alignmargins su ./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 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. |
| 8. | Configure application software. br>
If you want to print out of PPD-aware applications like Star/Open Office, the GIMP, or from a Windows or Mac client, use the same PPD file you used to set up your printer queue and follow the application instructions. |
Printing
Now that you've set it up -- use it! The CUPS lp(1) and lpr(1) commands are your first friends here. 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 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, send a print job with only the option 'docs', like this: 'lp -d foo1 -o docs /etc/hosts'. This will make foomatic-rip print out an option summary (instead of the actual print job). You can also download and install lphelp (Usage: 'lphelp <printer> | less') to display the options nicely on the screen or use 'lpoptions -p <printer> -l' which displays also the options, but not so nicely.
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 ~/.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 or float 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 at the top of foomatic-rip, 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] | (Linuxprinting.org extension)|
| (= "raster driver") | |
| +----------------v-------------+
| |
SOMETHING-DEVICE-SPECIFIC <--------------------------------+
|
V
backend
|
NOTES:
|
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 tables which detail exactly how to execute a given printer driver. There are two front-ends which use these tables: (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 and PPD-aware applications/clients.
- The PPD File
- The PPD file generated by the database contains all inforation 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 backend 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 printfile 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.
Grant added a bunch of special code to pick out the media= and sides= options. These map sensibly to the PageSize, MediaType, and InputSlot enumerated selections, plus the boolean Duplex argument, 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. Oh, well.