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

Things 2.5.4 - Elegant personal task man...
Things is a task management solution that helps to organize your tasks in an elegant and intuitive way. Things combines powerful features with simplicity through the use of tags and its intelligent... Read more
NeoOffice 2014.10 - Mac-tailored, OpenOf...
NeoOffice is a complete office suite for OS X. With NeoOffice, users can view, edit, and save OpenOffice documents, PDF files, and most Microsoft Word, Excel, and PowerPoint documents. NeoOffice 3.x... Read more
iPhoto Library Manager 4.2 - Manage mult...
iPhoto Library Manager allows you to organize your photos among multiple iPhoto libraries, rather than having to store all of your photos in one giant library. You can browse the photos in all your... Read more
Web Snapper 3.3.8 - Capture entire Web p...
Web Snapper lets you capture Web pages exactly as they appear in your browser. You can send them to a file as images or vector-based, multi-page PDFs. It captures the whole Web page - eliminating the... Read more
TeamViewer 10.0.41404 - Establish remote...
TeamViewer gives you remote control of any computer or Mac over the Internet within seconds, or can be used for online meetings. Find out why more than 200 million users trust TeamViewer! Free for... Read more
Ableton Live 9.1.8 - Record music using...
Ableton Live lets you create and record music on your Mac. Use digital instruments, pre-recorded sounds, and sampled loops to arrange, produce, and perform your music like never before. Ableton Live... Read more
VOX 2.5 - Music player that supports man...
VOX is a beautiful music player that supports many filetypes. The beauty is in its simplicity, yet behind the minimal exterior lies a powerful music player with a ton of features & support for... Read more
OmniFocus 2.1.2 - GTD task manager with...
OmniFocus helps you manage your tasks the way that you want, freeing you to focus your attention on the things that matter to you most. Capturing tasks and ideas is always a keyboard shortcut away in... Read more
Adobe Flash Player 17.0.0.169 - Plug-in...
Adobe Flash Player is a cross-platform, browser-based application runtime that provides uncompromised viewing of expressive applications, content, and videos across browsers and operating systems.... Read more
iMazing 1.1.3 - Complete iOS device mana...
iMazing (was DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and from... Read more

Chainsaw Warrior: Lords of the Night has...
It's time to put the Darkness back in its place now that Chainsaw Warrior: Lords of the Night has officially made it to iOS. | Read more »
A World of Ice and Fire Lets You Stalk 2...
George R. R. Martin’s A World of Ice and Fire, by Random House, is a mobile guide to the epic series. The new update gives you the Journeys map feture that will let you track the movements of 25 different characters. But don't worry, you can protect... | Read more »
Gameloft Announces Battle Odyssey, a New...
Battle Odyssey, Gameloft's newest puzzle RPG, is coming to the App Store next week. Set in the world of Pondera, you will need to control the power of the elements to defend the world from evil. You'll be able to entlist over 500 allies to aid you... | Read more »
Fusion - HDR Camera (Photography)
Fusion - HDR Camera 1.0.0 Device: iOS Universal Category: Photography Price: $1.99, Version: 1.0.0 (iTunes) Description: Fusion creates HDR (high dynamic range) photos by capturing different exposures and then combining them into one... | Read more »
Sago Mini Toolbox (Education)
Sago Mini Toolbox 1.1 Device: iOS Universal Category: Education Price: $2.99, Version: 1.1 (iTunes) Description: Come build with the Sago Mini friends! Use a wrench, try a saw, or hammer some nails. From sewing hand puppets to... | Read more »
You Should Probably Grab Hitman GO While...
Hitman GO is a surprisingly cool (yet also incredibly drastic) departure from the Hitman series. It's well worth playing for any puzzle game fans out there, and at the moment you can get your hands - or garrotte if you will - on it for a mere $0.99... | Read more »
IFTTT is Bringing Do Button and Do Note...
IFTTT has announced Do Button and Do Note for the Apple Watch. Do Button lets you make your own personalized button that can connect to things like your Google Drive, control the temperature in your home with Nest Thermostat, or turn the lights on... | Read more »
How Many Days, Hours, and Minutes Are Le...
Countdown, by Yves Tscherry, is now available on the App Store. The app keeps track of countdowns to your favorite things such as someones birthday or days till the New Year. You can display the time in seconds, minutes, hours, days, weeks, months,... | Read more »
The All-New Misfit 2.0 App is Available...
Misfit has just given their app a complete overhaul. Misfit 2.0 now has a brand new interface with a sleek design and is easier to navigate. You'll be able to sync your Misfit device and look up health and fitness information faster than ever before... | Read more »
Halo: Spartan Strike (Games)
Halo: Spartan Strike 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: Delve into 30 challenging missions through cities and jungles using a devastating arsenal of weapons, abilities and... | Read more »

Price Scanner via MacPrices.net

Sale! 16GB iPhone 5S for $1 with service
Best Buy is offering 16GB iPhone 5Ss for $1.00 with 2-year activation at a participating cellular provider. Choose free home shipping and activation, or buy online and activate during in-store pickup... Read more
Apple refurbished 2014 MacBook Airs available...
The Apple Store has Apple Certified Refurbished 2014 MacBook Airs available starting at $679. An Apple one-year warranty is included with each MacBook, and shipping is free. These are currently the... Read more
27-inch 3.5GHz 5K iMac on sale for $2349, sav...
 Adorama has the 27″ 3.5GHz 5K iMac in stock today and on sale for $2349 including free shipping plus NY & NJ sales tax only. Their price is $150 off MSRP. For a limited time, Adorama will... Read more
Save up to $380 on an iMac with Apple refurbi...
The Apple Store has Apple Certified Refurbished iMacs available for up to $380 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $2119 $... Read more
Faithful iPad 2 Gets A Second Career In Retir...
Finally, after four months’ transition, I handed my faithful old 2011 iPad 2 off to my wife at the end of March and switched whole-hog to using the iPad Air 2 I bought back in November. I’d found... Read more
Apple’s Worldwide Developers Conference Opens...
Apple has announced that it will hold its 26th annual Worldwide Developers Conference (WWDC) from June 8 through June 12 at San Francisco’s Moscone West, with more sessions than ever before streamed... Read more
Apple restocks refurbished 15-inch Retina Mac...
The Apple Store has restocked Apple Certified Refurbished 2014 15″ Retina MacBook Pros, available for up to $380 off the cost of new models. An Apple one-year warranty is included with each model,... Read more
College Student Deals: Additional $50 off Mac...
Take an additional $50 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through May 9, 2015. Anyone with a valid .EDU email address can take advantage of... Read more
Save up to $300 on a new Mac, $30 on an iPad,...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
15-inch and 13-inch Apple Retina MacBook Pros...
B&H Photo has 15″ & 13″ Retina MacBook Pros on sale for up to $200 off MSRP for a limited time. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799... Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
*Apple* TV Live Streaming Frameworks Test En...
**Job Summary** Work and contribute towards the engineering of Apple 's state-of-the-art products involving video, audio, and graphics in Interactive Media Group (IMG) at Read more
Event Director, *Apple* Retail Marketing -...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global engagement strategy and team. Delivering an overarching brand Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.