TweetFollow Us on Twitter

My CUPS Runneth Over

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

CUPS

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.

Printer Setup Utility

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:



Figure 1.

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.



Figure 2.

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

Command Line Magic

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.

Setting the Default Printer

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.

Deleting Printers

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.

Printer Pooling

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.

One liners

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.

Going Deeper With lpadmin

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

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.

Advanced options

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.

Making it useful

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.

Odds and ends

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.

Armed and dangerous

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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Grab it now: Game Craft’s Legend of War...
The real time strategy game is now available for you to sink your teeth into, through the App Store and Google Play. Combining elements of skill, strategy and empire building, Legend of War is a real gamers’ game. [Read more] | Read more »
Skateboard Party 3 ft. Greg Lutzka (Gam...
Skateboard Party 3 ft. Greg Lutzka 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Skateboard Party is back! This third edition of the popular sports franchise features professional skater... | Read more »
Cubious (Games)
Cubious 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Cubious – How smart are you? How high is your IQube? Solve the impossible puzzles to find out, and help a lost little cube find his... | Read more »
Goat Simulator Waste of Space (Games)
Goat Simulator Waste of Space 1.1 Device: iOS Universal Category: Games Price: $4.99, Version: 1.1 (iTunes) Description: ** IMPORTANT - SUPPORTED DEVICESiPhone 4S, iPad 2, iPod Touch 5 or better.** | Read more »
Wildfulness - Unwind in nature and calm...
Wildfulness - Unwind in nature and calm your mind with nature sounds and illustrations 1.0 Device: iOS Universal Category: Healthcare & Fitness Price: $1.99, Version: 1.0 (iTunes) Description: Spending time in nature helps you to... | Read more »
Dr. Panda Racers (Education)
Dr. Panda Racers 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: STEP ON THE GAS, RACE AND WIN!Fasten your seat belts and get ready to race! Speed your way to the finish line while doing... | Read more »
ROMANCING SAGA 2 (Games)
ROMANCING SAGA 2 1.0.0 Device: iOS Universal Category: Games Price: $17.99, Version: 1.0.0 (iTunes) Description: Romancing SaGa 2, originally released only in Japan in 1993, has been completely remastered and now receives its first... | Read more »
WRIO Keyboard (Utilities)
WRIO Keyboard 1.0 Device: iOS iPhone Category: Utilities Price: $2.99, Version: 1.0 (iTunes) Description: 40% OFF DURING LIMITED INTRODUCTORY OFFER | Read more »
Hatoful Boyfriend (Games)
Hatoful Boyfriend 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: The hit PC game that everybirdie loves has now migrated to your mobile device! Now you are free to explore the wonders of St... | Read more »
Warp Shift (Games)
Warp Shift 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: [ CHECK YOUR HARDWARE: Warp Shift does NOT run on iPhone 4, iPad 1 and iPod touch 4G or older devices! It requires at least iOS8... | Read more »

Price Scanner via MacPrices.net

Goal Zero and OtterBox Partner to Expand iPh...
Goal Zero, specialists in portable power, have announced a partnership with OtterBox, brand smartphone case protection, to offer the Slide and Slide Plus Batteries as modules compatible with the new... Read more
15-inch Retina MacBook Pros on sale for up to...
B&H Photo has 15″ Retina MacBook Pros on sale for up to $210 off MSRP. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799 $200 off MSRP - 15″ 2.5GHz Retina... Read more
Clearance 2015 13-inch MacBook Airs available...
B&H Photo has clearance 2015 13″ MacBook Airs available for $250 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/4GB/128GB MacBook Air (MJVE2LL/A): $799... Read more
Apple refurbished Apple TVs available for up...
Apple has Certified Refurbished 32GB and 64GB Apple TVs available for up to $30 off the cost of new models. Apple’s standard one-year warranty is included with each model, and shipping is free: -... Read more
21-inch iMacs on sale for up to $120 off MSRP
B&H Photo has 21″ iMacs on sale for up to $120 off MSRP including free shipping plus NY sales tax only: - 21″ 3.1GHz iMac 4K: $1379.99 $120 off MSRP - 21″ 2.8GHz iMac: $1189 $110 off MSRP - 21″ 1... Read more
Kanex Introduces GoPower USB-C Rechargeable B...
Kanex has announced its GoPower USB-C portable battery for the USB-C MacBook, featuring the new industry standard connector and cable used for connectivity and power. Providing users with a new... Read more
Convertible and Detachable Devices Winning Ov...
According to the latest figures published by International Data Corporation (IDC), Western European shipments of ultraslim convertibles and detachables posted positive growth (44.7%) to account for... Read more
New MacBook Pros And Will MacBook Air Be Upgr...
With my mid-2013 13-inch MacBook Air closing on its third anniversary come November, I’m in system upgrade mode. Actually the Haswell CPU equipped Air is still doing a fine job, but my good wife is... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free, and... Read more
13-inch 2.5GHz MacBook Pro on sale for $999,...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $999 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more

Jobs Board

Editor, *Apple* News - APPLE (United States...
Job Summary The Apple News team is looking for a passionate and knowledgeable editor with experience covering entertainment/pop culture and experience running social Read more
*Apple* Nissan Service Technicians - Apple A...
Apple Automotive is one of the fastest growing dealer...and it shows. Consider making the switch to the Apple Automotive Group today! At Apple Automotive , Read more
ISCS *Apple* ID Site Support Engineer - APP...
…position, we are looking for an individual who has experience supporting customers with Apple ID issues and enjoys this area of support. This person should be Read more
Automotive Sales Consultant - Apple Ford Linc...
…you. The best candidates are smart, technologically savvy and are customer focused. Apple Ford Lincoln Apple Valley is different, because: $30,000 annual salary Read more
*Apple* Support Technician II - Worldventure...
…global, fast growing member based travel company, is currently sourcing for an Apple Support Technician II to be based in our Plano headquarters. WorldVentures is Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.