CUPS Software Users Manual
Author: Easy Software Products
Description: Common UNIX Printing System Software Users Manual

# Preface

This software users manual describes how to use the Common UNIX Printing System ("CUPS") Version 1.0.4.

## System Overview

The Common UNIX Printing System provides a portable printing layer for UNIX® operating systems. It has been developed by Easy Software Products to promote a standard printing solution for all UNIX vendors and users. CUPS provides the System V and Berkeley command-line interfaces.

CUPS uses the Internet Printing Protocol (IETF-IPP) as the basis for managing print jobs and queues. The Line Printer Daemon (LPD, RFC1179), Server Message Block (SMB), and AppSocket protocols are also supported with reduced functionality.

CUPS adds network printer browsing and PostScript Printer Description ("PPD")-based printing options to support real world applications under UNIX.

CUPS also includes a customized version of GNU GhostScript (currently based off GNU GhostScript 4.03) and an image file RIP that can be used to support non-PostScript printers.

## Document Overview

This software users manual is organized into the following sections:

- 1 - Printing System Overview
- 2 - Using the Printing System
- 3 - Standard Printer Options
- 4 - Checking the Status Via the Web

# 1 - Printing System Overview

This chapter provides an overview of how the Common UNIX Printing System works.

## The Printing Problem

For years the printing problem has plagued UNIX®. Unlike Microsoft® Windows® or MacOS, UNIX has no standard interface or system in place for supporting printers. Among the solutions previously available, the Berkeley and System V printing systems are the most prevalent.

These printing systems support line printers (text only) or PostScript printers (text and graphics), and with some coaxing they can be made to support a full range of printers and file formats. However, because each varient of the UNIX operating system uses a different printing system than the next, developing printer drivers for a wide range of printers is extremely difficult. That combined with the limited volume of customers for each UNIX varient has forced most printer vendors to give up supporting UNIX entirely.

The Common UNIX Printing System, or CUPS, is designed to eliminate the printing problem. One common printing system can be used by all UNIX varients to support the printing needs of users. Printer vendors can use its modular filter interface to develop a single driver program that supports a wide range of file formats with little or no effort. Since CUPS provides both the System V and Berkeley printing commands, users (and applications) can reap the benefits of this new technology with no changes.

## The Technology

CUPS is based upon an emerging Internet standard called the Internet Printing Protocol, or IPP. IPP has been embraced by dozens of printer and printer server manufacturers, and will be supported by the next Microsoft Windows operating system.

IPP defines a standard protocol for printing as well as managing print jobs and printer options like media size, resolution, and so forth. Like all IP-based protocols, IPP can be used locally or over the Internet to printers hundreds or thousands of miles away. Unlike other protocols, however, IPP also supports access control, authentication, and encryption, making it a much more secure printing solution than older ones.

IPP is layered on top of the Hyper-Text Transport Protocol, or HTTP, which is the basis of web servers on the Internet. This allows the user to view documentation and status information on a printer or server using their web browser.

CUPS provides a complete IPP/1.0-based printing system that provides Basic authentication and domain or IP-based access control. Digest authentication and TLS encryption will be available in future versions of CUPS.

## Jobs

Each file that is submitted for printing is called a job. Jobs are identified by a unique number starting at 1 and are assigned to a particular destination (usually a printer). Jobs can also have options associated with them such as media size, number of copies, and priority.

## Classes

CUPS supports collections of printers known as classes. Jobs sent to a class are forwarded to the first available printer in the class.

## Filters

Filters allow a user or application to print many types of files without extra effort. Print jobs sent to a CUPS server are filtered before sending them to a printer. Some filters convert job files to different formats that the printer can understand. Others perform page selection and ordering tasks. Backend filters perform the most important task of all - they send the filtered print data to the printer.

CUPS provides filters for printing many types of image files, HP-GL/2 files, PDF files, and text files. CUPS also supplies PostScript and image file Raster Image Processors, or RIPs, that convert PostScript or image files into bitmaps that can be sent to a raster printer.

CUPS provides backends for printing over parallel and serial ports, and over the network via the JetDirect (AppSocket), Server Message Block, and Line Printer Daemon protocols.

## Printer Drivers

Printer drivers in CUPS consist of one of more filters specific to a printer. CUPS includes a sample printer driver for Hewlett-Packard LaserJet and DeskJet printers. While this driver does not generate optimal output for different printer models, it does demonstrate how you can write your own printer drivers and incorporate them into CUPS.

## Networking

Printers and classes on the local system are automatically shared with other systems on the network. This allows you to setup one system to print to a printer and use this system as a printer server or spool host for all of the others. If there is only one occurrence of a printer on a network, then that printer can be accessed using its name alone. If more than one printer exists with the same name, users must select the printer by specifying which server to use (e.g. "printer@host1" or "printer@host2".)

