Volume Number: 22 (2006)
Issue Number: 10
Column Tag: CUPS

My CUPS Runneth Over

Taking the power of printing to the next level in Macintosh OS X

by Philip Rinehart

Included with Mac OS X since the release of Jaguar, the Common Unix Printing System, CUPS, gives a system administrator great flexibility and power. Many Unix system administrators are quite familiar with the intricacies of this system. Mac OS X takes advantage of this flexibility, while at the same time providing a very simple interface for printer management. In this article, we will delve deeper, examining the command line for use in printer management in OS X. As an added bonus, managing printers from the command line works both on Macintosh OS X and Macintosh OS X Server! Let's begin by recapping the printer interface as it appears in Tiger.

The Printer Setup Utility is an evolved beast. When first introduced as Print Center in Jaguar, many options were not present. With each release of the operating system, more options have been added, allowing for greater printer control. Figure 1 shows the interface as it appears in Tiger:

It appears pretty normal, eh? The obvious things are here: Adding a printer, Colorsync, Utility, and Show Info. Each item is pretty straightforward. How does this relate to CUPS though? All in due time... More interesting options now appear in the Add Printer box. By default, various types of printers are omitted from the Add Printer dialog. Clicking on the More Printers button allows users to add many more types of printers, including Bluetooth, SMB (Windows), Appletalk, and other printers using TCP/IP protocols that do not use the Line Printer Daemon (LPD), or Bonjour. Prior to Tiger, adding these types of printers required using a special key combination.

Even more options are available in the Printers Menu Item. Figure 2 shows the options that are available.

A lot of new options have appeared in Tiger, let's now begin to see how they can tie to the command line.

So, you ask, why would I want to use the command line instead of using the Printer Setup Utility application? What if you are attempting to administer a remote site? How about using the Send Unix command in Apple Remote Desktop? Removing stuck jobs from a printer? The list goes on. Often, an administrator may be able to accomplish many common tasks using their preferred administration tools, be it ssh, ARD, or some other way of delivering custom user settings. Using Figure 2 as a point of reference, each option can be accomplished with the command line. For simplicities sake, all the command line options below assume that at least one printer has been added to the system with the Printer Setup Utility.

The first option, Make Default is relatively simply accomplished using either lpoptions or lpadmin. In this case, lpadmin makes more sense, as it will be the basis for many of the other command line tasks in this article. Here's the command:

lpadmin -d printer_name

Simple. Well, not quite. The command is fairly simple, getting the printer name is not. The queue name is typically what is needed to properly invoke this command. If the machine is being remotely administered, the queue names for all attached printers can be obtained with the lpstat command. Get ready, this command is a little long:

lpstat -v | awk '{sub(/\:/,"",$3); print $3}'

You might ask, why all the extra stuff with awk? In this case, it is simply a matter of convenience, as the printer names are all listed as known by the system. Typically, an IP printer name will be in a form similar to _192_168_1_108 when added using Printer Setup Utility. The last bit of trickiness is that Printer Setup Utility usually writes a file to the user's home directory that will override any setting that you send to the client machine. This file, .lpoptions, can be removed. The alternative of course is simply place a new file with this name on the client machine in the users home directory with the word Default before the printer name. If a global setting is what you are after, create this file in /etc/cups. Name the file here lpoptions. Always remember though, a local .lpoptions file will always override any global setting.

For now, skip the Add Printer option. Moving to the delete printer menu item, it is very similar to the command for setting a default printer. Once again, the printer name is needed to delete the printer.

lpadmin -x _192_168_1_108

This command will remove the named printer from the system. Pretty simple.

Let's get a little more complex now. Printer pooling is a new concept. Consulting the CUPS documentation, there is nothing regarding printer pooling. In the CUPS documentation, printer pools are referred to as management classes. Jobs sent to a pool (class) are sent to the first available printer. In an office with all printers in a centralized location, this option could be of some use.

lpadmin -p _192_168_1_108 -p hp_color_LaserJet_5550__EABEF6_ -c myprinterpool

