wiki:CupsFaq

Version 6 (modified by Alex Taylor, 14 years ago) ( diff )

Add directions for installing SMB support

eCups Frequently Asked Questions

1. General Information

2. Configuration & Use

3. Troubleshooting


1. General Information


1.1. What is eCups?

eCups is complete printing framework which is designed to allow the support of modern printers which lack ‘native’ OS/2 print drivers.

eCups includes the following components:

  • CUPS (ported by Paul Smedley)
  • GhostScript (ported by Paul Smedley)
  • Print driver packages such as Gutenprint, Splix, & HPLIP (ported by Paul Smedley)
  • eCups port driver (various authors; based on LPR32 by Serge Sterck)
  • eCups PostScript driver (various authors; based on modified IBM PSCRIPT.DRV)
  • foomatic-rip filter (ported by Alex Taylor and Paul Smedley)

Although the terms are sometimes used interchangeably, there is a distinction between eCups and CUPS. eCups is basically a framework of related products and tools for integrating the CUPS product into OS/2 and eComStation.


1.2. All right then, what is CUPS?

CUPS stands for Common Unix Printing System. As the name implies, it was originally designed to be a generic framework for printer support under various UNIX systems. Since then, it has been adopted as the main printing engine under Linux and MacOS X as well.

It is important to keep in mind that CUPS is not a printer driver. At its most fundamental level, CUPS is essentially a print spooler plus a collection of data conversion modules.

The actual printer ‘drivers’ are located in addon packages like Gutenprint. CUPS itself does have a few built-in generic drivers, but generally you need at least one driver package installed in addition to CUPS itself.


1.3. Another spooler? Doesn't OS/2 already have a print spooler?

Yes, it does... but the OS/2 spooler is only capable of receiving print jobs sent by various applications, converting them with a native OS/2 printer driver, and then sending them straight to the printer port (plus logic for managing the job queue, of course).

The CUPS spooler, by contrast, is able to perform a number of vital additional tasks during the process of sending a job to the printer. These tasks are what allow CUPS to support such a vast range of printers.


1.4. How does CUPS work?

First of all, CUPS makes extensive use of PostScript, which is an open and widely-used standard for data formatting. A basic understanding of how PostScript normally works with regards to printing is needed in order to properly explain how CUPS works. Refer to the box below for a brief summary, or just skip past it if you already know this.

PostScript and Printing

Different printers require the data they receive for printing to be in a particular format or printer ‘language’. Naturally, printers from any given manufacturer typically use that manufacturer's own proprietary printer language. But even different printers from the same manufacturer often use slightly (or occasionally even radically) different variations of these languages. This is, of course, why we need specific drivers for our printers in the first place.