CUPS also provides implicit classes, which are collections of printers and/or classes with the same name. This allows you to setup multiple servers pointing to the same physical network printer, for example, so that you aren't relying on a single system for printing. Because this also works with printer classes, you can setup multiple servers and printers and never worry about a "single point of failure" unless all of the printers and servers goes down!

# 2 - Using the Printing System

This chapter shows you how to submit, query, and cancel print jobs to different printers.

## Submitting Files for Printing

CUPS provides both the System V (`lp`) and Berkeley (`lpr`) printing commands. To print a file to the default printer on the system (or your only printer if you have only one) you just need to type:

    % lp filename ENTER

or:

    % lpr filename ENTER

CUPS understands many different types of files directly, including PostScript and image files. This allows you to print from inside your applications or at the command-line, whichever is most convenient!

## Choosing a Printer

Many systems will have more than one printer available to the user. These printers can be attached to the local system via a parallel or serial port, or available over the network.

To see a list of available printers, use the `lpstat` command:

    % lpstat -p -d ENTER

The "-p" option specifies that you want to see a list of printers, and the "-d" option reports the current system default printer or class.

To print to a specific printer, use the "-d" option to the `lp` command:

    % lp -d printer filename ENTER

or the "-P" option to the `lpr` command:

    % lpr -P printer filename ENTER

## Setting Printer Options

For many types of files, the default printer options may be sufficient for your needs. However, there may be times when you need to change the options for a particular file you are printing.

The `lp` command allows you to pass printer options using the "-o" option:

    % lp -o landscape -o scaling=75 -o media=A4 filename.jpg

The `lpr` command has no command-line option for printer options.

The available printer options vary depending on the printer. The standard options are described in Chapter 3.

## Printing Multiple Copies

Both the `lp` and `lpr` commands have options for printing more than one copy of a file:

    % lp -n num-copies filename ENTER
    % lpr -#num-copies filename ENTER

Copies are normally not collated for you. To get collated copies use the `lp` command with the "-o Collate=True" option:

    % lp -n num-copies -o Collate=True filename ENTER

## Checking the Printer Status from the Command-Line

The `lpstat` command can be used to check for jobs that you have submitted for printing:

    % lpstat ENTER
    Printer-1 johndoe 4427776
    Printer-2 johndoe 15786
    Printer-3 johndoe 372842

The jobs are listed in the order they will be printed. To see which files and printers are active, use the "-p" option:

    % lpstat -p ENTER
    printer DeskJet now printing DeskJet-1.

Or to show the jobs and the printers, use the "-o" and "-p" options:

    % lpstat -o -p ENTER
    Printer-1 johndoe 4427776
    Printer-2 johndoe 15786
    Printer-3 johndoe 372842
    printer DeskJet now printing DeskJet-1.

## Checking the Printer Status from the Web

Since CUPS uses the Internet Printing Protocol, it is also a full-featured web server. To use your web browser to monitor the printers on your system, open the URL "http://localhost:631". From there you can view the status of classes, jobs, and printers with the click of a button!

## Canceling a Print Job

The `cancel` command cancels a print job:

    % cancel job-id ENTER

The job-id is a number that was reported to you by the `lp` or `lpstat` commands.

# 3 - Standard Printer Options

This chapter describes the standard printer options that are available when printing with the `lp` command.

## General Options

The following options apply when printing all types of files.

### Selecting the Media Size, Type, and Source

The "-o media=xyz" option sets the media size, type, and/or source:

    % lp -o media=Letter filename ENTER
    % lp -o media=Letter,MultiPurpose filename ENTER
    % lp -o media=Letter,Transparency filename ENTER
    % lp -o media=Letter,MultiPurpose,Transparency filename ENTER

The available media sizes, types, and sources depend on the printer, but most support the following options (case is significant):

- `Letter` - US Letter (8.5x11 inches, or 216x279mm)
- `Legal` - US Legal (8.5x14 inches, or 216x356mm)
- `A4` - ISO A4 (8.27x11.69 inches, or 210x297mm)
- `COM10` - US #10 Envelope (9.5x4.125 inches, or 241x105mm)
- `DL` - ISO DL Envelope (8.66x4.33 inches, or 220x110mm)
- `Transparency` - Transparency media type or source
- `Upper` - Upper paper tray
- `Lower` - Lower paper tray
- `MultiPurpose` - Multi-purpose paper tray
- `LargeCapacity` - Large capacity paper tray

The actual options supported are defined in the printer's PPD file in the `PageSize`, `InputSlot`, and `MediaType` options.

### Setting the Orientation

The "-o landscape" option will rotate the page 90 degrees to print in landscape orientation:

    % lp -o landscape filename ENTER