By now, the command should being to look somewhat familiar. The -p option simply specifies the printer name that will be added to the printer pool. Each printer must be specified when creating the class. The last option is the pool name, specified with the -c option. Once finished, a new printer pool should appear in print center. By default the printer pool will be stopped, it can be started in the same way as a printer. Read on to find out how.Configure Printer

We've looked at two of the three lynchpins for command line cups administration. The last command, lpoptions is used to view settings for a named printer. The command syntax is quite similar to lpadmin. Let's look at a command,

lpoptions -l -p 192_168_1_108

This command will return all of the available options for the printer model. It will look similar to the following output:

HPPaperPolicy/Fit to Page: *PromptUser NearestSizeAdjust NearestSizeNoAdjust
InstalledMemory/Total Printer Memory: *8MB 16MB 24MB 32MB 48MB 64MB
HPwmSwitch/Watermark/Overlay: *Off Watermark Overlay
HPwmPages/Watermark Pages: *AllPages FirstPage
HPwmTextMessage/Watermark Text: *Draft CompanyConfidential CompanyProprietary CompanyPrivate 
   Confidential Copy Copyright FileCopy Final ForInternalUse Preliminary Proof ReviewCopy Sample 
   TopSecret Urgent Set
HPwmFontName/Watermark Font: CourierB *HelveticaB TimesB
HPwmFontSize/Watermark Size (points): pt24 pt30 pt36 pt42 *pt48 pt54 pt60 pt66 pt72 pt78 pt84 pt90
HPwmTextAngle/Watermark Angle: Deg90 Deg75 Deg60 *Deg45 Deg30 Deg15 Deg0 DegN15 DegN30 DegN45 DegN60 
   DegN75 DegN90
HPwmTextStyle/Watermark Style: Thin *Medium Thick Halo Fill
HPwmBrightness/Watermark Intensity: Darkest Darker Dark MediumDark *Medium MediumLight Light Lighter 
   Lightest
Smoothing/Resolution Enhancement: *PrinterDefault On Off
PageSize/Media Size: *Letter LetterSmall Executive Legal LegalSmall A4 A4Small A5 A6 ISOB5 B5 
   w612h936 Postcard DoublePostcard w558h774 Env10 EnvMonarch EnvDL EnvC5 EnvISOB5 Custom
PageRegion/PageRegion: Letter LetterSmall Executive Legal LegalSmall A4 A4Small A5 A6 ISOB5 B5 
   w612h936 Postcard DoublePostcard w558h774 Env10 EnvMonarch EnvDL EnvC5 EnvISOB5
InputSlot/Media Source: *Upper
ManualFeed/Tray 1 (Manual): True *False
HPHalftone/Levels of Gray: *PrinterDefault Enhanced Standard
Resolution/Printer Resolution: 1200x1200dpi *600x600x2dpi 600x600dpi 300x300dpi
HPEconoMode/EconoMode: *PrinterDefault True False

These options are usually directly from the PPD file for the printer. Choosing a specific option from the above list, the resolution of the printer can be set with lpadmin using this command:

lpadmin -p _192_168_1_108 -o Resolution=1200x1200dpi

Unfortunately, many of these options are not exposed in the Printer Setup Utility. Additionally, the most useful tool, page size, cannot be set from the command line, as a Preference plist is actually used by the OS X printing system.

A lot of the remaining menu options can be accomplished with a single line command. Stopping jobs requires one line disable printername. Restarting the queue is just as easy, instead of disable printername use enable printername. Once you open the Printer Setup Utility using either command, the state of the print queue will be stopped or started based on the command entered. Earlier, printer pools were discussed. Here's how you enable the printer pool, use the command above, and substitute the pool name for the printername. Once you have enabled the queue or pool, it needs to be configured to accept or reject print jobs. The command is identical in syntax to enabling or disabling, use accept/reject printername to allow the printer to accept or reject jobs.

Getting information about a printer using the command line is also a one liner, though it does not present the information in quite the way that the Printer Setup Utility does. Type the following command, lpstat -t and a complete list of printer statuses, the default destination, and the scheduler is shown.

