CUPS Software Administrators Manual


CUPS-SAM-1.0.4
Easy Software Products
Copyright 1997-1999, All Rights Reserved

Table of Contents



Preface 1 - Printing System Overview 2 - Building and Installing CUPS 3 - Printer Queue Management 4 - Printing System Management 5 - Printer Accounting A - Using CUPS with SAMBA
GIF89a¯ÿòÌÌÌ™™™fff333ÿÿÿÿÿÿÿÿÿ!ù,¯ÿBþXºÜþ0ÊI«½8ëÍ»ÿ`(Ždižhª2€0p,Ïtmßx®ï ;±Ýíˆndý !¸ ž³wà…MƒƒY~¿{,gÚ\‚äé Œ×Ø(tÙî!Ï=Ñ.ûz¯áÑŸ:ì;Ã9qöíÉë]/¿ºÉ¤Et/†'Îþt9ÀØ–ž_ÙÇ\|W•wArö¸Ý2Ô× tN°0Tï}¡û‰$!‚yMxî)ˆš‰Ôø@nB°U½ÊwE„§!ŠF H L8B c‰;ždŠ-æDVWdг€h±äÚ“P¶%#(4Fiå•Ï\hŠ:Re!\ÒÄ—X^¦%€¥À-$E€Ö/úHŽšlââöÌQX ¸1Nô¯b"œŠüjåÁÂE0…È8ö5GkZ|ÒÁwt„C»ÔQSÇo6ÔÙ[W„$²*Ž+4Pb-8¹P1þ'8"‘ФÄ$ Cyê‘„)>ãŠtè`Ð3‡‹¾z"«rE'Âqfä°Ë ‘qÂ\|€„Ž¡ôö»%É(.—bڽȀíÉ`{¬EÇ1w’ »[Hß`(B6ö“  †')ÊRŽÎa[ÃrbC!Tå°Œ 2Q·ÈHZê#–®üË/àô¯FÝê(Û²% ºXË9öÀbÁ4f.ù-oý™XËB…IÎÒ7¹*@ÃÓŽÍT€hà‘ÌWâ™Ã$f:µyžn†ó†r„'téKv` Ç+dª– œ79sò|'=×¢Ìx¶òœÿ„¦œˆeÎ;*à$þ” IÝÆaÏ{–3ŽÅÁ P“ÍS[ÙL¨3©òQ7éÆò#ãûô0F×ðsE°t§@‘ØQÜ´´ ©:3ÓRíd ¥*MITnŒ£¨H]ØQÁd @òþ—¬rMœŽaO rë^yÀ·(¸îéêû$uDòrã/a,I.°ÙUÀœb hˆ`¾B ë" Ü`HØxȸo1þ[á\8f^æ|\ý‚¢¢zø0(ˆ\ {ƒÄgäÞõ€çâ§Á˜0*\³n¼‹m¶/Äeª±ÿ†ì Ç,½DN2€œº+ùÉ|í0L¡Le*ð¸Ã>­2ëf,eIPOËÅàr—±”80SAŸcFªatç»ãy¤¸ršçÌ¡5ïoõËsžï|¿8˙Φ¬þ,ï¼èà)ÁÌ;øk¡—†dDpÑòø2¢qfHã!Ë“~ÙŸ-í 'g:,æ4y?ýäP‹Z›ž#ÏÕ´Î5AK‰k]ûš›ÒKõ¯‡më€õzØÈƫ؎Ý>B{PЪ.6hf]º?©ÌIŽuO„íM‚ÌÇÜcµ3˜ 61‹NÒ[†W£ ¦m¿­{ÂPâvζKnUˆ[ ònĽ±÷n?l:Áž3ušë¬sP[ÿnn¾çP…WõÔFj[Â÷ ¹vÏ™à‰˜xú'ˆ£ÀÀ†p¸4.êãKÇ¿ÂÁ±o§¢ü"Á|Nk`îʘ  jl©ÌuˆËi™0pmC´«+‰÷6¤2­éÏe`(ŽJ]¥iõð3ƒØí"p|ª!:qøFس 6£ @­,þŠqüãoÌÇ®žÖüV“¶QÇ›Evî¹²É8ÙªS"æÀç‡x± àþ‡>—Iãg ïÝ>Y‰çN80æ§ ±¾GLLìÕµ…(1Þ¼!8}þ¬“*…ª‰Ùì:e»´œ ª¿ên_6ÂÃSÀ`eG;Ö„CƒCcˆ¿‡4¸yeî¯Í)oøByRm½0?íLîÅ`QÿjÓÙ/ºôÓN|Ý þÙAÜŒÁ¸D5©D aævx ?жx°DM@•!h‰àÈ€Ž§® • á×B`ð¤ªE?›“”Þdƒ"8$Ý`Ki0…OðƒnΓ±µvtžè€I([,¹Ndɨh\'6X Pã—Š‰Éøt ¢‘¥˜¬è €ˆ†Ky™FˆŒë`š”yƒ„¨š €š‰ƒM©‡øFQhY„ 9¶X¯×–í4š¤™Y\)"¹AN]‰xéz÷Gq07)©ñ™•Y€r°ŒŽi‹ z ™ÇäFÍÉT–ù› ËŽC œwI›üX]‹¹\ëY]þf lïYbj8ŸÈuœbŸÍÅtú©fÞןfBI—“*øé:ÛØUj Ò ˆõ¹ Õp $(~ ¡Ú ¡gù{îpZI?¡ƒîÀv:“a¦˜6¢§Ô]Ý‘(ªê)!ŸÚ¢: jwµ¡4ÚvíHÛǘ9ºXhó•üù£¥Á¢VÉ{Dº2š‰(°¤3š¤a÷ +У¥“p¢þò4Vº—  E´¥è¤k°7ºhT*€¿èw`ÚžiÄ …S¦Ʀmê Nêƒ#ú¢f€ xê†ý 8z©7uÚp{Ú=~]7`«h‡ÚsÚg:…zd˜ó§ÎA-vþAñr¦'–AÚ)9–š¢âSi;£…š 1ªo"ª ¦J;“º rº8Ui|é>¡Úœú “ë¥Dfný2»ƒ–0j«®»ºK;zë¢Íö»—!µ—S»³r>K+6ˆ‹¨XÒ»; CÈ 8Ê;¢»ÃÛ/Œ‹¥ž!¬s½VR½óõÏ‹Oâ[/çK¨þ˜Ñ:Í‹\Ý+ Sc:ïËž’º¶ë9Æ» ô 8ly$ 8©ÙÅmX2Ùh>—?¯!šHüÁ^LsP,Ÿ«Y‹âá¿ÿtšì‚£Y r¦Éš¥9ÇjžÄ8-ÆÇŒ¶iêPÂbA˜ù‰Ã¸š»³7RœCWRoìŠå MŒŠ”åt™ Œ›réÉq å>}Lê}ÎǨ 5:àŒ|"þÇwÐsøæNΰ¹#R>~-N‰®èƒ ßcðÞÚÎÑ¥®åGÎâ툉Ýè*‚¸ =‚ž ºëâ…­ëÀ>Û·žën^žmèÊëð¼ã>å×Λ«}êØ÷ “Œ¬ËIÁ·AÔNÍëv>]t.âÚLЫþíï¾ñnäÖÜæs¹¿±â°+† ¬UØïî•.ç¬ÎìÍ.è´ÞŠG=ðù‚§ž¯”ë^äÛ®êh-‹êê!i!ÕvMíiªîþ¾òîá/þÑ-OÖGð,oñº!å’gOâ POìOôBþÈàhâ+?ï>ßÊVHÀsaõ™€õ$óSîõ—»ó8.žß¹ ~áßÈ©ö»]ò3ëÆt_÷[ïôb¯ç‚Ü÷Õ«@u™ð;zܘ‘Ü@óŽ2’?ùƒ¸ÙlùF ¶™¯ù›N ž0œú£¶¤ÿ0#9:ß§½ž©Ÿ\#ÃÙæó2é+û‚ÀÓ¸_äM/ÓtaÚý3”]Ù«¿¸iîaF>ª}ŒØvÍïMÍ÷Ðëä©îrÜŒöqñ_ÀüªrâF®ò ýþ¸—hT_ã4sx”ýÝî)ç.QgûàŸÏ%ì‹}i´ASû|þð@QÜ $J9€»-̱÷ÜôMØ‘hZ˜¦:°œ*ÏlßxÒ|ϼ¡ÅLÀ ¬Áfù9BÑdìÁ|«VV„¢“énKv kB_ƒg 3ʳ8#Þ¬L=0;J¤äÈ@¤F|'i~±© žaÊŠÆg;d*3²”©bPÏ¢TäHô¦?[† ÄäƒhN6ZM¢D:c*BR!$±ckƒ’V­-uÛ@[øp„Ÿ]¼8ö-1{TήWÏ2ñ Šp=¸q«Ñ½es.‰„4+#Ëe¦¥W5µekxr䛓/XÍš5Iǃ=kÝúµì˰ûN–2qŦyZ£QŽ›ÇÞtxŠäcK—Ííɹ iþ¡9¼m1oñ¢©/²8îìSté4l’Wm¾9óéÖÛÐãã{{üzÞ¿çøêöÞzà}œàL¨ "˜ ÄÐsà¶PGLUúå`MÞ  ¡†9¬§Û{pX¸¡wÚw߇¡¨ ‰í "MUXNx +l´á¦ j²F:Á.êÆÛj¤³Búî ¼Ê«/£Ö’[н#í+ð¥ænJÞ¸«æ;ð©õ‹¨ _ËðÄŠÒ»*º? ƒÂwœÃyzh±°Øzl2,#oZ2È›r|òË‚°¼$Ç)ë óÍÙÔ,éfs€1Î@/øîÏPõÌiÐH·ðÃBkLtÒP¯bôS;NÝWÔXÏ ó’dlÍtÖ`°tžOc óÅa§}AÄ›²1vËjÇmþu+`ÍÍÁ·qwü6˜‚ì½sÞXŸ¨Ë$xM6àP³-iÉSÚ½AÙˆïë84–ø=xä8^!ä*L>Þ˜ƒk¹Œ({Iè^!ḘN$ê «®ç!ºû‚ÿÝ ë¯ßoî—Oü¨¾ÿî9í]ñÞ{ñÙÊ®ãlhŽ(èÌÃê¼~ÔS¢|öÕŸzýw¬Ë§|øÝ—*½ŒÈ×­|úåwzþæ“)Nrû¾Ê?*ô¥ ¿*÷ô7ú½~Múúú÷ª÷Ɉ•S3x*ûíP”ùH£°°àó(è¾í-Jƒú™ åAF{#\”g…Áœ)!),Ô #ÓÂǼjþ1œŒþh©²K„9$ƒYè)Ž ˆA È —‡)#1‰Óp"˜ð'Ã%n‰P´‡Ù¨-‹1³¢^\%ƈÔp„CLÖ5Ã

Preface

This software administrators manual provides printer administration information for the Common UNIX Printing System ("CUPS") Version 1.0.4.

System Overview

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

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

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

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

Document Overview

This software administrators manual is organized into the following sections:

1 - Printing System Overview

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

The Printing Problem

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

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

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

The Technology

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

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

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

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

Jobs

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

Classes

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

Filters

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

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

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

Printer Drivers

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

Networking

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

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

2 - Building and Installing CUPS

This chapter shows how to build and install the Common UNIX Printing System. If you are installing a binary distribution from the CUPS web site, proceed to the section titled, Installing a Binary Distribution.

Installing a Source Distribution

Requirements

You'll need an ANSI C compiler to build CUPS on your system. As its name implies, CUPS is designed to run on the UNIX operating system, however the CUPS interface library and most of the filters and backends supplied with CUPS should also run under Microsoft® Windows®.

For the image file filters and PostScript RIP, you'll need the JPEG, PNG, TIFF, and ZLIB libraries. CUPS will build without these, but with reduced functionality. Easy Software Products maintains a mirror of the current versions of these libraries at:

If you make changes to the man pages you'll need GNU groff or another nroff-like package. GNU groff is available from:

The documentation is formatted using the HTMLDOC software. If you need to make changes you can get the HTMLDOC software from:

Compiling CUPS

CUPS uses GNU autoconf to configure the makefiles and source code for your system. To configure CUPS for your system type:

The default installation will put the CUPS software in the /usr and /var directories on your system, which will overwrite any existing printing commands on your system. To install the CUPS software in another location use the --prefix option:

If the PNG, JPEG, TIFF, and ZLIB libraries are not installed in a system default location (typically /usr/include and /usr/lib) you'll need to set the CFLAGS and LDFLAGS environment variables prior to running configure:

Once you have configured things, just type:

to build the software.

Installing the Software

To install the software type:

Running the Software

Once you have installed the software you can start the CUPS daemon by typing:

Installing a Binary Distribution

We are currently distributing CUPS binary distributions in TAR format with installation and removal scripts.

To install the CUPS software you will need to be logged in as root (doing an "su" is good enough). Once you are the root user, run the installation script with:

After asking you a few yes/no questions the CUPS software will be installed and the scheduler will be started automatically.

3 - Printer Queue Management

This chapter discusses how to add, modify, and delete print queues on your system.

The lpadmin Command

The lpadmin command allows you to perform most printer administration tasks from the command-line. Since lpadmin is also a System V printing system command, it is located in the /usr/lib directory instead of a more common one like /usr/bin or /usr/sbin.

Adding and Modifying Printers

To add a printer to CUPS you simply run the lpadmin command with the "-p" option:

Spaces between the option letter and value are optional.

The printer name can be up to 127 letters, digits, hyphens, and underscores. Unlike other printing systems, the printer name in CUPS is not case-sensitive, so you can't add two printers named LaserJet and laserjet.

The device argument specifies the device URI or filename for the printer. The following devices are supported in a basic installation of CUPS:

file:/dev/filename
/dev/filename
Sends all output to the specified file.
http://[username:password@]hostname[:port]/resource
ipp://[username:password@]hostname[:port]/resource
Sends all output to the specified IPP printer or server. The port parameters defaults to 631.
lpd://hostname/queue
Sends all output to the specified LPD printer queue.
parallel:/dev/filename
Sends all output to the specified parallel port device.
serial:/dev/filename[?options]
Sends all output to the specified serial port device. The options can be any of the following separated by the plus (+) character:
smb://[username:password@]hostname/queue
smb://[username:password@]workgroup/hostname/queue
Sends all output to the specified SMB (Windows) printer queue using the SAMBA software.
socket://hostname[:port]
Sends all output to the specified printer using the AppSocket protocol. The port parameter defaults to 9100.

The ppd argument specifies the PostScript Printer Description file to use for this printer. Many options (such as media size, etc.) will not be available if you omit this part of the lpadmin command.

Using Standard Printer Drivers

The lpadmin command allows you to use "standard" PPD files and interface scripts located in the /usr/share/cups/model directory with the "-m" option:

The model argument specifies the name of the PPD file or interface script. For example, to add a printer using the sample HP DeskJet series driver connected to parallel port 1 under Linux you would use:

Removing Printers

To remove a printer to CUPS you simply run the lpadmin command with the "-x" option:

Printer Classes

CUPS allows you to group similar printers in a printer class. When a user sends a print job to a class, the job will be processed by the first available printer in that class.

To add a printer to a class you simply run the lpadmin command with the "-p" and "-c" options:

The class is created automatically if it doesn't exist. To remove a class just use the "-x" option:

Setting the Default Printer

To set the default printer or class simply run the lpadmin command with the "-d" option:

The destination argument is the name of the printer or class.

Starting and Stopping Printers

The enable and disable commands start and stop printer queues, respectively:

Printers that are disabled may still accept jobs for printing, but won't actually print any files until they are restarted. This is useful if the printer malfunctions and you need time to correct the problem. Any queues jobs are printed after the printer is enabled (started).

Accepting and Rejecting Print Jobs

The accept and reject commands accept and reject print jobs for the named printer, respectively:

As noted above, a printer can be stopped but accepting new print jobs. A printer can also be rejecting new print jobs while it finishes those that have been queued. This is useful for when you must perform maintenance on the printer and will not have it available to users for a long period of time.

4 - Printing System Management

This chapter shows how you can configure the CUPS server.

Changing the Configuration Files

All of the server configuration files are located in the /var/cups/conf directory. Once you have made a change to a file you need to restart the CUPS server by sending it a HUP signal or using the supplied script "cups.sh":

The binary distribution installs the script in the init.d directory with the name lp or lpd depending on the vendor-supplied printing system.

Temporary Files

Normally CUPS puts all of its temporary files in /var/tmp . If you'd like to change this directory you'll need to edit the /var/cups/conf/cupsd.conf file.

Start by creating the new temporary directory and setting the appropriate permissions:

Then change the line containing the TempDir directive in the cupsd.conf to the directory that you've created:

Finally, restart the server as outlined in the first section of this chapter.

Network Configuration

The default configuration of the CUPS server listens for connections from all network interfaces on port 631 (the standard IPP port). Administration functions are limited to local connections with the appropriate username and password.

If you'd like to limit access to your system you'll need to edit the /var/cups/conf/cupsd.conf file.

Port

The Port directive specifies a port to listen on for all interfaces. Besides the standard IPP port (631) you can also setup your server to listen on the HTTP port (80) to use your CUPS server as a standard web server as well.

Listen

The Listen directive specifies a listening address and port, extending the functionality of the Port directive. If you want to allow connections only from the local machine you can use:

instead of the Port directive.

If you want to limit access to a specific network/subnet, make sure you specify only the network address and not your system's network address!

BrowsePort

The BrowsePort directive controls which port is monitored for remote printers. By default it is set to the IPP port (631), however you can change it as needed.

BrowseAddress

The BrowseAddress directive specifies a broadcast address to use when sending printer status updates over the network. The default browse address is 255.255.255.255 which will send printer information to all subnets.

Printer Security

CUPS provides IP and domain-name based access control and Basic authentication for authentication.

Location

The Location directive defines access control for a specific HTTP directory. The following pseudo directories are provided by the CUPS server:

All other directories are taken from the /usr/share/cups/doc directory.

The Location directive surrounds the other access control directives described below. The default server configuration uses:

Order

The Order directive defines the default access control. The following values are supported:

The Order directive must appear inside a Location directive.

Allow

The Allow directive specifies a hostname, IP address, or network that is allowed access to the server:

Allow directives are cummulative, so multiple Allow directives can be used to allow access for multiple hosts or networks. The /mm notation specifies a CIDR netmask:

mmnetmask
00.0.0.0
1128.0.0.0
2192.0.0.0
......
8255.0.0.0
16255.255.0.0
24255.255.255.0
32255.255.255.255

The Allow directive must appear inside a Location directive.

Deny

The Deny directive specifies a hostname, IP address, or network that is allowed access to the server:

Deny directives are cummulative, so multiple Deny directives can be used to allow access for multiple hosts or networks. The /mm notation specifies a CIDR netmask:

mmnetmask
00.0.0.0
1128.0.0.0
2192.0.0.0
......
8255.0.0.0
16255.255.0.0
24255.255.255.0
32255.255.255.255

The Deny directive must appear inside a Location directive.

AuthType

The AuthType directive defines the type of authentication to perform:

The AuthType directive must appear inside a Location directive.

AuthClass

The AuthClass directive defines what level of Basic access is required:

The AuthClass directive must appear inside a Location directive.

AuthGroupName

The AuthGroupName directive sets the group to use for Group authentication.

The AuthGroupName directive must appear inside a Location directive.

SystemGroup

The SystemGroup directive sets the administration group used when authenticating the System type. It defaults to the "sys" group.

File Formats

CUPS provides a MIME-based file typing and filtering mechanism to convert files to a printable format for each printer. The mime.types and mime.convs files define the file type and filters that are available on the system.

mime.types

The mime.types defines the known file types. Each line of the file starts with the MIME type and may be followed by one or more file type recognition rules. For example, the text/html file type is defined as:

The first two rules say that any file with an extension of ".html" or ".htm" is a HTML file. The third rules says that any file whose first 1024 characters are printable text and starts with the strings "<HTML>" or "<!DOCTYPE" is a HTML file as well.

The first two rules deal solely with the name of the file being typed. This is useful when the original filename is known, however for print files the server doesn't always have a filename to work with. The third rule takes care of this possibility and automatically figures out the file type based upon the contents of the file instead.

The available tests are:

mime.convs

The mime.convs file defines all of the filter programs that are known to the system. Each line consists of:

The source field is a MIME type, optionally using a wildcard for the super-type or sub-type (e.g. "text/plain", "image/*", "*/postscript").

The destination field is a MIME type defined in the mime.types file.

The cost field defines a relative cost for the filtering operation from 1 to 100. The cost is used to choose between two different sets of filters when converting a file. For example, to convert from image/jpeg to application/vnd.cups-raster, you could use the imagetops and pstoraster filters for a total cost of 100, or the imagetoraster filter for a total cost of 50.

The program field defines the filter program to run; the special program "-" can be used to make two file types equivalent. The program must accept the standard filter arguments and environment variables described in the CUPS Interface Design Document:

If specified, the filename argument defines a file to read when filtering, otherwise the filter must read from the standard input. All filtered output must go to the standard output.

5 - Printer Accounting

This chapter describes the CUPS log files.

Where to Find the Log Files

The log files are normally stored in the /var/cups/logs directory. You can change this by editing the /var/cups/conf/cupsd.conf configuration file.

The access_log File

The access_log file lists each HTTP resource that is accessed by a web browser or CUPS/IPP client. Each line is in the so-called "Common Log Format" used by many web servers and web reporting tools:

The host field will normally only be an IP address unless you have changed the HostnameLookups directive on in the cupsd.conf file.

The group field always contains "-".

The user field is the authenticated username of the requesting user. If no username and password is supplied for the request then this field contains "-".

The date-time field is the date and time of the request in Greenwich Mean Time (a.k.a. ZULU) and is in the format:

The method field is the HTTP method used ("GET", "PUT", "POST", etc.)

The resource field is the filename of the requested resource.

The version field is the HTTP specification version used by the client. For CUPS clients this will always be "HTTP/1.1".

The status field contains the HTTP result status of the request. Usually it is "200", but other HTTP status codes are possible. For example, 401 is the "unauthorized access" status in the example above.

The bytes field contains the number of bytes in the request. For POST requests the bytes field contains the number of bytes of non-IPP data that is received from the client.

The error_log File

The error_log file lists messages from the scheduler (errors, warnings, etc.):

The level field contains the type of message:

The date-time field contains the date and time of when the page started printing. The format of this field is identical to the data-time field in the access_log file.

The message fields contains a free-form textual message.

The page_log File

The page_log file lists each page that is sent to a printer. Each line contains the following information:

The printer field contains the name of the printer that printed the page. If you send a job to a printer class, this field will contain the name of the printer that was assigned the job.

The user field contains the name of the user (the IPP requesting-user-name attribute) that submitted this file for printing.

The job-id field contains the job number of the page being printed. Job numbers are reset to 1 whenever the CUPS server is started, so don't depend on this number being unique!

The date-time field contains the date and time of when the page started printing. The format of this field is identical to the data-time field in the access_log file.

The page-number and num-pages fields contain the page number and number of copies being printed of that page. For printer that can not produce copies on their own, the num-pages field will always be 1.

A - Using CUPS with SAMBA

This appendix describes how to use CUPS with SAMBA.

What is SAMBA?

In case you haven't heard of SAMBA, it is basically a software package that allows you to configure your UNIX system as a Windows file and printer server. It also allows you to access files and printers on a Windows system. Like CUPS, SAMBA is free software.

SAMBA version 2.0.6 is the first release of SAMBA that supports CUPS. You can download SAMBA from:

http://www.samba.org

How Do I Configure SAMBA for CUPS?

To configure SAMBA for CUPS, edit the smb.conf file and replace the existing printing commands and options with the line:

That's all there is to it! Remote users will now be able to browse and print to printers on your system.

How Do I Configure CUPS for SAMBA?

To configure CUPS for SAMBA, run the following command:

The smbspool program is provided with SAMBA starting with SAMBA 2.0.6. Once you have made the link you can use the smb method in the device URI for your printers:

The second form only needs to be used if the Windows system is in a different workgroup.