### Printing On Both Sides of the Paper

The "-o sides=two-sided-short-edge" and "-o sides=two-sided-long-edge" options will enable duplexing on the printer (if the printer supports it.) The "two-sided-short" option is suitable for landscape pages, while the "two-sided-long" option is suitable for portrait pages:

    % lp -o sides=two-sided-short-edge filename ENTER
    % lp -o sides=two-sided-long-edge filename ENTER

### Selecting a Range of Pages

The "-o page-ranges=pages" option selects a range of pages for printing:

    % lp -o page-ranges=1 filename ENTER
    % lp -o page-ranges=1-4 filename ENTER
    % lp -o page-ranges=1-4,7,9-12 filename ENTER

As shown above, the pages value can be a single page, a range of pages, or a collection of page numbers and ranges separated by commas. The pages will always be printed in ascending order, regardless of the order of the pages in the "page-range" option.

To select the even or odd pages, use the "-o page-set=set" option:

    % lp -o page-set=odd filename ENTER
    % lp -o page-set=even filename ENTER

### N-Up Printing

The "-o number-up=value" option selects N-Up printing. N-Up printing places multiple document pages on a single printed page. CUPS supports 1-Up, 2-Up, and 4-Up formats:

    % lp -o number-up=1 filename ENTER
    % lp -o number-up=2 filename ENTER
    % lp -o number-up=4 filename ENTER

The default format is 1-Up.

### Setting the Brightness

You can control the overall brightness of the printed output using the "-o brightness=percent" option:

    % lp -o brightness=120 filename ENTER

Values greater than 100 will lighten the print, while values less than 100 will darken it.

### Setting the Gamma Correction

You can control the overall gamma correction of the printed output using the "-o gamma=value" option:

    % lp -o gamma=1700 filename ENTER

Values greater than 1000 will lighten the print, while values less than 1000 will darken it. The default gamma is 2200 which matches the sRGB specification.

## Text Options

The following options apply when printing text files.

### Setting the Number of Characters Per Inch

The "-o cpi=value" option sets the number of characters per inch:

    % lp -o cpi=12 filename ENTER

### Setting the Number of Lines Per Inch

The "-o lpi=value" option sets the number of lines per inch:

    % lp -o lpi=8 filename ENTER

### Setting the Number of Columns

The "-o columns=value" option sets the number of text columns:

    % lp -o columns=2 filename ENTER

### Setting the Page Margins

Normally the page margins are set to the hard limits of the printer. To adjust the page margins use the "-o page-left=value", "-o page-right=value", "-o page-top=value", and "-o page-bottom=value" options:

    % lp -o page-left=value filename ENTER
    % lp -o page-right=value filename ENTER
    % lp -o page-top=value filename ENTER
    % lp -o page-bottom=value filename ENTER

The value argument is the margin in points; each point is 1/72 inch or 0.35mm.

### Pretty Printing

The "-o prettyprint" option puts a header at the top of each page with the page number, job title (usually the filename), and the date. Also, C and C++ keywords are highlighted, and comment lines are italicized:

    % lp -o prettyprint filename ENTER

## Image Options

The following options apply when printing image files.

### Scaling the Image

The "-o scaling=percent" and "-o ppi=value" options change the size of a printed image:

    % lp -o scaling=percent filename ENTER
    % lp -o ppi=value filename ENTER

The scaling percent is a number from 1 to 800 specifying the size in relation to the page (not the image.) A scaling of 100 percent will fill the page as completely as the image aspect ratio allows. A scaling of 200 percent will print on up to 4 pages.

The ppi value is a number from 1 to 1200 specifying the resolution of the image in pixels per inch. An image that is 3000x2400 pixels will print 10x8 inches at 300 pixels per inch, for example. If the specified resolution makes the image larger than the page, multiple pages will be printed to satisfy the request.

### Adjusting the Hue (Tint) of an Image

The "-o hue=value" option will adjust the hue of the printed image, much like the tint control on your television:

    % lp -o hue=value filename ENTER

The value argument is a number from -360 to 360 and represents the color hue rotation. The following table summarizes the change you'll see with different colors:

Original | hue=-45 | hue=45
--- | --- | ---
Red | Purple | Yellow-orange
Green | Yellow-green | Blue-green
Yellow | Orange | Green-yellow
Blue | Sky-blue | Purple
Magenta | Indigo | Crimson
Cyan | Blue-green | Light-navy-blue

### Adjusting the Saturation (Color) of an Image

The "-o saturation=percent" option adjusts the saturation of the colors in an image, much like the color knob on your television:

    % lp -o saturation=percent filename ENTER

The percent argument specifies the color saturation from 0 to 200. A color saturation of 0 produces a black-and-white print, while a value of 200 will make the colors extremely intense.