If you will, the gateway to the CUPS printing system is the single command lpadmin. Until now, I've compared how it can be used with the Menu options in Printer Setup Utility, drawing corollaries as appropriate. However, we have not examined it extensively. Adding printers is probably the single largest headache for a system administrator. With lpadmin, much of this barrier can be overcome without using a Desktop Management solution.

Adding a printer from the command line is probably the single most powerful use of lpadmin. If you wanted to add a printer to a group of computers with Apple Remote Desktop, lpadmin is a very quick and easy way to do so. Here's the basic command to do so:

lpadmin -p myprinter -E -v lpd://10.0.1.0/queue -m laserjet.ppd

Most of this command should look quite familiar. -p specifies the printer name. In this case though, the printer name can be any name that is descriptive. Unlike the Printer Setup Utility, the printername added with lpadmin does not have to have a form similar to 192_168_1_108. In the Printer Setup Utility, this field is the Printer Name, located in the Name & Location tab. Next we enable the printer with the -E option. It is very important that this option is entered after the printer option. If it is specified before, lpadmin will attempt to connect to the CUPS using encryption. Continuing, the most important option is -v. Why? -v provides the Uniform Resource Identifier (URI) for the printer. In the above example, lpd is being used as the printer communication protocol. Here is a list of the most common device URI's:

direct pdf700://distiller
direct pdf700
network pap
network socket
direct bluetooth
serial fax://dev/cu.Bluetooth-Modem
network epsonpap
direct epsonfirewire
network epsontcpip
serial fax
direct firewire
network http
network ipp
network lpd
direct usb
network smb
network mdns

Determining the device URI is one of the trickiest parts of adding a printer from the command line. If unsure of the device URI, add a test printer with the protocol desired. Once finished, use lpstat -t to determine the proper form. The last option -m specifies the ppd file that should be used for the printer. If none is specified, the printer will use the raw driver. The raw driver is problematic, usually causing print jobs to fail.

The model option needs closer inspection though, as it is not immediately obvious what types of printer models are supported. -m uses only models in the /usr/share/cups/model directory. It can also use any ppd file at any location on the file system as long as it is a file in ppd format. If the file is not in /usr/share/cups/model, specify the full path with this option. But wait, there's more! Mac OS X stores a whole slew of drivers in gzipped format. Try adding a ppd file stored in this way. What happens? An error is thrown by lpadmin, but the printer is still added! Look at the driver though, it is a RAW driver. Not good. Fortunately, CUPS has provided a way around this, the -P option. With this option, any gzipped file can be used. Here's an example command:

lpadmin -p printername -E -v lpd://10.0.1.0 -P /Library/Printers/PPDs/Contents/
Resources/en.lproj/Dell\ Laser\ Printer\ 3100cn.gz

As most of the printer ppd files are gzipped in Tiger, this command is probably the most useful. A couple of other command line options can be used to provide a location and custom description. The switches are -D for description, and -L for location. They are not required, but are useful for informational purposes on a client machine.

What is the next step? Adding a printer from the command line is nice, but lpadmin has a number of advanced options that benefit a system administrator.

The first option is specifying a quota for the printer. There are three types of quotas, kilobyte, page-limit, and period. The syntax for all three commands is identical,

lpadmin -p printername -o job-k-limit=1024

The three quota options can be used individually or in combination. The job-k-limit option sets a limit per kilobyte, job-page-limit restricts the number of pages that can be printed, and job-quota-period sets the time interval for quota usage. Note that the job-quota-period time interval is expressed in seconds. To enforce quotas for a single day, specify job-quota-period=86400. Quotas are applied for each individual user, but apply to every user of that printer. As an example, if the quota is set to 25 pages, every user will be able to print 25 pages on the printer. Users cannot be excluded on an individual basis from quota enforcement.

One other slight change is needed to enforce quotas on print queues. Using an editor, open the cupsd.conf file located in /etc/cups. Search for AppleQuotas. The line should be commented out, uncomment it and restart the cups daemon. Unfortunately, the OS X interface does not indicate why printing failed, either presenting no dialogue or simply stating that an error in printing has happened.

