by Kurt Pfeifle, Danka Deutschland GmbH
Printing is one of the most complicated things in day to day IT usage. CUPS makes printing more easy than ever before. But CUPS is new. It is different in many ways compared to other printing systems. So even experienced administrators sometimes get trapped if they try it for the first time. So don't be shy to ask. But remember: your chances to get a precise and helpful answer depend on asking a precise question and supplying helpful facts. If you don't know which are the helpful facts, this little article is for you. There are quite a few of volunteers trying to help you through any thicket you might have to pass on your way in these CUPS newsgroups (or if you are new to Linux altogether). But we don't want to waste our time on people who don't show an effort themselves.
As the support service through this newsgroup is done by people in their spare time, you should not give the impression of wanting everything fed by the spoon. Just make an effort yourself. If you tell us, what you did so far to solve your problem (and what results that gave), we might not only be much more responsive, but also more able to point you to the right direction.
If you have CUPS installed on your system, and if your
CUPS daemon is running, it is available online (HTML and PDF formats) on your
local system at http://localhost:631/documentation.html. If the
CUPS daemon is not running, you might find it in your file system; the
standard location is at
/usr/share/doc/cups/. On the CUPS
homepage you meet it at http://www.cups.org/documentation.html.
Read at least the Software Administrators Manual and the
Software Users Manual.
The most important ones are those for
lpadmin, lpr, lp, lpc,
lpq, lpstat, cupsd.conf, lprm . At
the end of most man pages you might be pointed to other man pages. Go
read them too. Check if there are new ones in a new CUPS version by
Example: "SuSE Linux 6.4, running Kernel 2.2.18"
Example: "CUPS 4.1.6...", (hint: you should
upgrade to the latest version, currently at least 1.1.14),
"...downloaded from www.cups.org as a portable binary and
installed through the companion
Examples: the CUPS web interface -- the
lpadmin command -- or a third party GUI tool, like the KDE
lpadmin -p 1st-printer -v socket://10.160.16.102 -L
"Next to my desk" (Won't work: you used a dash in the printer
name and it doesn't start with a character, which at present is
"illegal" with CUPS; your socket device URL will most likely not work
if you don't give a Port number; you forgot the "-E" parameter to
enable the printer; you didn't supply a PPD...)
So what PPD did you use for your printer? What sort of printer is it? Don't just tell the model name (some people might not know it -- but still *do* tell it), look up in your printer manual (you have one, haven't you?!), which printing languages the device is supposed to support (PostScript Level 2, PCL 5e, ESC/P...) and tell us...
Every printer in CUPS (if it is not used as a "raw" printer) needs a so called PPD (PostScript Printer Description) file. (In CUPS, even non PostScript printers use PPD files). The PPD contains descriptions about every one of the printer's capabilities and the printer specific commands to be send if one or more of those capabilities are to be called for in the print job (f.e. duplex printing from paper tray 3). For non-PostScript printers the PPD also contains a call for the appropriate CUPS- or Third-Party-Filter to be used. (A filter may be only one element in a whole filter chain). The final filter takes a PostScript (or other legal input) file and converts it to the correct raster or other format for the target print device.
PPDs for CUPS are supplied also from third parties, so there is no shortage of them. Unfortunately, there are some very outdated and badly working packages in circulation on the Net and amongst distributions. Make sure you don't use a wrong PPD for your printer.
Those are generic PPDs for 9-pin and 24-pin Epson matrix printers, for Epson Stylus Color and Stylus Photo printers, HP LaserJet and DeskJet printers and Dymo Label printers. These will enable you to print to several hundred different printer models, but will not give you access to specific capacities of the models (duplex, input tray selection, smaller margins,...)
Those are distributed alongside a PostScript
capable printer. Originally they were intended for MacOS or MS Windows
platforms only. CUPS can use them without a change. Normally, the
Windows NT versions work flawlessly with CUPS. You get them from the
manufacturer's website or from any MS Windows PC that has the
PostScript driver for this printer installed. Put a copy into your
/usr/share/cups/model/ directory to make it available for
installation through the web interface.
Those are commercially sold and supported drivers that are supplied (and only work for) ESP PrintPro, the professional printing software made by the creators of CUPS and based on CUPS. ESP PrintPro is available for Linux, Sun-Solaris, SGI-IRIX, HP-UX, IBM-AIX, Compaq Tru64 UNIX and Digital Unix.
Those are a way to make any previously working pair of Ghostscript-filter / printer-device work with CUPS. You'll usually get the same (good or bad) printing quality as in standard LPR/LPD or LPRng print system installations. But in addition you'll have all the CUPS goodies: web interface, access to all supported printer/driver/filter options (through commandline, GUI or web interface), etc. This concept is lately also known as "Foomatic". For it to work, you do not just need the Foomatic PPD (which may be generated online on the Linuxprinting.org website), but also the accompanying cupsomatic Perl script (download it too), plus working Perl and "standard" Ghostscript installations on your box. Unfortunately some Linux distributions have bundled alpha and beta versions of this software without any documentation, which leads in many cases to difficulties and outright failure to setup a printer. cupsomatic, if it works, "hi-jacks" your print data after it has passed the CUPS pstops filter, hands it to the appropriate Ghostscript filter, which generates the print-ready output and gives it back to the CUPS backends to pass it to the target printer.
Those are distributed as part of the gimp-print
software source code. If you compile it with CUPS support enabled
./configure --with-cups), you get everything installed
into the right places in CUPS, including specific PPDs for around 120
different models of Canon, Epson, HP and Lexmark color printers. The
creators of CUPS are founders and still part of the development team of
So not every PPD works with every filter. Nor is a PPD the *only* file you need to make your printer work. Any PPD for a non-PostScript printer is associated with a companion filter that is needed for it to work.
Only if you own or have access to a PostScript printer, it is good enough to copy the PPD from a friend's box. If you want to use the gimp-print software, the PPD is only part of the cake. *You also need to have the Gimp-Print filters installed for the Gimp-Print PPD to function as expected!* And don't rely a CUPS-O-Matic generated PPD to work with a PostScript printer! This is generally a bad idea. PostScript printers should be installed using the vendor PPD for that model (best use the one targeted for Windows NT).
You can do a lot to de-bug a not working printer:
For every installed printer (apart from "raw" printers),
there is a copy of the companion PPD in the
directory, named like your printer with a .ppd extension. (Hint: you
don't need to put this file manually there; it's done by the
lpadmin command or the web installation interface). Example: a
printer named "MySuperDuperInkjet" will have a
/etc/cups/ppd/MySuperDuperInkjet.ppd. A nice trick: You can look
at a PPD in use for a particular printer through your browser (if your CUPS
daemon is running) by pointing it to http://localhost:631/printers/MySuperDuperInkjet.ppd.
Amongst the first 25 lines of this file you should recognize lines like the
*PCFileName: "escp2-1290.ppd" *Manufacturer: "EPSON" *Product: "(GIMP-print v4.1.99-b1)" *ModelName: "escp2-1290" *ShortNickName: "EPSON Stylus Photo 1290" *NickName: "EPSON Stylus Photo 1290, CUPS+GIMP-print v4.1.99-b1"
Most important is the line starting "*NickName...". It should always be there and tell you which sort of PPD is in use. Supply this information, if it is related to your problem!
(If you are not able to access the file through you
browser, the command "
head -n 25
/etc/cups/ppd/MySuperDuperInkjet.ppd" will also get you there.)
Amongst possible tags for the PPDs you might find things like:
Supply this little piece of information; most of the time it is important.
Switch on the "debug" mode in the LogLevel
directive for your CUPS daemon. Edit
wherever this configuration file is installed in your case) to have the line
LogLevel debug" there. Then restart your CUPS daemon
/etc/software/init.d/cups start (the command may be customized by
your Linux distribution; f.e. SuSE will take "rccups start").
Now print a job. Watch what is written to your CUPS error
log. It normally sits in
/var/log/cups/error_log. In debug
level, nearly every action of the CUPS daemon is logged. You can see
which filters and backends are called in which order. Very often you'll get a
hint about what is missing for the print job to succeed.
error_login "debug" mode
An example that recently dropped into my mailbox. Some parts are deleted. Look at it. Do you spot the problem? Have a try:
d [04/Sep/2001:21:38:28 +0100] SendBrowseList: (97 bytes) 100e 3 ipp://mama:631/printers/hp720c "Dach" "Farbdrucker" "HP DeskJet 720C, Foomatic + pnm2ppa" [....] D [04/Sep/2001:21:38:29] StartJob(22, 080868b0) D [04/Sep/2001:21:38:29] StartJob() id = 22, file = 0 D [04/Sep/2001:21:38:29] StartJob: argv = "hp720c","22","root", "Test Page","1","","/var/spool/cups/d00022-001" D [04/Sep/2001:21:38:29] StartJob: envp = "PATH=/bin:/usr/bin", "SOFTWARE=CUPS/1.1","USER=root",[...], "DEVICE_URI=parallel:/dev/lp0", "PRINTER=hp720c",[....] D [04/Sep/2001:21:38:29] StartJob: statusfds = 7, 8 D [04/Sep/2001:21:38:29] StartJob: filterfds = 9, -1 D [04/Sep/2001:21:38:29] StartJob: filter = "/usr/lib/cups/filter/pstops" D [04/Sep/2001:21:38:29] StartJob: filterfds = 10, 11 D [04/Sep/2001:21:38:29] start_process("/usr/lib/cups/filter/pstops", [....]) I [04/Sep/2001:21:38:29] Started filter /usr/lib/cups/filter/pstops (PID 935) for job 22. D [04/Sep/2001:21:38:29] StartJob: filter = "/usr/lib/cups/filter/cupsomatic" D [04/Sep/2001:21:38:29] StartJob: filterfds = 9, 12 D [04/Sep/2001:21:38:29] start_process("/usr/lib/cups/filter/cupsomatic", [....] I [04/Sep/2001:21:38:29] Started filter /usr/lib/cups/filter/cupsomatic (PID 936) for job 22. D [04/Sep/2001:21:38:29] StartJob: backend = "/usr/lib/cups/backend/parallel" D [04/Sep/2001:21:38:29] StartJob: filterfds = -1, 10 D [04/Sep/2001:21:38:29] start_process("/usr/lib/cups/backend/parallel", [....]) I [04/Sep/2001:21:38:29] Started backend /usr/lib/cups/backend/parallel (PID 937) for job 22. d [04/Sep/2001:21:38:29] SendBrowseList: (97 bytes) 100e 4 ipp://mama:631/printers/hp720c "Dach" "Farbdrucker" "HP DeskJet 720C, Foomatic + pnm2ppa" D [04/Sep/2001:21:38:29] CloseClient() 5 D [04/Sep/2001:21:38:29] CloseClient() 3 D [04/Sep/2001:21:38:29] EBUG: Page = 612x792; 9,40 to 603,766 D [04/Sep/2001:21:38:29] pw = 594.8, pl = 726.9 D [04/Sep/2001:21:38:29] PageLeft = 8.6, PageRight = 603.4 D [04/Sep/2001:21:38:29] PageTop = 766.5, PageBottom = 39.6 D [04/Sep/2001:21:38:29] PageWidth = 612.0, PageLength = 792.0 D [04/Sep/2001:21:38:30] Cupsomatic backend version $Revision: 1.3 $ running... D [04/Sep/2001:21:38:30] called with arguments: '22','root','Test Page','1','' D [04/Sep/2001:21:38:30] ppd=/etc/cups/ppd/hp720c.ppd D [04/Sep/2001:21:38:30] options: -><- D [04/Sep/2001:21:38:31] gs PID pid2=939 D [04/Sep/2001:21:38:31] /usr/lib/cups/filter/cupsomatic: prepended: D [04/Sep/2001:21:38:31] gs command: gs -sDEVICE=ppmraw -q -dNOPAUSE -dSAFER -dBATCH -r600 -sOutputFile=- - | pnm2ppa -v 720 -f /etc/pnm2ppa.conf --eco -F /etc/pnm2ppa.gamma_normal -B 2 -t 10 -b 150 -l 10 -r 10 -x 160 -y 50 -i - -o - D [04/Sep/2001:21:38:31] sh: pnm2ppa: command not found D [04/Sep/2001:21:38:31] foomatic-gswrapper: gs '-sDEVICE=ppmraw' '-dNOPAUSE' '-dSAFER' '-dBATCH' '-r600' '-sOutputFile=|cat >&3' '-' 3>&1 1>&2 D [04/Sep/2001:21:38:31] GNU Ghostscript 5.50 (2000-2-13) D [04/Sep/2001:21:38:31] Copyright (C) 1998 Aladdin Enterprises, Menlo Park, CA. All rights reserved. D [04/Sep/2001:21:38:31] This software comes with NO WARRANTY: see the file COPYING for details. D [04/Sep/2001:21:38:32] Loading NimbusSanL-Bold font from /usr/share/ghostscript/fonts/n019004l.pfb[....] D [04/Sep/2001:21:38:32] Loading NimbusSanL-Regu font from [....] done. D [04/Sep/2001:21:38:33] Loading NimbusRomNo9L-Regu font from [....] done. D [04/Sep/2001:21:38:34] Loading NimbusSanL-BoldItal font from [....] done. D [04/Sep/2001:21:38:35] cat: write error: Broken pipe D [04/Sep/2001:21:38:37] mallinfo: arena = 550944, used = 521384, free = 29560 D [04/Sep/2001:21:38:49] Error: /ioerror in --.outputpage-- D [04/Sep/2001:21:38:49] Operand stack: D [04/Sep/2001:21:38:49] 416.5 308.0 306.0 748.0 306.0 55.0 51.0 1 true D [04/Sep/2001:21:38:49] Execution stack: D [04/Sep/2001:21:38:49] %interp_exit .runexec2 --nostringval-- --nostringval-- --nostringval-- 2 %stopped_push --nostringval-- --nostringval-- --nostringval-- false 1 %stopped_push 1 3 %oparray_pop .runexec2 --nostringval-- --nostringval-- --nostringval-- 2 %stopped_push --nostringval-- 7 3 %oparray_pop --nostringval-- --nostringval-- --nostringval-- --nostringval-- D [04/Sep/2001:21:38:49] Dictionary stack: D [04/Sep/2001:21:38:49] --dict:918/1241(G)-- --dict:0/20(G)-- --dict:68/200(L)-- D [04/Sep/2001:21:38:49] Current allocation mode is local D [04/Sep/2001:21:38:49] Last OS error: 32 D [04/Sep/2001:21:38:49] Current file position is 14608 D [04/Sep/2001:21:38:49] GNU Ghostscript: Unrecoverable error, exit code 1 D [04/Sep/2001:21:38:49] tail process done writing data to *main::STDOUT D [04/Sep/2001:21:38:49] UpdateJob: job 22, file 0 is complete. D [04/Sep/2001:21:38:49] CancelJob: id = 22 D [04/Sep/2001:21:38:49] StopJob: id = 22 D [04/Sep/2001:21:38:49] StopJob: printer state is 3
Did you spot the problem? Yes, on 04/Sep/2001, at 21:38:31, the system was looking for, but could't find or execute the pnm2ppa filter. Although the user didn't supply any information about his system, one can see and conclude, what his environment is like:
What is wrong here?
Some background first: the HP DeskJet720C is a so called PPA printer. PPA has been developed by Hewlett-Packard in the mid-90s and was soon after dropped again. It stands for "Print Performance Architecture" and due to little market success was only used in a few models. The idea in PPA was to make a cheap printer, saving on electronics inside the device. The complete rendering must be done by the printing host. Of course there were only drivers by HP for the windows platform.
Now pnm2ppa is a filter that can convert PNM ("Portable Anymap") to the PPA format. There are three different PNM variants: PPM (Portable Pixmap, color), PGM (Portable Graymap)and PBM (Portable Black-and-White-map). pnm2ppa is *not* a part of Ghostscript. It has to be installed separately. You can find it at http://pnm2ppa.sourceforge.net/ or http://sourceforge.net/projects/pnm2ppa/). In SuSE it is part of the "filters" package. To print to the printer in question, you still need Ghostscript, namely to *create* the PNM from the original PostScript. The Ghostscript-"devices" ppmraw, pgmraw or pbmraw will do this from PostScript input. The conversion chain and travelling route of the print file through the system could therefor be described like this: PostScript --> ppmraw --> PNM --> pnm2ppa -->PPA --> HP720C printer.
As you can see from the
error_log, it stops
at the pnm2ppa stage because this filter is not installed or can not
be found or executed by the cupsomatic "backend"...
If you find it appropriate to send your cupsd.conf configuration file to the ones you ask for help, please strip it as far as possible. We don't necessarily want to scroll through all the comments. A command like
cat /etc/cups/cupsd.conf|grep -v ^#|grep [:alnum:]
will print your cupsd.conf file onto the screen without the comment lines (starting with a "#" character), and
cat /etc/cups/cupsd.conf|grep -v ^#|grep [:alnum:] >
will re-direct this output to the file cupsd.conf-stripped. It looks f.e.like this:
ServerName 192.168.123.201 ServerAdmin root@transmeta Classification none DefaultCharset UTF-8 DefaultLanguage en Printcap /etc/printcap PrintcapFormat BSD [....]
Recent versions of CUPS help you determine a few things.
The utility cups-config has several optional parameters, shown by
"cups-config --help".Its output is:
kurt@transmeta:~> cups-config --help Usage: cups-config --api-version cups-config --cflags cups-config --datadir cups-config --help cups-config --ldflags cups-config [--image] [--static] --libs cups-config --serverbin cups-config --serverroot cups-config --version
If you ask it questions, f.e. "cups-config --libs", it will tell you which libraries have been used to compile into it. So if you are looking for SSL support and there is no "-lssl" output to your question, you get a hint how to help yourself.
To determine which static libraries are linked to your cupsd
executable, use the
ldd command (as root). Here is what's on my
transmeta:/home/kurt/cups-versionen # ldd `which cupsd` libz.so.1 => /lib/libz.so.1 (0x4002e000) libssl.so.0.9.6 => /usr/lib/libssl.so.0.9.6 (0x4003d000) libcrypto.so.0.9.6 => /usr/lib/libcrypto.so.0.9.6 (0x4006a000) libpam.so.0 => /lib/libpam.so.0 (0x40133000) libdl.so.2 => /lib/libdl.so.2 (0x4013c000) libcups.so.2 => /usr/lib/libcups.so.2 (0x40140000) libnsl.so.1 => /lib/libnsl.so.1 (0x4015a000) libcrypt.so.1 => /lib/libcrypt.so.1 (0x40171000) libc.so.6 => /lib/libc.so.6 (0x4019e000) /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
This output even shows you, which SSL-version has been used (0.9.6), in case you need to know for troubleshooting....
If you're wondering, why your standard RedHat KDEPrint command kprinter does not support CUPS, check if the following files are in place on your system:
If those files are not installed on your system, then the possible reasons are:
Please be very hesitant to write mails to private addresses of people you know answering questions in public forums. Don't expect them to react dutifully on unsolicited personal mails. Start asking in the suggested public forums and only send material to private mail addresses if asked to do so. Asking on a public list will enable everybody to learn from the given answers. It increases your chance to get a quick response, as there might be different people watching the list fit for giving advice. Remember, this is a volunteer service. Sometimes people are tired to answer. Can you imagine that someone might feel molested by receiving 20 - 30 personal mails per day, asking the same questions about printing over and over again? It is OK to ask the questions -- but keep it voluntary for your advisors, as it is the case, if you ask in the following public forums or on mailing lists:
Now that you have read all the suggested stuff and thought about your problem again: do you still need to ask? If so, you're welcome. But please, supply the facts you have...
Kurt Pfeifle (email@example.com)
(Version 0.92, February 2002)