Some printers, however, (especially higher-end laser printers) are PostScript printers, meaning that they use PostScript as their printer language. (Often, it must be said, in addition to the manufacturer's proprietary language.) Because PostScript is an open, mature, and fully standardized language, this generally means that any printer driver which outputs generic PostScript data can print to any PostScript printer.

In this case, the individual capabilities of the printer (such as paper size, DPI, number and type of trays, duplexing, etc.) are provided by the manufacturer in standardized format via an ASCII file called a PostScript Printer Description (PPD).

The standard OS/2 PostScript printer driver includes a utility called PIN which allows these PPDs to be imported, thereby adding printer-specific support for the model in question without the need for new drivers.

Of course, since PostScript is a standardized language, it should also be possible to print to any PostScript printer using only generic settings (the PostScript driver includes a definition called "Generic PostScript Printer" for this purpose). As you would expect, however, using a generic printer definition does not let you take advantage of printer-specific features.

Given the above, there is rarely a problem with using any model of PostScript printer under OS/2, as long as a PPD for that printer is available. Where we need something like CUPS is for non-PostScript printers (of which, regrettably, there are many).

Basically, what CUPS does is add a PostScript emulation layer on top of all printers. That is to say, from the perspective of the operating system and applications, CUPS turns every printer into a PostScript printer. It accomplishes this emulation through a complex system of conversion utilities.

Because CUPS presents all printers as PostScript, it expects to receive incoming printer jobs in PostScript format. Generally, this is the responsibility of whatever passes the print job to CUPS in the first place, although CUPS is capable of converting a few specific file formats into PostScript on its own (such as plain text, PDF, or certain image formats).

CUPS takes each printer job it receives through the following steps:

  1. Receives the printer job data as a PostScript file. If the file CUPS receives is not PostScript, but is in another supported format, it calls one of a number of ‘pre-filter‘ utilities to convert it into PostScript.

    (Some types of image file can be converted directly to CUPS-Raster format (see step C) when printing to a non-PostScript printer; in this case, CUPS skips step B and the first part of step C.)

  2. Uses the configured printer settings (defined via PPD and configured in the CUPS administration GUI and/or the desktop printer object) to add printer- and job-specific options to the PostScript data.

    If printing to a genuine PostScript printer, this data is then sent directly to the backend for printing (step D). Otherwise, it proceeds to step C.

  3. Passes the data to a program, or series of programs, for final processing. These programs are known as ‘filters‘, and are responsible for converting the PostScript data into the printer's native language.

    The first filter, in most configurations, is "pstoraster", which uses GhostScript to convert the PostScript data into an intermediate format called "CUPS-Raster". (This format is supported by GhostScript as one of its available output formats.)

    The CUPS-Raster data is then passed to another program which knows how to convert it into printer-specific data. (This latter program can thus, in a sense, be considered the actual printer ‘driver’.) CUPS has a few built- in programs for some common printer languages (generic support only), but more commonly an external driver package will be used. The largest such driver package is called "Gutenprint" (formerly called "gimp-print", as it was originally developed for The GIMP), which provides support for a large number of (mostly inkjet) printers. Other packages include HPLIP and Splix.

    As it happens, GhostScript itself includes a number of printer drivers which aren't available in other packages like Gutenprint. In this case, the PostScript data can be converted directly to printer-specific format, rather than going through the process of CUPS-Raster --> external driver package. In cases like this, an alternative filter called "foomatic-rip" (or simply "Foomatic") gets called instead of pstoraster. Using instructions in the PPD file, Foomatic calls GhostScript in order to convert the PostScript data — not into CUPS-Raster format, but directly into the printer's native format instead. The usual second step of calling an external driver package is thus omitted. (Note that printers which use Foomatic for their drivers require a special PPD file with the required instructions.)

    Whatever filters are called, at the end of this phase, CUPS should have a printer data file which is now in the printer's own native format, ready for actual printing.

  4. Passes the printer data to the ‘backend‘. This is the term used for CUPS's internal equivalent of a port driver: it controls the physical communication with the printer. Available backends include:
    • USB, for USB-connected printers.
    • IPP, for network printers on a TCP/IP network.
    • SMB, for network printers being managed by a CIFS server like Samba.

  5. The backend passes the data to the printer, and the job is finally printed.

A flowchart showing the various steps in more detail can be seen here.

See below for a more simplified flowchart which shows how these steps fit into the eCups framework under OS/2.


1.5. How does CUPS fit into OS/2?

All CUPS printers are managed by the CUPS daemon, which is responsible for the whole process between receiving the initial job (in PostScript format), through all the filters and converters, to the backend whence it is passed off to the actual printer.

Once a printer is configured in CUPS, it is possible to print test pages from the CUPS administration GUI, as well as send files (or at least those in one of the supported formats) directly to the CUPS printer from a command line using the cupslpr utility.

To print from OS/2 applications, however, it is necessary to create a normal OS/2 printer object.

Wait! you ask. If we can already print files to the CUPS printer, why is it necessary to create an OS/2 printer as well?

Well, we can print using CUPS's own internal tools. The OS/2 printer object will be needed for the more general case. Basically, normal OS/2 (Presentation Manager) applications only know how to print to an OS/2 printer queue. They know nothing about any CUPS printers. So all our programs will be printing to our standard OS/2 printer object, and that gets sent on to CUPS.

How does that work? Well, we can redirect the jobs that get sent to an OS/2 printer so they end up going through CUPS. The OS/2 printing subsystem actually provides a mechanism for doing this, via a custom port driver. Instead of configuring the printer for LPTx or COMx, eCups includes a port driver, CUPS.PDR, which passes all jobs on to the CUPS daemon.

There's more; remember that CUPS needs the print jobs it receives to be in PostScript format before it can process them. CUPS does know how to convert a few specific file types into PostScript on its own, but it's not designed to handle the GPI format generated by most OS/2 applications. Happily, the OS/2 printer drivers are specifically designed to handle GPI data... and the PostScript printer driver in particular generates — naturally — a PostScript file, which then gets handed off to the printer. So, we just pass that file along to CUPS.

It's certainly possible to use the standard OS/2 PostScript driver for this. However, the eCups team has provided an updated PostScript driver called ECUPS.DRV; this is actually based on the standard PostScript driver, but with various fixes and other improvements to make it work with CUPS more smoothly.

The general flow of operation thus looks something like the following (greatly simplified, of course): 

+-------------+
| Application |
+-------------+
       |
       | (OS/2-GPI printer format)
       |
*======|=================== OS/2 PRINTER OBJECT =============================*
#      |                                                                     #
#      v                                                                     #
#   +---------------------------------------+                                #
#   | PostScript printer driver (ECUPS.DRV) |                                #
#   +---------------------------------------+                                #
#                                    |                                       #
#                                    | (PostScript data)                     #
#                                    v                                       #
#                      +-----------------------------+                       #
#                      | CUPS port driver (CUPS.PDR) |                       #
#                      +-----------------------------+                       #
#                                    |                                       #
*====================================|=======================================*
                                     |
*======================= CUPS =======|=======================================*
#                                    |                                       #
#                                    | (Incoming PostScript data) (A)        #
#                                    v                                       #
#                            +---------------+                               #
#                            | 'pstops' (B)  |                               #
#                            +---------------+                               #
#                                    |                                       #
#                                    | (Printer-specific PostScript data)    #
#                                    |                                       #
#                                    |                                       #
#      PostScript printer?           |       Built in GhostScript driver?    #
#          +------------------------< >---------------------+                #
#          |                         |                      |                #
#          |       CUPS or 3rd-party | driver module?       |                #
#          |                         |                      v                #
#          |                         v                +--------------------+ #
#          |                +------------------+      | 'foomatic-rip' (C) | #
#          |                | 'pstoraster' (C) |      +--------------------+ #
#          |                +------------------+                   |         #
#          |                         |                             |         #
#          |                         | (CUPS-Raster format)        |         #
#          |                         v                             |         #
#          |           +-----------------------------+             |         #
#          |           | Printer-specific driver (C) |             |         #
#          |           +-----------------------------+             |         #
#          |                         |                             |         #
#          | (PostScript)            | <-(Printer-native format)-> |         #
#          |                         |                             |         #
#          v                         v                             v         #
#    +------------------------------------------------------------------+    #
#    | CUPS backend (parallel/serial/USB/IPP/LPD/SMB/AppleTalk/etc. (D) |    #
#    +------------------------------------------------------------------+    #
#                                    |                                       #
*====================================|=======================================*
                                     |
                                     V
                              +-------------+
                              | PRINTER (E) |
                              +-------------+

The box labelled "CUPS" indicates components which are part of the cross- platform CUPS system. The whole diagram, with the exception of the application at the top and the printer at the bottom, comprises the eCups framework.


1.6. What limitations does eCups have?

CUPS involves a long and exceedingly complex chain of interlocking stages, many of which consist of separate programs. If something goes wrong somewhere along the line, it can be very difficult to pinpoint the failing component.

At the moment, installing and configuring eCups is a lengthy and sometimes difficult process.

Due to the lack of properly-integrated OS/2 tools, configuring and managing CUPS is also awkward. Simply creating a new printer, for example, is tedious and often confusing.


1.7. Are there any known problems with eCups?

  • Importing certain (mostly Foomatic) PPD files into ECUPS.DRV can cause the OS/2 spooler to crash when printing. Until a fix is found, you should be able to use the Generic PostScript Printer driver.

  • Printing to printers which use Foomatic plus a built-in GhostScript driver doesn't work properly just yet: the print job may abort about 99% of the way through (resulting in the last few words/characters being cut off).

    This problem is currently under investigation. In the meantime, it does not seem to occur when printing files which are already in either PS or PDF format; therefore, one workaround is to print to a PostScript file first (by selecting "output to file" on the output port page of the OS/2 printer object's properties), and then print the file manually using cupslpr or gsview. (This has only been tested with single-page documents.)

    (Similarly, in programs like OpenOffice, which have the option of exporting directly to PDF, you can generate a PDF file which can be printed from cupslpr or Lucide.)


2. Configuration & Use


2.1. How do I set up eCups on my system?

Check out the eCups HOWTO, which provides detailed instructions, including screenshots.


2.2. What printers are supported?

When you go to add a new printer in the CUPS web interface, you will see a list of supported printer models, arranged by manufacturer. CUPS gets this list from all the driver packages which you have installed (like Gutenprint), plus the small number of generic drivers which CUPS includes natively.

Of course, some printers may be supported by driver packages which you don't currently have installed, in which case you won't see it in CUPS (until you install the required software). A good way to check for support for a particular printer model is to check the OpenPrinting Database. Keep in mind, though, that not all of the CUPS driver packages out there have been ported to OS/2 (and not all of them are open source in any case.)


2.3. How do I install support for a printer which isn't listed?

First, you need to find out if a CUPS driver for your printer (or a compatible model) actually exists. The best place to find out is by looking through the printer list on the OpenPrinting web site.

If you've determined that your printer is supported, you will need make sure that the driver package required is installed. Currently, the following driver packages are available for eCups:

  • Gutenprint
  • Splix
  • HPLIP
  • Foomatic/Ghostscript built-in (only partially working at the moment)

Go to the CupsPort page to download them.

You may also need to download the appropriate CUPS PPD file, if the support hasn't been included in the driver package already. The OpenPrinting site (see link above) is your place to go for these.

Finally, you have to install the support for your printer in CUPS and OS/2. In general terms, you need to do the following:

  1. Install the driver package; consult its documentation for details.
  2. Create a new printer in CUPS. Either select your printer if it's listed, or import the PPD file if not.
  3. If the printer isn't listed in the eCups printer driver, you will also need to import the PPD into ECUPS.DRV using the PIN utility.
  4. Create an OS/2 printer object using the newly-added printer driver.
  5. Create a new CUPS port which points to the new printer in CUPS, and select it as the output port in the OS/2 printer object.

The eCups HOWTO describes these steps in more detail.


2.4. Where can I find PPD files?

Browse the printer list on the OpenPrinting web site.


2.5. I can't import my PPD into ECUPS.DRV, what should I do?

One may occasionally encounter a PPD file which can be imported into CUPS without problems, but which the OS/2 printer driver (ECUPS.DRV) chokes on.

If this happens to you, you can simply use the "Generic PostScript Printer" driver for the OS/2 printer object. Since CUPS is designed to operate on generic PostScript files, this should work just fine, as long as CUPS itself is properly configured to support your printer.

The main disadvantage of doing it this way is that you will be unable to set any printer-specific options in the OS/2 printer object or from the standard OS/2 job properties dialog. If you need to change the printer options, you will have to do so from the CUPS administration GUI.


2.6. What's the difference between all these network device types (ipp://, lpd://, socket://, etc.)?

CUPS supports several different types of network connection to a printer. Basically, you should choose whichever one your printer (or the print server it's connected to) supports best.

ipp://
IPP or Internet Printing Protocol. This is a modern TCP/IP protocol for networking printers which was designed to replace the much older LPD. It supports many features which the LPD and AppSocket do not, including encryption, authentication, and job control. Not all print servers may support it, however.

lpd://
This is the venerable TCP/IP Line Printing Daemon protocol. Virtually all TCP/IP network printers and print servers should support it.

socket://
AppSocket (or "JetDirect") protocol over TCP/IP. Originally developed by HP but supported by many network printers as well as hardware print servers.

smb://
SMB protocol, as used by Windows Networking, OS/2 Peer and LAN Server, and Samba.

If your printer is being shared by a Windows, OS/2 Peer, LAN Server, or Samba file/print server, then you will probably need to use SMB (see question 2.11). Otherwise, choose whichever of the TCP/IP-based protocols your printer (or its print server) supports best.

Of course, it's quite likely that more than one of them is supported. In this case, you may want to consult the documentation that came with your printer/server (or ask your network administrator) to see if any of them is recommended specifically.

In general, IPP supports the most features, AppSocket/JetDirect has the best performance, and LPD is the most widely available.


2.7. What are the "Simplified" printer drivers for?

Gutenprint provides many of its printer drivers (through its included PPD files) in both normal and "Simplified" versions.

The Gutenprint user's manual explains the difference:

The "simplified" PPD files offer a basic set of options only, for selecting printer options, standard paper sizes, and basic quality settings. The PPD files that are not "simplified" offer a much broader set of controls, giving the user extensive control over quality and color adjustment.
— Gutenprint 5.x user's manual

The Simplified drivers should be adequate for most peoples' needs.


2.8. Why do I need to create both a CUPS printer and an OS/2 printer object?

OS/2 Presentation Manager programs only know how to print to an OS/2 printer object (or rather, to an OS/2 print queue, which is what the printer object defines). They know nothing about CUPS printers.

(Obviously, you can print directly to the CUPS printer using CUPS-specific tools like cupslpr or the CUPS web interface. But that doesn't help us with the general case.)

Creating an OS/2 printer object gives applications somewhere to send their print jobs. What we do in this case is configure that printer object to redirect all its jobs to CUPS. This is done by setting the printer output port to a CUPSx port, which you must configure with the name of the corresponding printer defined in CUPS.

To put it more simply: OS/2 printer objects know how to receive print jobs from applications. CUPS knows how to send that data to the actual printer. So they have to work together in tandem in order for printing to work.

In an ideal world, a corresponding OS/2 printer object would be created for you automatically whenever you created a new printer in CUPS. Unfortunately, there is no way to do this just at the moment, so you have to create them both separately yourself.


It may also strike you as confusing that you can't simply add support for your printer by importing the PPD into the ECUPS or PSCRIPT driver (as you can with non-CUPS printers). After all, the driver now lists your printer as supported, just as it does for native printers... so what's the problem?

The thing is, what the driver lists as supported isn't the true printer — it's the PostScript-emulated version of that printer presented by CUPS. It depends on going through CUPS in order to translate it into the printer's actualy format. If you were to select a CUPS-based printer driver and then try printing directly to the printer (instead of going through the eCups port driver), the printer wouldn't understand the job and would either reject it or start spewing out garbage. (Unless, of course, it really is a PostScript printer.)


2.9. Where should I define the printer settings: in the OS/2 printer properties, or in CUPS?

In principle, you can set your preferred printer settings in either the OS/2 printer object or in CUPS itself.

When you configure options in the OS/2 printer object, the resulting PostScript file which gets sent on to CUPS will have those settings defined. In this case, CUPS should respect them.

The settings in CUPS itself (which you can configure through the web administration GUI) can be thought of as fall-back defaults. Any options which you set in the OS/2 printer object (or in the job properties dialog which most applications will offer you before printing) should take priority. Options which were not set in the printer object (and which are thus not defined in the PostScript file which CUPS receives) will fall back to the CUPS-configured defaults.

Just to avoid confusion, it's a good idea to keep both the printer object defaults and the internal CUPS defaults synchronized with each other.


2.10. How do I upgrade to a new version?

It depends on which specific component you are upgrading:

CUPS
Make sure you stop the CUPS Daemon (cupsd.exe) if it is running.

Generally, you can just unzip the new cups-*.zip over your previous installation. You should back up the existing \cups directory tree first, though.

If you'd rather install cleanly (while preserving your setup), do the following:

  1. Rename your current \cups directory tree.
  2. Unzip the new cups-*.zip — a new \cups tree will be created.
  3. Copy the following files over from your previous (renamed) \cups directory tree:
    • etc/cups/ppd/*
    • etc/cups/printers.conf
    • etc/cups/classes.conf — only necessary if you have classes (printer groups) defined
    • etc/cups/snmp.conf — only necessary if you have customized SNMP settings
    • etc/cups/local.convs, if it exists
    • etc/cups/local.types, if it exists
  4. Either reinstall Gutenprint (by re-unzipping gutenprint-*.zip to the same root directory as CUPS), or else copy the following files over from your previous (renamed) CUPS installation:
    • cups/etc/cups/command.types
    • cups/lib/cups/driver/gutenprint.version.exe
    • cups/lib/cups/filter/commandtocanon.exe
    • cups/lib/cups/filter/commandtoepson.exe
    • cups/lib/cups/filter/rastertogutenprint.version.exe
    • cups/share/cups/calibrate.ppm
    • cups/share/cups/model/gutenprint/*
  5. Reinstall the foomatic and/or foo2qpdl packages if you had them installed. (Again, simply unzipping them to the same root directory as CUPS should be sufficient.) You should also copy the file cups/etc/foomatic/filter.conf over from your previous (renamed) CUPS installation.
  6. Restore any configuration options you have defined (and want to keep) from etc/cups/cupsd.conf in your previous (renamed) CUPS instalation. You can probably just copy the file over, but you should generally compare it with the new (default) version provided by CUPS, in case the new version has new or changed items/syntax that should be taken into account.

After upgrading (either way), check the file \cups\lib\cups\filter\pstoraster and make sure the "prefix=" line points to your correct GhostScript path.

Finally, start the CUPS Daemon (cupsd.exe), then go into the web administration GUI and double-check that your printers and settings are correct.

(If everything works properly, you can delete any backed-up/renamed previous versions of CUPS. It's a good idea to run with the new version for a while before doing this, however.)

CUPS.PDR
Copy the new version of CUPS.PDR over the old one (probably located in \OS2\DLL). Note that you will probably first need to unlock ECUPS.DRV using a tool like unlock or replmod, or else boot from another partition/CD.

ECUPS.DRV
Unzip the ecups-*.zip file over the existing files (in \OS2\DLL\ECUPS).

GhostScript
You should be able to unzip gs*.zip alongside the old installation; the new version should be installed under a new subdirectory of \gs.

After unzipping the new version, edit the file (in your CUPS installation) \cups\lib\cups\filter\pstoraster, and change the "prefix=" line to point to the new GhostScript path.

If you have GSView installed, and want to make it use the new version of GhostScript (recommended), run GSView and go into "Options" --> "Advanced Configure". Make sure the "GhostScript include path" is updated to point to the new GhostScript directory. (See the file readme.os2 included with GhostScript for what this path should look like in general.)

Once you have everything changed over to use the new GhostScript, and you've verified that it all works properly, you can delete the old GhostScript subdirectory.

Gutenprint
TODO


2.11. How do I connect to a SMB printer?

To set up a printer using the SMB/CIFS (i.e. Peer/Samba/Windows network) protocol, an extra step is required.

Specifically, you need to obtain the file smbspool.exe from the OS/2 Samba client port. Rename this file to smb.exe and place it in the /cups/lib/cups/backend directory. The next time you go into the "Add printer" page in the CUPS Adminstration GUI, you should see a new option for "Windows or SAMBA" printer listed.

Enter the URI in the form: 

smb://username:password@hostname/queue


3. Troubleshooting


3.1. How do I diagnose printing problems?

First of all, go into the CUPS web GUI by pointing your browser at http://localhost:631.

The best place to go first is probably the Printers page. Each defined printer will show its current status; if a printer error was received by CUPS, that printer will show the error message under the status column.

For more detailed information, go to the Administration page. There's a button on that page called "View Error Log", which will show you all errors and warnings that were recently logged by CUPS.

For even more detailed diagnostics, you can enable the checkbox labelled "Save debugging information for troubleshooting". (Changing this setting requires the CUPS daemon to be restarted.) Of course, this setting is only useful if it was enabled before the error occurred... so if you decide to activate it, you'll presumably want to resubmit whatever job caused the error you're trying to diagnose.

Reading the error log (with or without debug information enabled) can be a bit intimidating to the uninitiated. It's not all that hard to work out with a bit of practise, however.

Note: See TracWiki for help on using the wiki.