In addition to quotas, users and groups can be allowed or denied access to a printer. By now, the command to do this should look achingly familiar. Once again:

lpadmin -p printername -u deny:username,@groupname

This directive sets access controls to print queues on an allow deny basis per user. Group name restrictions use the @ symbol before the group name. Again, no meaningful feedback is provided by the OS X interface. One last piece of information: only local users on the machine can be denied access, currently it does not work if the machine is bound to a Directory Services system.

That finally finishes all of the various options that can be controlled using command line tools. With knowledge of all the various options, there are number of interesting things that can be accomplished using scripts.

To make using the command line really useful, how about a real world problem? A client machine has been bound to a Directory Service. Multiple network users are attempting to print, but the queue is stopping for some unknown reason. In this case, a system administrator can use a single command to inspect the status of the any printer. Use lpq to determine if jobs are printing, and how many entries are in the queue. Assume that the queue has a stuck job. To remove the stuck job, send the command cancel jobid. It does the trick quite nicely. If the job id is unknown, add -l for a complete listing of all jobs.

Pretty quick and dirty, and it solves the immediate problem. However, what if the queue has been stuck for some time? The printer will immediately begin to process all jobs, often resulting in unnecessary and extraneous print jobs. Extending the concept, create a logout script. Here's an example script:

#!/usr/bin/perl -wi
for (`lpstat -a`) {
        s/\s.*\n//;
        `cancel -a $_`;
}

This really short script takes advantage of the CUPS command line. Walking through it, all printers on the machine are listed, the trailing return is removed, and all jobs are cancelled on all available printers. No more stuck print jobs once a user logs out!

With a knowledge of the command line, the sky is the limit. Almost any printer problem can be administered remotely, using your favorite remote administration tool.

One of the problems with adding a printer from the command line is some functionality is lost. In particular, ColorSync profiles are not associated with the printer when adding from the command line. With a little perl magic, a CUPS keyword can be added to the printer ppd file that lives in /etc/cups/ppd. Without further delay:

perl -pi -e 's/\*APP/\*cupsICCProfile\ \/Library\/Printers\/Dell\/Profiles\/Dell\ 
Laser\ Printer\ 3100cn.icc\n\*APP/' /etc/cups/ppd/myprinter.ppd

This one liner inserts a ColorSync keyword into the printer ppd file. Once added, the printer has a ColorSync profile associated with it.

Occasionally the debugging information shown in the system log file is not sufficient. To crank up the logging information, edit the cupsd.conf file. It is initially set to provide info level logging. For most purposes that is sufficient. If not, debug and debug2 can be set in the cupsd.conf file. One warning though, the amount of information can be staggering when set to debug2 level logging.

One option that has been the bane of many system administrators existence is the use of binary printing from Photoshop. Occasionally users will print a file in binary form to a printer, spewing pages and pages of one character per page. A printer can now be set from the command line to understand binary printing options. Our good friend, lpadmin to the rescue!

lpadmin -p printername -o protocol=TBCP

The printer will now correctly send binary printing jobs. Woohoo!

The last fun thing that can be done is accessing the cups interface from the local web interface. Open a web browser, and enter http://localhost:631. Most of the functionality in this article is available through the web interface. Most often, I use it for browsing the CUPS documentation without having to access the cups.org website.

Almost any task that can be accomplished using Printer Setup Utility can also be done with the command line. Only one item in Printer Setup cannot be accomplished easily, adding a Desktop Printer. It probably makes sense that this is the case, as desktop printers are a very Mac like functionality. Delving into it a little deeper, Printer Setup Utility also creates a printer "app" in /Library/Printers. lpadmin does not create this .app file. If Desktop Printers are very important in your environment, the command line may not be for you. Now get out there, and start strutting your new stuff!

Philip Rinehart is co-chair of the steering committee leading the Mac OS X Enterprise Project (macenterprise.org) and is the Lead Mac Analyst at Yale University. He has been using Macintosh Computers since the days of the Macintosh SE, and Mac OS X since its Developer Preview Release. Before coming to Yale, he worked as a Unix system administrator for a dot-com company. He can be reached at: philip.rinehart@yale.edu.