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.

 
AAPL
$531.70
Apple Inc.
+0.53
MSFT
$39.99
Microsoft Corpora
+0.05
GOOG
$534.81
Google Inc.
+6.19

MacTech Search:
Community Search:

Software Updates via MacUpdate

Viber 4.1.0 - Send messages and make cal...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device,... Read more
Apple iOS 7.1.1 - The latest version of...
The latest version of iOS can be downloaded through iTunes. Apple iOS 7 brings an all-new design and all-new features. Simplicity Simplicity is often equated with minimalism. Yet true simplicity is... Read more
1Password 4.3 - Powerful password manage...
1Password is a password manager that uniquely brings you both security and convenience. It is the only program that provides anti-phishing protection and goes beyond password management by adding Web... Read more
Lens Blur 1.3.0 - True out-of-focus boke...
Let Lens Blur transform your existing photo into true SLR-quality out-of-focus bokeh effect! Everyone needs a gorgeous personalized background for a social profile, blog, Web/UI design, presentation... Read more
VMware Fusion 6.0.3 - Run Windows apps a...
VMware Fusion allows you to create a Virtual Machine on your Mac and run Windows (including Windows 8.1) and Windows software on your Mac. Run your favorite Windows applications alongside Mac... Read more
Tweetbot 1.5.1 - Popular iOS twitter cli...
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
Mac DVDRipper Pro 4.1.7 - Copy, backup,...
Mac DVDRipper Pro is the DVD backup solution that lets you protect your DVDs from scratches, save your batteries by reading your movies from your hard disk, manage your collection with just a few... Read more
PDFpenPro 6.2 - Advanced PDF toolkit for...
PDFpenPro allows users to edit PDF's easily. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Create... Read more
PDFpen 6.2 - Edit and annotate PDFs with...
PDFpen allows users to easily edit PDF's. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Features... Read more
Monolingual 1.5.9 - Remove unwanted OS X...
Monolingual is a program for removing unnecesary language resources from OS X, in order to reclaim several hundred megabytes of disk space. It requires a 64-bit capable Intel-based Mac and at least... Read more

Latest Forum Discussions

See All

Zeebox is Now Beamly TV – Still Offers t...
Zeebox is Now Beamly TV – Still Offers the Same Social Networking TV Fun, Plus a New Look Posted by Rob Rich on April 22nd, 2014 [ permalink ] | Read more »
Bandai Namco Unveils Upcoming Slate of M...
At their recent Global Gamers’ Day event, Bandai Namco was largely focused on their console and PC offerings for the upcoming year. However mobile still had a small presence, with some upcoming titles revealed by the company – though few were in a... | Read more »
The Story Behind Grammar Girl’s Grammar...
Learning is so much more rewarding when it’s also fun. That’s part of the reason why recent educational app, Grammar Pop HD, garnered such a positive review from us last week. The brainchild of Mignon Fogarty, otherwise known as Grammar Girl, we... | Read more »
Pinnacle Studio for iPhone Review
Pinnacle Studio for iPhone Review By Jennifer Allen on April 22nd, 2014 Our Rating: :: SIMPLY POWERFULiPhone App - Designed for the iPhone, compatible with the iPad Video editing while on the move has never been so convenient.   | Read more »
Taste Savant Review
Taste Savant Review By Jennifer Allen on April 22nd, 2014 Our Rating: :: TASTY RECOMMENDATIONSiPhone App - Designed for the iPhone, compatible with the iPad In need of some new restaurant recommendations? This app will be ideal,... | Read more »
Where’s My Water? Featuring XYY Adds Mor...
Where’s My Water? Featuring XYY Adds More Than Just Sheep to the Liquid Physics Puzzler Posted by Rob Rich on April 22nd, 2014 [ permalink ] | Read more »
FarmVille 2: Country Escape Review
FarmVille 2: Country Escape Review By Jennifer Allen on April 22nd, 2014 Our Rating: :: STEADY FARMINGUniversal App - Designed for iPhone and iPad FarmVille is bigger and brighter than ever before, but don’t expect it to sway you... | Read more »
Doctor Who: Legacy receives big update,...
Doctor Who: Legacy receives big update, adds Perk System and more Posted by Tre Lawrence on April 22nd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Strongarm Universal Mount Hardware Revie...
Made by: Viatek Price: $14.99 for 2 Hardware/iOS Integration Rating: 3.5 out of 5 stars Usability Rating: 4 out of 5 stars Reuse Value Rating: 3.75 out of 5 stars Build Quality Rating: 3.5 out of 5 stars Overall Rating: 3.69 out of 5 stars | Read more »
Boxer Review
Boxer Review By Campbell Bird on April 21st, 2014 Our Rating: :: KO YOUR INBOXUniversal App - Designed for iPhone and iPad Turn your inbox into a task list or tune it to your own needs with this highly customizable, user friendly... | Read more »

Price Scanner via MacPrices.net

Everything You Wanted To Know And Probably Mo...
Macworld UK’s Lou Hattersley takes a look inside Apple’s A7 System On Chip (SoC) , noting that its processor module is much more powerful than other smartphone chipsets. He notes that the A7 was a... Read more
2.5GHz Mac mini, Apple refurbished, available...
The Apple Store has Apple Certified Refurbished 2.5GHz Mac minis available for $509, $90 off MSRP. Apple’s one-year warranty is included, and shipping is free. Read more
13-inch MacBook Pro, Apple refurbished, avail...
The Apple Store continues to offer Apple Certified Refurbished 13″ 2.5GHz MacBook Pros (4GB RAM/500GB HD) for $999 which is $200 off MSRP. Apple’s one-year warranty is included, and shipping is free. Read more
15-inch MacBook Pros (refurbished) available...
The Apple Store has Apple Certified Refurbished October 2013 15″ Retina MacBook Pros available starting at $1699, with models up to $400 off MSRP. Apple’s one-year warranty is standard, and shipping... Read more
$100 off cellular iPad minis plus free $20 gi...
Best Buy is discounting cellular iPad minis with Retina Displays by $100 on their online store for a limited time. They’ll also throw in a free $20 Best Buy gift card. Choose free shipping or free... Read more
Updated Price Trackers
We’ve updated our Mac Price Trackers with the latest information on prices, bundles, and availability on systems from Apple’s authorized internet/catalog resellers: - 15″ MacBook Pros - 13″ MacBook... Read more
Apple refurbished MacBook Airs available for...
The Apple Store has Apple Certified Refurbished 2013 MacBook Airs available for up to $200 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is free... Read more
Android Leads in Operating System Share Andro...
Consumer Intelligence Research Partners, LLC (CIRP) has released its latest results of its research on mobile phone operating systems for the calendar quarter that ended March 31, 2014. This analysis... Read more
Pelican Products, Inc. Introduces New Lineup...
Pelican Products, Inc., the global leader in the design and manufacture of high-performance protective cases, today announced the launch of a new line of rugged phone cases for both the Apple iPhone... Read more
SaveDrives – Car Dashboard Video Camera &...
Drivers who want to help reduce potential damage to their health and finances in the event of an accident can download the innovative new no-cost app SaveDrives – Car Dashboard Video Camera &... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Inc. Research Data Specialist - Appl...
…of Worldwide Market Research & Intelligence. The team is responsible for conducting Apple branded consumer market research. It is also responsible for analyzing data Read more
*Apple* Automotive Parts Department position...
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, we Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.