3 <META NAME="COPYRIGHT" CONTENT="Copyright 1997-2003, All Rights Reserved">
4 <META NAME="DOCNUMBER" CONTENT="CUPS-SAM-1.2.0">
5 <META NAME="Author" CONTENT="Easy Software Products">
6 <TITLE>CUPS Software Administrators Manual</TITLE>
10 <H1 ALIGN="RIGHT">Preface</H1>
12 <P>This software administrators manual provides printer administration
13 information for the Common UNIX Printing System<SUP>TM</SUP>
14 ("CUPS<SUP>TM</SUP>"), version 1.2.0.
16 <EMBED SRC="system-overview.shtml">
19 <H2>Document Overview</H2>
21 <P>This software administrators manual is organized into the following sections:</P>
24 <LI><A HREF="#OVERVIEW">1 - Printing System Overview</A>
25 <LI><A HREF="#BUILDING_INSTALLING">2 - Building and Installing CUPS</A>
26 <LI><A HREF="#MANAGING_PRINTERS">3 - Managing Printers</A>
27 <LI><A HREF="#PRINTER_CLASSES">4 - Printer Classes</A>
28 <LI><A HREF="#CLIENT_SETUP">5 - Client Setup</A>
29 <LI><A HREF="#PRINTING_MANAGEMENT">6 - Printing System Management</A>
30 <LI><A HREF="#PRINTING_OTHER">7 - Printing with Other Systems</A>
31 <LI><A HREF="#LICENSE">A - Software License Agreement</A>
32 <LI><A HREF="#COMMON_NETWORK">B - Common Network Settings</A>
33 <LI><A HREF="#PRINTER_DRIVERS">C - Printer Drivers</A>
34 <LI><A HREF="#FILES">D - List of Files</A>
35 <LI><A HREF="#FAQ">E - Troubleshooting Common Problems</A>
38 <H2>Notation Conventions</H2>
40 <P>Various font and syntax conventions are used in this guide. Examples and
41 their meanings and uses are explained below:
43 <CENTER><TABLE WIDTH="80%">
46 <TD> </TD>
49 <TR><TD> </TD></TR>
51 <TD><CODE>lpstat</CODE><BR>
52 <CODE>lpstat(1)</CODE></TD>
54 <TD> </TD>
56 <TD>The names of commands; the first mention of a command or
57 function in a chapter is followed by a manual page section
60 <TR><TD> </TD></TR>
62 <TD><VAR>/var</VAR><BR>
63 <VAR>/usr/share/cups/data/testprint.ps</VAR></TD>
65 <TD> </TD>
67 <TD>File and directory names.</TD>
69 <TR><TD> </TD></TR>
71 <TD NOWRAP><TT>Request ID is Printer-123</TT></TD>
73 <TD> </TD>
75 <TD>Screen output.</TD>
77 <TR><TD> </TD></TR>
79 <TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD>
81 <TD> </TD>
83 <TD>Literal user input; special keys like <KBD>ENTER</KBD> are
86 <TR><TD> </TD></TR>
90 <TD> </TD>
92 <TD>Numbers in the text are written using the period (.) to indicate
93 the decimal point.</TD>
98 <H2>Abbreviations</H2>
100 The following abbreviations are used throughout this manual:
106 <DD>Kilobytes, or 1024 bytes<BR>
109 <DD>Megabytes, or 1048576 bytes<BR>
112 <DD>Gigabytes, or 1073741824 bytes<BR>
117 <H2>Other References</H2>
122 <DT>CUPS Software Programmers Manual
124 <DD>A programmer guide for interfacing with and/or extending the CUPS
127 <DT>CUPS Software Users Manual
129 <DD>An end-user guide for using the CUPS software.<BR>
135 <EMBED SRC="printing-overview.shtml">
138 <H1 ALIGN="RIGHT"><A NAME="BUILDING_INSTALLING">2 - Building and Installing CUPS</A></H1>
140 <P>This chapter shows how to build and install the Common UNIX Printing System.
141 If you are installing a binary distribution from the CUPS web site, proceed to
142 the section titled, <A HREF="#BINARY">Installing a Binary Distribution</A>.
144 <H2>Installing a Source Distribution</H2>
146 <P>This section describes how to compile and install CUPS on your system
147 from the source code.
149 <H3><A NAME="REQUIREMENTS">Requirements</A></H3>
151 <P>You'll need ANSI-compliant C and C++ compilers to build CUPS on your
152 system. As its name implies, CUPS is designed to run on the UNIX
153 operating system, however the CUPS interface library and most of the
154 filters and backends supplied with CUPS should also compile and run
155 under Microsoft Windows.
157 <P>For the image file filters and PostScript RIP, you'll need the JPEG,
158 PNG, TIFF, and ZLIB libraries. CUPS will build without these, but with
159 significantly reduced functionality. Easy Software Products maintains a
160 mirror of the current versions of these libraries at:
163 <A HREF="ftp://ftp.easysw.com/pub/libraries">ftp://ftp.easysw.com/pub/libraries</A>
166 <P>If you make changes to the man pages you'll need GNU groff or another
167 nroff-like package. GNU groff is available from:
170 <A HREF="ftp://ftp.gnu.org/pub/groff">ftp://ftp.gnu.org/pub/groff</A>
173 <P>The documentation is formatted using the HTMLDOC software. If you need to
174 make changes you can get the HTMLDOC software from:
177 <A HREF="http://www.easysw.com/htmldoc">http://www.easysw.com/htmldoc</A>
180 <P>Finally, you'll need a <CODE>make</CODE> program that
181 understands the <CODE>include</CODE> directive - FreeBSD,
182 NetBSD, and OpenBSD developers should use the <CODE>gmake</CODE>
185 <H3><A NAME="COMPILING">Compiling CUPS</A></H3>
187 <P>CUPS uses GNU autoconf to configure the makefiles and source code
188 for your system. Type the following command to configure CUPS for your
192 <B>./configure ENTER</B>
195 <P>The default installation will put the CUPS software in the
196 <VAR>/etc</VAR>, <VAR>/usr</VAR>, and <VAR>/var</VAR> directories on
197 your system, which will overwrite any existing printing commands on
198 your system. Use the <CODE>--prefix</CODE> option to install the CUPS
199 software in another location:
202 <B>./configure --prefix=/some/directory ENTER</B>
205 <P>If the PNG, JPEG, TIFF, and ZLIB libraries are not installed in a
206 system default location (typically <VAR>/usr/include</VAR> and
207 <VAR>/usr/lib</VAR>) you'll need to set the <CODE>CFLAGS</CODE>,
208 <CODE>CXXFLAGS</CODE>, and <CODE>LDFLAGS</CODE> environment variables
209 prior to running configure:
212 <B>setenv CFLAGS "-I/some/directory" ENTER</B>
213 <B>setenv CXXFLAGS "-I/some/directory" ENTER</B>
214 <B>setenv LDFLAGS "-L/some/directory" ENTER</B>
215 <B>setenv DSOFLAGS "-L/some/directory" ENTER</B>
216 <B>./configure ... ENTER</B>
222 <B>CFLAGS="-I/some/directory"; export CFLAGS ENTER</B>
223 <B>CXXFLAGS="-I/some/directory"; export CXXFLAGS ENTER</B>
224 <B>LDFLAGS="-L/some/directory"; export LDFLAGS ENTER</B>
225 <B>DSOFLAGS="-L/some/directory"; export DSOFLAGS ENTER</B>
226 <B>./configure ... ENTER</B>
229 <P>To enable support for encryption, you'll also want to add the
230 "--enable-ssl" option:
233 ./configure --enable-ssl
236 <P>SSL and TLS support require the OpenSSL library, available at:
239 <A HREF="http://www.openssl.org">http://www.openssl.org</A>
242 <P>If the OpenSSL headers and libraries are not installed in the
243 standard directories, use the <CODE>--with-openssl-includes</CODE>
244 and <CODE>--with-openssl-libs</CODE> options:</P>
247 ./configure --enable-ssl \
248 --with-openssl-includes=/foo/bar/include \
249 --with-openssl-libs=/foo/bar/lib
252 <P>Once you have configured things, just type:
258 <P>to build the software.
261 <H3><A NAME="INSTALLING">Installing the Software</A></H3>
263 <P>Use the "install" target to install the software:
266 <B>make install ENTER</B>
269 <CENTER><TABLE WIDTH="80%" BORDER="1" BGCOLOR="#cccccc" CELLPADDING="5">
274 <P>Installing CUPS will overwrite your existing printing
275 system. If you experience difficulties with the CUPS software
276 and need to go back to your old printing system, you will need
277 to reinstall the old printing system from your operating system CDs.
282 <H3><A NAME="RUNNING">Running the Software</A></H3>
284 <P>Once you have installed the software you can start the CUPS server by
288 <B>/usr/sbin/cupsd ENTER</B>
292 <H2><A NAME="BINARY">Installing a Binary Distribution</A></H2>
294 <P>CUPS comes in a variety of binary distribution formats. Easy
295 Software Products provides binaries in TAR format with installation and
296 removal scripts ("portable" distributions), and in RPM and DPKG formats
297 for Red Hat and Debian-based distributions. Portable distributions are
298 available for all platforms, while the RPM and DPKG distributions are
299 only available for Linux.
301 <CENTER><TABLE WIDTH="80%" BORDER="1" BGCOLOR="#cccccc" CELLPADDING="5">
306 <P>Installing CUPS will overwrite your existing printing
307 system. If you experience difficulties with the CUPS software
308 and need to go back to your old printing system, you will need
309 to remove the CUPS software with the provided script and/or
310 reinstall the old printing system from your operating system CDs.
316 <H3><A NAME="PORTABLE-BINARY">Installing a Portable Distribution</A></H3>
318 <P>To install the CUPS software from a portable distribution you will
319 need to be logged in as root; doing an <CODE>su</CODE> is good enough.
320 Once you are the root user, run the installation script with:
323 <B>./cups.install ENTER</B>
326 <P>After asking you a few yes/no questions the CUPS software will be
327 installed and the scheduler will be started automatically.
330 <H3><A NAME="RPM-BINARY">Installing an RPM Distribution</A></H3>
332 <P>To install the CUPS software from an RPM distribution you will need
333 to be logged in as root; doing an <CODE>su</CODE> is good enough. Once
334 you are the root user, run RPM with:
338 <B>rpm -i cups-1.1-linux-M.m.n-intel.rpm ENTER</B>
341 <P>After a short delay the CUPS software will be
342 installed and the scheduler will be started automatically.
344 <H3><A NAME="DPKG-BINARY">Installing an Debian Distribution</A></H3>
346 <P>To install the CUPS software from a Debian distribution you will
347 need to be logged in as root; doing an <CODE>su</CODE> is good enough.
348 Once you are the root user, run dpkg with:
351 <B>dpkg -i cups-1.1-linux-M.m.n-intel.deb ENTER</B>
354 <P>After a short delay the CUPS software will be installed and the
355 scheduler will be started automatically.
358 <H1 ALIGN="RIGHT"><A NAME="MANAGING_PRINTERS">3 - Managing Printers</A></H1>
360 <P>This chapter describes how to add your first printer and how to
361 manage your printers.
365 <P>Each printer queue has a name associated with it; the printer name
366 must start with a letter and can contain up to 127 letters, numbers,
367 and the underscore (_). Case is not significant, e.g. "PRINTER", "Printer",
368 and "printer" are considered to be the same name.
370 <P>Printer queues also have a device associated with them. The device can be
371 a parallel port, a network interface, and so forth. Devices within CUPS use
372 Uniform Resource Identifiers ("URIs") which are a more general form of
373 Uniform Resource Locators ("URLs") that are used in your web browser. For
374 example, the first parallel port in Linux usually uses a device URI of
375 <CODE>parallel:/dev/lp1</CODE>.
378 <P>You can see a complete list of supported devices by running the
379 <CODE>lpinfo(8)</CODE> command:
382 <B>lpinfo -v ENTER</B>
387 direct parallel:/dev/lp1
388 serial serial:/dev/ttyS1?baud=115200
389 serial serial:/dev/ttyS2?baud=115200
390 direct usb:/dev/usb/lp0
394 <P>The <CODE>-v</CODE> option specifies that you want a list of available
395 devices. The first word in each line is the type of device (direct, file,
396 network, or serial) and is followed by the device URI or method name for
397 that device. File devices have device URIs of the form
398 <CODE>file:/directory/filename</CODE> while network devices use the more
399 familiar <CODE>method://server</CODE> or <CODE>method://server/path</CODE>
402 <P>Finally, printer queues usually have a PostScript Printer Description
403 ("PPD") file associated with them. PPD files describe the capabilities of
404 each printer, the page sizes supported, etc., and are used for PostScript
405 and non-PostScript printers. CUPS includes PPD files for HP LaserJet, HP
406 DeskJet, EPSON 9-pin, EPSON 24-pin, and EPSON Stylus printers.
408 <H2>Adding Your First Printer</H2>
410 <P>CUPS provides two methods for adding printers: a command-line
411 program called <CODE>lpadmin(8)</CODE> and a Web interface. The
412 <CODE>lpadmin</CODE> command allows you to perform most printer
413 administration tasks from the command-line and is located in
414 <VAR>/usr/sbin</VAR>. The Web interface is located at:
417 <A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
420 <P>and steps you through printer configuration. If you don't like
421 command-line interfaces, try the <A HREF="#ADD_WEB">Web interface</A> instead.
423 <H3>Adding Your First Printer from the Command-Line</H3>
425 <P>Run the <CODE>lpadmin</CODE> command with the <CODE>-p</CODE> option to add a
429 <B>/usr/sbin/lpadmin -p <I>printer</I> -E -v <I>device</I> -m <I>ppd</I> ENTER</B>
432 <P>For a HP DeskJet printer connected to the parallel port this would look
436 <B>/usr/sbin/lpadmin -p DeskJet -E -v parallel:/dev/lp1 -m deskjet.ppd ENTER</B>
439 <P>Similarly, a HP LaserJet printer using a JetDirect network interface at
440 IP address 11.22.33.44 would be added with the command:
443 <B>/usr/sbin/lpadmin -p LaserJet -E -v socket://11.22.33.44 -m laserjet.ppd ENTER</B>
446 <P>As you can see, <CODE>deskjet.ppd</CODE> and <CODE>laserjet.ppd</CODE> are
447 the PPD files for the HP DeskJet and HP LaserJet drivers included with CUPS.
448 You'll find a complete list of PPD files and the printers they will work with
449 in <A HREF="#PRINTER_DRIVERS">Appendix C, "Printer Drivers"</A>.
452 <P>For a dot matrix printer connected to the serial port this would might look like:
455 <B>/usr/sbin/lpadmin -p DotMatrix -E -v serial:/dev/ttyS0?baud=9600+size=8+parity=none+flow=soft deskjet.ppd ENTER</B>
458 <P>Here you specify the serial port (e.g. S0,S1, d0, d1), baud rate
459 (e.g. 9600, 19200, 38400, 115200, etc.), number of bits, parity, and flow control.
460 If you do not need flow control, delete the "+flow=soft" portion.
463 <H3><A NAME="ADD_WEB">Adding Your First Printer from the Web</A></H3>
465 <P>The CUPS web server provides a user-friendly "wizard" interface for
466 adding your printers. Rather than figuring out which device URI and PPD file
467 to use, you can instead click on the appropriate listings and fill in some
468 simple information. Enter the following URL in your web browser to begin:
471 <A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
474 <P>Click on the <VAR>Add Printer</VAR> button to add a printer.
476 <H2>Managing Printers from the Command-Line</H2>
478 <P>The <CODE>lpadmin</CODE> command enables you to perform most printer
479 administration tasks from the command-line. You'll find <CODE>lpadmin</CODE>
480 in the <VAR>/usr/sbin</VAR> directory.
482 <H3>Adding and Modifying Printers</H3>
484 <P>Run the <CODE>lpadmin</CODE> command with the <CODE>-p</CODE> option
485 to add or modify a printer:
488 <B>/usr/sbin/lpadmin -p <I>printer</I> <I>options</I> ENTER</B>
491 <P>The <I>options</I> arguments can be any of the following:
498 <DD>Adds the named printer to printer class <VAR>class</VAR>.
499 If the class does not exist then it is created.
501 <DT>-i <I>interface</I>
503 <DD>Copies the named <VAR>interface</VAR> script to the printer.
504 Interface scripts are used by System V printer drivers. Since
505 all filtering is disabled when using an interface script, scripts
506 generally should not be used unless there is no other driver for
511 <DD>Specifies a standard printer driver which is usually a PPD
512 file. A list of all available models can be displayed using the
513 <CODE>lpinfo</CODE> command with the <CODE>-m</CODE> option. A
514 list of printer drivers included with CUPS can be found in
515 <A HREF="#PRINTER_DRIVERS">Appendix C, "Printer Drivers"</A>.
519 <DD>Removes the named printer from printer class <VAR>class</VAR>.
520 If the resulting class becomes empty then it is removed.
522 <DT>-v <I>device-uri</I>
524 <DD>Sets the device for communicating with the printer. If a
525 job is currently printing on the named printer then the job
526 will be restarted and sent to the new device.
530 <DD>Provides a textual description of the printer, e.g.
531 "John's Personal Printer".
535 <DD>Enables the printer and accepts job. This option is
536 equivalent to running the <CODE>enable(1)</CODE> and
537 <CODE>accept(8)</CODE> commands on the printer.
539 <DT>-L <I>location</I>
541 <DD>Provides a textual location for the printer, e.g.
544 <DT>-P <I>ppd-file</I>
546 <DD>Specifies a local PPD file for the printer driver.
551 <H3>Deleting Printers</H3>
553 <P>Run the <CODE>lpadmin</CODE> command with the <CODE>-x</CODE> option
557 <B>/usr/sbin/lpadmin -x <I>printer</I> ENTER</B>
560 <H3>Setting the Default Printer</H3>
562 <P>Run the <CODE>lpadmin</CODE> command with the <CODE>-d</CODE> option
563 to set a default printer:
566 <B>/usr/sbin/lpadmin -d <I>printer</I> ENTER</B>
569 <P>The default printer can be overridden by the user using the
570 <CODE>lpoptions(1)</CODE> command.
572 <H3>Starting and Stopping Printers</H3>
574 <P>The <CODE>enable</CODE> and <CODE>disable</CODE> commands start and stop
575 printer queues, respectively:
578 <B>/usr/bin/enable <I>printer</I> ENTER</B>
579 <B>/usr/bin/disable <I>printer</I> ENTER</B>
582 <P>Printers that are disabled may still accept jobs for printing, but won't
583 actually print any files until they are restarted. This is useful if the
584 printer malfunctions and you need time to correct the problem. Any queued
585 jobs are printed after the printer is enabled (started).
587 <H3>Accepting and Rejecting Print Jobs</H3>
589 <P>The <CODE>accept</CODE> and <CODE>reject</CODE> commands accept and reject
590 print jobs for the named printer, respectively:
593 <B>/usr/sbin/accept <I>printer</I> ENTER</B>
594 <B>/usr/sbin/reject <I>printer</I> ENTER</B>
597 <P>As noted above, a printer can be stopped but accepting new print
598 jobs. A printer can also be rejecting new print jobs while it finishes
599 those that have been queued. This is useful for when you must perform
600 maintenance on the printer and will not have it available to users for
601 a long period of time.
603 <H3>Setting Quotas on a Printer</H3>
605 <P>CUPS supports page and size-based quotas for each printer.
606 The quotas are tracked individually for each user, but a single set of
607 limits applies to all users for a partiuclar printer. For example, you
608 can limit every user to 5 pages per day on an expensive printer, but
609 you cannot limit every user except Johnny.</P>
611 <P>The <I>job-k-limit</I>, <I>job-page-limit</I>, and <I>job-quota-peiod</I>
612 options determine whether and how quotas are enforced for a printer.
613 The <I>job-quota-period</I> option determines the time interval for
614 quota tracking. The interval is expressed in seconds, so a day is
615 86,400, a week is 604,800 and a month is 2,592,000 seconds. The
616 <I>job-k-limit</I> option specifies the job size limit in killobytes. The
617 <I>job-page-limit</I> option specifies the number of pages limit.</P>
619 <P>For quotas to be enforced, the period and at least one of the limits
620 must be set to a non-zero value. The following options will enable
625 <B>/usr/sbin/lpadmin -p <I>printer</I> -o job-quota-period=604800 -o job-k-limit=1024 <I>ENTER</I></B>
626 <B>/usr/sbin/lpadmin -p <I>printer</I> -o job-quota-period=604800 -o job-page-limit=100 <I>ENTER</I></B>
630 <P>Or, you can combine all three options on the same line.</P>
632 <H3>Restricting User Access to a Printer</H3>
634 <P>The <CODE>-u</CODE> option of the <CODE>lpadmin</CODE> command controls which users can
635 print to a printer. The default configuration allows all users to print
640 <B>/usr/sbin/lpadmin -p <I>printer</I> -u allow:all <I>ENTER</I></B>
644 <P>CUPS supports allow and deny lists so that you can specify a
645 list of users who are allowed to print or not allowed to print. Along
646 with your list of users, you can specify whether they are allowed or
647 not allowed to use the printer:</P>
651 <B>/usr/sbin/lpadmin -p <I>printer</I> -u allow:peter,paul,mary <I>ENTER</I></B>
655 <P>This command allows peter, paul, and mary to print to the named
656 printer, but all other users cannot print. The command:</P>
660 <B>/usr/sbin/lpadmin -p <I>printer</I> -u deny:peter,paul,mary <I>ENTER</I></B>
664 <P>has the opposite effect. All users except peter, paul, and mary will
665 be able to print to the named printer.</P>
667 <P>You can control access by UNIX groups as well by placing an
668 "@" character before each group name. The command:</P>
672 <B>/usr/sbin/lpadmin -p <I>printer</I> -u allow:peter,paul,mary,@printgods <I>ENTER</I></B>
676 <P>allows the users peter, paul, and mary to print, as well as
677 any user in the printgods group to print.
680 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
684 <P>The <I>allow</I> and <I>deny</I> options are not cummulative. That
685 is, you must provide the complete list of users to allow or deny each
688 <P>Also, CUPS only maintains one list of users - the list can
689 allow or deny users from printing. If you specify an allow list and
690 then specify a deny list, the deny list will replace the allow list -
691 only one list is active at any time.</P>
698 <H2>Managing Printers from the Web</H2>
700 <P>The Web interface is located at:
703 <A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
706 <P>From there you can perform all printer management tasks with a few
710 <H1 ALIGN="RIGHT"><A NAME="PRINTER_CLASSES">4 - Printer Classes</A></H1>
712 <P>This chapter describes what printer classes are and how to manage them.
716 <P>CUPS provides collections of printers called <I>printer classes</I>. Jobs
717 sent to a class are forwarded to the first available printer in the class.
718 Classes can themselves be members of other classes, so it is possible for
719 you to define very large, distributed printer classes for high-availability
722 <P>CUPS also supports <I>implicit classes</I>. Implicit classes work just
723 like printer classes, but they are created automatically based upon the
724 available printers and classes on the network. This allows you to setup
725 multiple print servers with identical printer configurations and have the
726 client machines send their print jobs to the first available server. If
727 one or more servers go down, the jobs are automatically redirected to the
728 servers that are running, providing fail-safe printing.
730 <H2>Managing Printer Classes from the Command-Line</H2>
732 <P>Run the <CODE>lpadmin</CODE> command with the <CODE>-p</CODE> and <CODE>-c</CODE> options
733 to add a printer to a class:
736 <B>/usr/sbin/lpadmin -p <I>printer</I> -c <I>class</I> ENTER</B>
739 <P>The <I>class</I> is created automatically if it doesn't exist. To remove a
740 printer from a class use the <CODE>-r</CODE> option:
743 <B>/usr/sbin/lpadmin -p <I>printer</I> -r <I>class</I> ENTER</B>
746 <P>To remove the entire class just use the <CODE>-x</CODE> option:
749 <B>/usr/sbin/lpadmin -x <I>class</I> ENTER</B>
752 <H2>Managing Printer Classes from the Web Interface</H2>
754 <P>The Web interface is located at:
757 <A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
760 <P>The <VAR>Add Class</VAR> and <VAR>Modify Class</VAR> interfaces provide a
761 list of available printers; click on the printers of interest to add them to
764 <H2>Implicit Classes</H2>
766 <P>A noted earlier, implicit classes are created automatically from the
767 available network printers and classes. To disable this functionality,
768 set the <A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
769 directive to <CODE>Off</CODE> in the <CODE>cupsd.conf</CODE> file. You
770 will find more information on doing this in
771 <A HREF="#PRINTING_MANAGEMENT">Chapter 6, "Printing System
775 <H1 ALIGN="RIGHT"><A NAME="CLIENT_SETUP">5 - Client Setup</A></H1>
777 <P>This chapter discusses several ways to configure CUPS clients for
782 <P>A client is any machine that sends print jobs to another machine for
783 final printing. Clients can also be servers if they communicate directly with
784 any printers of their own.
786 <P>CUPS supports several methods of configuring client machines:
789 <LI><A HREF="#CLIENT_MANUAL">Manual configuration of print queues.</A>
790 <LI><A HREF="#CLIENT_SERVER">Specifying a single server for printing.</A>
791 <LI><A HREF="#CLIENT_AUTO">Automatic configuration of print queues.</A>
792 <LI><A HREF="#CLIENT_POLL">Specifying multiple servers for printing.</A>
793 <LI><A HREF="#CLIENT_RELAY">Relaying printers to other clients.</A>
796 <H3><A NAME="CLIENT_MANUAL">Manual Configuration of Print Queues</A></H3>
798 <P>The most tedious method of configuring client machines is to configure
799 each remote queue by hand using the <CODE>lpadmin</CODE> command:
802 <B>lpadmin -p <I>printer</I> -E -v ipp://<I>server</I>/printers/<I>printer</I> ENTER</B>
805 <P>The <CODE>printer</CODE> name is the name of the printer on the server
806 machine. The <CODE>server</CODE> name is the hostname or IP address of the
807 server machine. Repeat the <CODE>lpadmin</CODE> command for each remote
808 printer you wish to use.</P>
811 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
814 <P>Manual configuration of print queues is not recommended for large
815 numbers of client machines because of the administration nightmare it
816 creates. For busy networks, consider subnetting groups of clients and
817 polling and relaying printer information instead.</P>
823 <H3><A NAME="CLIENT_SERVER">Specifying a Single Server for Printing</A></H3>
825 <P>CUPS can be configured to run without a local spooler and send all
826 jobs to a single server. However, if that server goes down then all
827 printing will be disabled. Use this configuration only as absolutely needed.
829 <P>The default server is normally "localhost". To override the default
830 server create a file named <VAR>/etc/cups/client.conf</VAR> and add
834 ServerName <I>server</I>
837 <P>to the file. The <VAR>server</VAR> name can be the hostname or IP address
838 of the default server.
840 <P>The default server can also be customized on a per-user basis. To set a
841 user-specific server create a file named <VAR>~/.cupsrc</VAR> and add a line
845 ServerName <I>server</I>
848 <P>to the file. The <VAR>server</VAR> name can be the hostname or IP
849 address of the default server.
851 <H3><A NAME="CLIENT_AUTO">Automatic Configuration of Print Queues</A></H3>
853 <P>CUPS supports automatic client configuration of printers on the same
854 subnet. To configure printers on the same subnet, <I>do nothing</I>.
855 Each client should see the available printers within 30 seconds
856 automatically. The printer and class lists are updated automatically as
857 printers and servers are added or removed.
859 <P>If you want to see printers on other subnets as well, use the
860 <A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A>
861 directive as described next.</P>
864 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
867 <P>The<A HREF="#BrowseAddress"> <CODE>BrowseAddress</CODE></A> directive
868 enables broadcast traffic from your server. The default configuration
869 braodcasts printer information every 30 seconds. Although this printer
870 information does not use much bandwidth, typically about 80 bytes per
871 printer, it can add up with large numbers of servers and printers.</P>
872 <P>Use the <A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A>
873 and <A HREF="#BrowseTimeout"><CODE>BrowseTimeout</CODE></A> directives to tune
874 the amount of data that is added to your network load. In addition,
875 subnets can be used to minimize the amount of traffic that is carried
876 by the "backbone" of your large network.</P>
882 <H3><A NAME="CLIENT_POLL">Specifying Multiple Servers for Printing</A></H3>
884 <P>If you have CUPS servers on different subnets, then you should configure
885 CUPS to poll those servers. Polling provides the benefits of automatic
886 configuration without significant configuration on the clients, and multiple
887 clients on the same subnet can share the same configuration information.
889 <P>Polling is enabled by specifying one or more
890 <A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A>
891 directives in the <VAR>/etc/cups/cupsd.conf</VAR> file.
892 For information on making these changes, see
893 <A HREF="#PRINTING_MANAGEMENT">Chapter 6, "Printing System Management"</A>.
895 <P>Multiple <A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A> lines can
896 be used to poll multiple CUPS servers. To limit the amount of
897 polling you do from client machines, you can have only one of the
898 clients do the polling and relay that information to the others on the
899 same subnet (described next).</P>
901 <H3><A NAME="CLIENT_RELAY">Relaying Printers to Other Clients</A></H3>
903 <P>When you have clients and servers spread across multiple subnets, the
904 polling method is inefficient. CUPS provides a
905 <A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A> directive that enables a
906 single client to relay (broadcast) the polled printer information to the local subnet.</P>
908 <P>For example, Server A and Server B are on subnet 1 and subnet 2,
909 while the clients are on subnet 3.
910 To provide printers to all of the clients in subnet 3,
911 client C will be configured with the following directives in <VAR>/etc/cups/cupsd.conf</VAR>:</P>
914 # Poll the two servers
916 BrowsePoll ServerA ENTER
917 BrowsePoll ServerB ENTER
920 # Relay the printers to the local subnet
922 BrowseRelay 127.0.0.1 192.168.3.255 ENTER
925 <P>The <A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A> line specifies a source address and mask.
926 Any browse packets coming from a matching address wil be sent to the given broadcast address.
927 In this case, we want the packets from the local machine (127.0.0.1) relayed to the other clients.</P>
929 <P>As printers are found using polling,
930 they are relayed from client C to the rest of the clients through a broadcast on subnet 3.
931 The rest of the clients can use the standard <VAR>cupsd.conf</VAR> configuration.</P>
933 <P>The <A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A> directive can also be used to relay
934 browsing packets from one network interface to another.
935 For example, if client C in the previous example had network interfaces attaches to both
936 subnet 1 and subnet 2, it could use the <A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A> directive exclusively:
939 # Relay the printers from subnet 1 and 2 to subnet 3
941 BrowseRelay 192.168.1 192.168.3.255 ENTER
942 BrowseRelay 192.168.2 192.168.3.255 ENTER
945 <H2>Load Balancing and Failsafe Operation</H2>
947 <P>When using server polling or broadcasting, CUPS clients can
948 automatically merge identical printers on multiple servers into a
949 single <I>implicit class</I> queue. Clients assume that printers with
950 the same name on multiple servers are in fact the same printer or type
951 of printer being served by multiple machines.</P>
953 <P>If you have two printers, LaserJet@ServerA and LaserJet@ServerB, a
954 third implicit class called <I>LaserJet</I> will be created
955 automatically on the client that refers to both printers. If the client
956 also has a local printer with the name LaserJet then an implicit class
957 named <I>AnyLaserJet</I> will be created instead.</P>
959 <P>The client will alternate between servers and automatically stop
960 sending jobs to a server if it goes down, providing a load-balancing
961 effect and fail-safe operation with automatic switchover.</P>
963 <CENTER><TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
966 <P>Note that implicit classes (<A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>)
967 are enabled by default.</P>
972 <H1 ALIGN="RIGHT"><A NAME="PRINTING_MANAGEMENT">6 - Printing System Management</A></H1>
974 <P>This chapter shows how you can configure the CUPS server.
978 <P>Several text files are used to configure CUPS. All of the server
979 configuration files are located in the <VAR>/etc/cups</VAR> directory:
987 <DD>This file contains information on each printer class.
988 Normally you manipulate this file using the
989 <CODE>lpadmin</CODE> command or the Web interface.<BR>
994 <DD>This file provides the default server name for client
995 machines. See <A HREF="#CLIENT_SETUP">Chapter 5, "Client
996 Setup"</A> for more information.<BR>
1001 <DD>This file controls how the CUPS server
1002 (<VAR>/usr/sbin/cupsd</VAR>) operates and is normally edited by
1008 <DD>This file contains a list of standard file conversion filters
1009 and their costs. You normally do not edit this file.<BR>
1014 <DD>This file contains a list of standard file formats and how to
1015 recognize them. You normally do not edit this file.<BR>
1020 <DD>This file contains information on each printer. Normally
1021 you manipulate this file using the <CODE>lpadmin</CODE> command
1022 or the Web Interface.<BR>
1027 <H2><A NAME="RESTARTING">Restarting the CUPS Server</A></H2>
1029 <P>Once you have made a change to a configuration file you need to
1030 restart the CUPS server by sending it a <CODE>HUP</CODE> signal or using the
1031 supplied initialization script. The CUPS distributions install the
1032 script in the <VAR>init.d</VAR> directory with the name
1033 <VAR>cups</VAR>. The location varies based upon the operating system:
1036 <B>/etc/software/init.d/cups restart ENTER</B>
1037 <B>/etc/rc.d/init.d/cups restart ENTER</B>
1038 <B>/etc/init.d/cups restart ENTER</B>
1039 <B>/sbin/init.d/cups restart ENTER</B>
1042 <H2>Changing the Server Configuration</H2>
1044 <P>The <VAR>/etc/cups/cupsd.conf</VAR> file contains configuration
1045 <I>directives</I> that control how the server functions. Each directive
1046 is listed on a line by itself followed by its value. Comments are
1047 introduced using the number sign ("#") character at the beginning of a
1048 line. Since the server configuration file consists of plain text, you
1049 can use your favorite text editor to make changes to it.
1052 <H2>Server Directives</H2>
1054 <P>The <VAR>cupsd.conf</VAR> file contains many directives that
1055 determine how the server operates:
1058 <TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
1062 <LI><A HREF="#AccessLog"><CODE>AccessLog</CODE></A>
1063 <LI><A HREF="#Allow"><CODE>Allow</CODE></A>
1064 <LI><A HREF="#AuthClass"><CODE>AuthClass</CODE></A>
1065 <LI><A HREF="#AuthGroupName"><CODE>AuthGroupName</CODE></A>
1066 <LI><A HREF="#AuthType"><CODE>AuthType</CODE></A>
1067 <LI><A HREF="#AutoPurgeJobs"><CODE>AutoPurgeJobs</CODE></A>
1068 <LI><A HREF="#BrowseAddress"><CODE>BrowseAddress</CODE></A>
1069 <LI><A HREF="#BrowseAllow"><CODE>BrowseAllow</CODE></A>
1070 <LI><A HREF="#BrowseDeny"><CODE>BrowseDeny</CODE></A>
1071 <LI><A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A>
1072 <LI><A HREF="#BrowseOrder"><CODE>BrowseOrder</CODE></A>
1073 <LI><A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A>
1074 <LI><A HREF="#BrowsePort"><CODE>BrowsePort</CODE></A>
1075 <LI><A HREF="#BrowseProtocols"><CODE>BrowseProtocols</CODE></A>
1076 <LI><A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A>
1077 <LI><A HREF="#BrowseShortNames"><CODE>BrowseShortNames</CODE></A>
1078 <LI><A HREF="#BrowseTimeout"><CODE>BrowseTimeout</CODE></A>
1079 <LI><A HREF="#Browsing"><CODE>Browsing</CODE></A>
1080 <LI><A HREF="#Classification"><CODE>Classification</CODE></A>
1081 <LI><A HREF="#ClassifyOverride"><CODE>ClassifyOverride</CODE></A>
1082 <LI><A HREF="#ConfigFilePerm"><CODE>ConfigFilePerm</CODE></A>
1083 <LI><A HREF="#DataDir"><CODE>DataDir</CODE></A>
1084 <LI><A HREF="#DefaultCharset"><CODE>DefaultCharset</CODE></A>
1085 <LI><A HREF="#DefaultLanguage"><CODE>DefaultLanguage</CODE></A>
1086 <LI><A HREF="#Deny"><CODE>Deny</CODE></A>
1087 <LI><A HREF="#DocumentRoot"><CODE>DocumentRoot</CODE></A>
1088 <LI><A HREF="#Encryption"><CODE>Encryption</CODE></A>
1096 <LI><A HREF="#ErrorLog"><CODE>ErrorLog</CODE></A>
1097 <LI><A HREF="#FilterLimit"><CODE>FilterLimit</CODE></A>
1098 <LI><A HREF="#FilterNice"><CODE>FilterNice</CODE></A>
1099 <LI><A HREF="#FontPath"><CODE>FontPath</CODE></A>
1100 <LI><A HREF="#Group"><CODE>Group</CODE></A>
1101 <LI><A HREF="#HideImplicitMembers"><CODE>HideImplicitMembers</CODE></A>
1102 <LI><A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A>
1103 <LI><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
1104 <LI><A HREF="#ImplicitAnyClasses"><CODE>ImplicitAnyClasses</CODE></A>
1105 <LI><A HREF="#Include"><CODE>Include</CODE></A>
1106 <LI><A HREF="#KeepAliveTimeout"><CODE>KeepAliveTimeout</CODE></A>
1107 <LI><A HREF="#KeepAlive"><CODE>KeepAlive</CODE></A>
1108 <LI><A HREF="#Limit"><CODE>Limit</CODE></A>
1109 <LI><A HREF="#LimitExcept"><CODE>LimitExcept</CODE></A>
1110 <LI><A HREF="#LimitRequestBody"><CODE>LimitRequestBody</CODE></A>
1111 <LI><A HREF="#Listen"><CODE>Listen</CODE></A>
1112 <LI><A HREF="#Location"><CODE>Location</CODE></A>
1113 <LI><A HREF="#LogFilePerm"><CODE>LogFilePerm</CODE></A>
1114 <LI><A HREF="#LogLevel"><CODE>LogLevel</CODE></A>
1115 <LI><A HREF="#MaxClients"><CODE>MaxClients</CODE></A>
1116 <LI><A HREF="#MaxCopies"><CODE>MaxCopies</CODE></A>
1117 <LI><A HREF="#MaxJobs"><CODE>MaxJobs</CODE></A>
1118 <LI><A HREF="#MaxJobsPerPrinter"><CODE>MaxJobsPerPrinter</CODE></A>
1119 <LI><A HREF="#MaxJobsPerUser"><CODE>MaxJobsPerUser</CODE></A>
1120 <LI><A HREF="#MaxLogSize"><CODE>MaxLogSize</CODE></A>
1121 <LI><A HREF="#MaxRequestSize"><CODE>MaxRequestSize</CODE></A>
1122 <LI><A HREF="#Order"><CODE>Order</CODE></A>
1123 <LI><A HREF="#PageLog"><CODE>PageLog</CODE></A>
1131 <LI><A HREF="#Port"><CODE>Port</CODE></A>
1132 <LI><A HREF="#PreserveJobFiles"><CODE>PreserveJobFiles</CODE></A>
1133 <LI><A HREF="#PreserveJobHistory"><CODE>PreserveJobHistory</CODE></A>
1134 <LI><A HREF="#Printcap"><CODE>Printcap</CODE></A>
1135 <LI><A HREF="#PrintcapFormat"><CODE>PrintcapFormat</CODE></A>
1136 <LI><A HREF="#PrintcapGUI"><CODE>PrintcapGUI</CODE></A>
1137 <LI><A HREF="#RemoteRoot"><CODE>RemoteRoot</CODE></A>
1138 <LI><A HREF="#RequestRoot"><CODE>RequestRoot</CODE></A>
1139 <LI><A HREF="#Require"><CODE>Require</CODE></A>
1140 <LI><A HREF="#RIPCache"><CODE>RIPCache</CODE></A>
1141 <LI><A HREF="#RootCertDuration"><CODE>RootCertDuration</CODE></A>
1142 <LI><A HREF="#RunAsUser"><CODE>RunAsUser</CODE></A>
1143 <LI><A HREF="#Satisfy"><CODE>Satisfy</CODE></A>
1144 <LI><A HREF="#ServerAdmin"><CODE>ServerAdmin</CODE></A>
1145 <LI><A HREF="#ServerBin"><CODE>ServerBin</CODE></A>
1146 <LI><A HREF="#ServerCertificate"><CODE>ServerCertificate</CODE></A>
1147 <LI><A HREF="#ServerKey"><CODE>ServerKey</CODE></A>
1148 <LI><A HREF="#ServerName"><CODE>ServerName</CODE></A>
1149 <LI><A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A>
1150 <LI><A HREF="#ServerTokens"><CODE>ServerTokens</CODE></A>
1151 <LI><A HREF="#SSLListen"><CODE>SSLListen</CODE></A>
1152 <LI><A HREF="#SSLPort"><CODE>SSLPort</CODE></A>
1153 <LI><A HREF="#SystemGroup"><CODE>SystemGroup</CODE></A>
1154 <LI><A HREF="#TempDir"><CODE>TempDir</CODE></A>
1155 <LI><A HREF="#Timeout"><CODE>Timeout</CODE></A>
1156 <LI><A HREF="#User"><CODE>User</CODE></A>
1164 <H3><A NAME="AccessLog">AccessLog</A></H3>
1170 AccessLog /var/log/cups/access_log
1171 AccessLog /var/log/cups/access_log-%s
1175 <H4>Description</H4>
1177 <P>The <CODE>AccessLog</CODE> directive sets the name of the access log
1178 file. If the filename is not absolute then it is assumed to be relative
1179 to the <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
1180 access log file is stored in "common log format" and can be used by any
1181 web access reporting tool to generate a report on CUPS server activity.
1183 <P>The server name can be included in the filename by using
1184 <CODE>%s</CODE> in the name.
1186 <P>The special name "syslog" can be used to send the access information
1187 to the system log instead of a plain file.
1189 <P>The default access log file is <VAR>/var/log/cups/access_log</VAR>.
1192 <H3><A NAME="Allow">Allow</A></H3>
1200 Allow from *.domain.com
1201 Allow from .domain.com
1202 Allow from host.domain.com
1204 Allow from nnn.nnn.*
1205 Allow from nnn.nnn.nnn.*
1206 Allow from nnn.nnn.nnn.nnn
1207 Allow from nnn.nnn.nnn.nnn/mm
1208 Allow from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
1210 Allow from @IF(name)
1213 <H4>Description</H4>
1215 <P>The <CODE>Allow</CODE> directive specifies a hostname, IP address,
1216 or network that is allowed access to the server. <CODE>Allow</CODE>
1217 directives are cummulative, so multiple <CODE>Allow</CODE> directives
1218 can be used to allow access for multiple hosts or networks. The
1219 <CODE>/mm</CODE> notation specifies a CIDR netmask:
1221 <CENTER><TABLE BORDER="1">
1223 <TH WIDTH="10%">mm</TH>
1224 <TH WIDTH="20%">netmask</TH>
1225 <TH WIDTH="10%">mm</TH>
1226 <TH WIDTH="20%">netmask</TH>
1229 <TD ALIGN="CENTER">0</TD>
1230 <TD ALIGN="CENTER">0.0.0.0</TD>
1231 <TD ALIGN="CENTER">8</TD>
1232 <TD ALIGN="CENTER">255.0.0.0</TD>
1235 <TD ALIGN="CENTER">1</TD>
1236 <TD ALIGN="CENTER">128.0.0.0</TD>
1237 <TD ALIGN="CENTER">16</TD>
1238 <TD ALIGN="CENTER">255.255.0.0</TD>
1241 <TD ALIGN="CENTER">2</TD>
1242 <TD ALIGN="CENTER">192.0.0.0</TD>
1243 <TD ALIGN="CENTER">24</TD>
1244 <TD ALIGN="CENTER">255.255.255.0</TD>
1247 <TD ALIGN="CENTER">...</TD>
1248 <TD ALIGN="CENTER">...</TD>
1249 <TD ALIGN="CENTER">32</TD>
1250 <TD ALIGN="CENTER">255.255.255.255</TD>
1254 <P>The <CODE>@LOCAL</CODE> name will allow access from all local
1255 network interfaces, but not remote point-to-point interfaces. The
1256 <CODE>@IF(name)</CODE> name will allow access from the named
1259 <P>The <CODE>Allow</CODE> directive must appear inside a
1260 <A HREF="#Location"><CODE>Location</CODE></A> directive.
1263 <H3><A NAME="AuthClass">AuthClass</A></H3>
1275 <H4>Description</H4>
1277 <P>The <CODE>AuthClass</CODE> directive defines what level of authentication
1282 <LI><CODE>Anonymous</CODE> - No authentication should be performed
1285 <LI><CODE>User</CODE> - A valid username and password is required.
1287 <LI><CODE>System</CODE> - A valid username and password is
1288 required, and the username must belong to the "sys" group; this
1289 can be changed using the
1290 <A HREF="#SystemGroup"><CODE>SystemGroup</CODE></A> directive.
1292 <LI><CODE>Group</CODE> - A valid username and password is
1293 required, and the username must belong to the group named by
1294 the <CODE>AuthGroupName</CODE> directive.
1298 <P>The <CODE>AuthClass</CODE> directive must appear inside a
1299 <A HREF="#Location"><CODE>Location</CODE></A> directive.
1302 <H3><A NAME="AuthGroupName">AuthGroupName</A></H3>
1308 AuthGroupName mygroup
1312 <H4>Description</H4>
1314 <P>The <CODE>AuthGroupName</CODE> directive sets the group to use for
1315 <CODE>Group</CODE> authentication.
1317 <P>The <CODE>AuthGroupName</CODE> directive must appear inside a
1318 <A HREF="#Location"><CODE>Location</CODE></A> directive.
1321 <H3><A NAME="AuthType">AuthType</A></H3>
1330 AuthType BasicDigest
1333 <H4>Description</H4>
1335 <P>The <CODE>AuthType</CODE> directive defines the type of authentication to
1340 <LI><CODE>None</CODE> - No authentication should be performed
1343 <LI><CODE>Basic</CODE> - Basic authentication should be
1344 performed using the UNIX password and group files.
1346 <LI><CODE>Digest</CODE> - Digest authentication should be
1347 performed using the <VAR>/etc/cups/passwd.md5</VAR> file.
1349 <LI><CODE>BasicDigest</CODE> - Basic authentication should be
1350 performed using the <VAR>/etc/cups/passwd.md5</VAR> file.
1354 <P>When using <CODE>Basic</CODE>, <CODE>Digest</CODE>, or
1355 <CODE>BasicDigest</CODE> authentication, clients connecting
1356 through the <CODE>localhost</CODE> interface can also
1357 authenticate using <A HREF="#CERTIFICATES">certificates</A>.
1359 <P>The <CODE>AuthType</CODE> directive must appear inside a
1360 <A HREF="#Location"><CODE>Location</CODE></A> directive.
1363 <H3><A NAME="AutoPurgeJobs">AutoPurgeJobs</A></H3>
1373 <H4>Description</H4>
1375 <P>The <CODE>AutoPurgeJobs</CODE> directive specifies whether or not to purge
1376 completed jobs once they are no longer required for quotas. This option has
1377 no effect if quotas are not enabled. The default setting is <CODE>No</CODE>.
1380 <H3><A NAME="BrowseAddress">BrowseAddress</A></H3>
1386 BrowseAddress 255.255.255.255:631
1387 BrowseAddress 192.0.2.255:631
1388 BrowseAddress host.domain.com:631
1389 BrowseAddress @LOCAL
1390 BrowseAddress @IF(name)
1393 <H4>Description</H4>
1395 <P>The <CODE>BrowseAddress</CODE> directive specifies an address to
1396 send browsing information to. Multiple <CODE>BrowseAddress</CODE>
1397 directives can be specified to send browsing information to different
1398 networks or systems.
1400 <P>The <CODE>@LOCAL</CODE> name will broadcast printer
1401 information to all local interfaces. The <CODE>@IF(name)</CODE>
1402 name will broadcast to the named interface.
1404 <P>No browse addresses are set by default.</P>
1406 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
1411 <P>If you are using HP-UX 10.20 and a subnet that is not 24,
1412 16, or 8 bits, printer browsing (and in fact all broadcast
1413 reception) will not work. This problem appears to be fixed in
1420 <H3><A NAME="BrowseAllow">BrowseAllow</A></H3>
1426 BrowseAllow from all
1427 BrowseAllow from none
1428 BrowseAllow from 192.0.2
1429 BrowseAllow from 192.0.2.0/24
1430 BrowseAllow from 192.0.2.0/255.255.255.0
1431 BrowseAllow from *.domain.com
1432 BrowseAllow from @LOCAL
1433 BrowseAllow from @IF(name)
1436 <H4>Description</H4>
1438 <P>The <CODE>BrowseAllow</CODE> directive specifies a system or network
1439 to accept browse packets from. The default is to accept browse packets
1442 <P>Host and domain name matching require that you enable the
1443 <A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A> directive.
1445 <P>IP address matching supports exact matches, partial addresses that
1446 match networks using netmasks of 255.0.0.0, 255.255.0.0, and 255.255.255.0,
1447 or network addresses using the specified netmask or bit count.
1449 <P>The <CODE>@LOCAL</CODE> name will allow browse data from all
1450 local network interfaces, but not remote point-to-point
1451 interfaces. The <CODE>@IF(name)</CODE> name will allow browse
1452 data from the named interface.
1456 <H3><A NAME="BrowseDeny">BrowseDeny</A></H3>
1463 BrowseDeny from none
1464 BrowseDeny from 192.0.2
1465 BrowseDeny from 192.0.2.0/24
1466 BrowseDeny from 192.0.2.0/255.255.255.0
1467 BrowseDeny from *.domain.com
1468 BrowseDeny from @LOCAL
1469 BrowseDeny from @IF(name)
1472 <H4>Description</H4>
1474 <P>The <CODE>BrowseDeny</CODE> directive specifies a system or network
1475 to reject browse packets from. The default is to deny browse packets
1478 <P>Host and domain name matching require that you enable the
1479 <A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A> directive.
1481 <P>IP address matching supports exact matches, partial addresses that
1482 match networks using netmasks of 255.0.0.0, 255.255.0.0, and 255.255.255.0,
1483 or network addresses using the specified netmask or bit count.
1485 <P>The <CODE>@LOCAL</CODE> name will block browse data from all
1486 local network interfaces, but not remote point-to-point
1487 interfaces. The <CODE>@IF(name)</CODE> name will block browse
1488 data from the named interface.
1492 <H3><A NAME="BrowseOrder">BrowseOrder</A></H3>
1498 BrowseOrder allow,deny
1499 BrowseOrder deny,allow
1502 <H4>Description</H4>
1504 <P>The <CODE>BrowseOrder</CODE> directive specifies the order of allow/deny
1505 processing. The default order is <CODE>deny,allow</CODE>:
1509 <LI><CODE>allow,deny</CODE> - Browse packets are accepted unless
1510 specifically denied.
1512 <LI><CODE>deny,allow</CODE> - Browse packets are rejected unless
1513 specifically allowed.
1518 <H3><A NAME="BrowseInterval">BrowseInterval</A></H3>
1528 <H4>Description</H4>
1530 <P>The <CODE>BrowseInterval</CODE> directive specifies the maximum amount of
1531 time between browsing updates. Specifying a value of 0 seconds disables
1532 outgoing browse updates but allows a server to receive printer information
1535 <P>The <CODE>BrowseInterval</CODE> value should always be less than the
1536 <A HREF="#BrowseTimeout"><CODE>BrowseTimeout</CODE></A> value. Otherwise
1537 printers and classes will disappear from client systems between updates.
1540 <H3><A NAME="BrowsePoll">BrowsePoll</A></H3>
1546 BrowsePoll 192.0.2.2:631
1547 BrowsePoll host.domain.com:631
1550 <H4>Description</H4>
1552 <P>The <CODE>BrowsePoll</CODE> directive polls a server for available
1554 <A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A> seconds.
1555 Multiple <CODE>BrowsePoll</CODE> directives can be specified to poll
1558 <P>If <CODE>BrowseInterval</CODE> is set to 0 then the server is polled
1559 once every 30 seconds.
1562 <H3><A NAME="BrowsePort">BrowsePort</A></H3>
1572 <H4>Description</H4>
1574 <P>The <CODE>BrowsePort</CODE> directive specifies the UDP port number
1575 used for browse packets. The default port number is 631.</P>
1577 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
1582 <P>You must set the <CODE>BrowsePort</CODE> to the same value
1583 on all of the systems that you want to see.
1589 <H3><A NAME="BrowseProtocols">BrowseProtocols</A></H3>
1595 BrowseProtocols CUPS
1597 BrowseProtocols CUPS SLP
1601 <H4>Description</H4>
1603 <P>The <CODE>BrowseProtocols</CODE> directive specifies the protocols to
1604 use when collecting and distributing shared printers on the local network.
1605 The default protocol is <CODE>CUPS</CODE>, which is a broadcast-based
1608 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
1613 <P>When using the <CODE>SLP</CODE> protocol, you must have at least
1614 one Directory Agent (DA) server on your network. Otherwise the
1615 CUPS scheduler (<CODE>cupsd</CODE>) will not respond to client
1616 requests for several seconds while polling the network.
1622 <H3><A NAME="BrowseRelay">BrowseRelay</A></H3>
1628 BrowseRelay 193.0.2.1 192.0.2.255
1629 BrowseRelay 193.0.2.0/255.255.255.0 192.0.2.255
1630 BrowseRelay 193.0.2.0/24 192.0.2.255
1631 BrowseRelay *.domain.com 192.0.2.255
1632 BrowseRelay host.domain.com 192.0.2.255
1635 <H4>Description</H4>
1637 <P>The <CODE>BrowseRelay</CODE> directive specifies source and destination
1638 addresses for relaying browsing information from one host or network to
1639 another. Multiple <CODE>BrowseRelay</CODE> directives can be specified
1642 <P><CODE>BrowseRelay</CODE> is typically used on systems that bridge
1643 multiple subnets using one or more network interfaces. It can also be
1644 used to relay printer information from polled servers with the line:
1647 BrowseRelay 127.0.0.1 255.255.255.255
1650 <P>This effectively provides access to printers on a WAN for all clients
1654 <H3><A NAME="BrowseShortNames">BrowseShortNames</A></H3>
1660 BrowseShortNames Yes
1664 <H4>Description</H4>
1666 <P>The <CODE>BrowseShortNames</CODE> directive specifies whether or not
1667 short names are used for remote printers when possible. Short names are
1668 just the remote printer name, without the server ("printer"). If more than
1669 one remote printer is detected with the same name, the printers will have
1670 long names ("printer@server1", "printer@server2".)
1672 <P>The default value for this option is <CODE>Yes</CODE>.
1675 <H3><A NAME="BrowseTimeout">BrowseTimeout</A></H3>
1685 <H4>Description</H4>
1687 <P>The <CODE>BrowseTimeout</CODE> directive sets the timeout for
1688 printer or class information that is received in browse packets. Once a
1689 printer or class times out it is removed from the list of available
1692 <P>The <CODE>BrowseTimeout</CODE> value should always be greater than the
1693 <A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A> value. Otherwise
1694 printers and classes will disappear from client systems between updates.
1697 <H3><A NAME="Browsing">Browsing</A></H3>
1707 <H4>Description</H4>
1709 <P>The <CODE>Browsing</CODE> directive controls whether or not network printer
1710 browsing is enabled. The default setting is <CODE>On</CODE>.</P>
1712 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
1717 <P>If you are using HP-UX 10.20 and a subnet that is not 24,
1718 16, or 8 bits, printer browsing (and in fact all broadcast
1719 reception) will not work. This problem appears to be fixed in
1726 <H3><A NAME="Classification">Classification</A></H3>
1733 Classification classified
1734 Classification confidential
1735 Classification secret
1736 Classification topsecret
1737 Classification unclassified
1740 <H4>Description</H4>
1742 <P>The <CODE>Classification</CODE> directive sets the classification level
1743 on the server. When this option is set, at least one of the banner pages
1744 is forced to the classification level, and the classification is placed
1745 on each page of output. The default is no classification level.
1748 <H3><A NAME="ClassifyOverride">ClassifyOverride</A></H3>
1754 ClassifyOverride Yes
1758 <H4>Description</H4>
1760 <P>The <CODE>ClassifyOverride</CODE> directive specifies whether users
1761 can override the default classification level on the server. When the
1762 server classification is set, users can change the classification using
1763 the <CODE>job-sheets</CODE> option and can choose to only print one
1764 security banner before or after the job. If the <CODE>job-sheets</CODE>
1765 option is set to <CODE>none</CODE> then the server default classification
1768 <P>The default is to not allow classification overrides.
1771 <H3><A NAME="ConfigFilePerm">ConfigFilePerm</A></H3>
1781 <H4>Description</H4>
1783 <P>The <CODE>ConfigFilePerm</CODE> directive specifies the permissions
1784 to use when writing configuration files. The default is 0600.
1787 <H3><A NAME="DataDir">DataDir</A></H3>
1793 DataDir /usr/share/cups
1796 <H4>Description</H4>
1798 <P>The <CODE>DataDir</CODE> directive sets the directory to use for data
1802 <H3><A NAME="DefaultCharset">DefaultCharset</A></H3>
1808 DefaultCharset utf-8
1809 DefaultCharset iso-8859-1
1810 DefaultCharset windows-1251
1813 <H4>Description</H4>
1815 <P>The <CODE>DefaultCharset</CODE> directive sets the default character set
1816 to use for client connections. The default character set is
1817 <CODE>utf-8</CODE> but is overridden by the character set for the language
1818 specified by the client or the <CODE>DefaultLanguage</CODE> directive.
1821 <H3><A NAME="DefaultLanguage">DefaultLanguage</A></H3>
1834 <H4>Description</H4>
1836 <P>The <CODE>DefaultLanguage</CODE> directive specifies the default language
1837 to use for client connections. Setting the default language also sets the
1838 default character set if a language localization file exists for it. The
1839 default language is "en" for English.
1842 <H3><A NAME="Deny">Deny</A></H3>
1850 Deny from *.domain.com
1851 Deny from .domain.com
1852 Deny from host.domain.com
1855 Deny from nnn.nnn.nnn.*
1856 Deny from nnn.nnn.nnn.nnn
1857 Deny from nnn.nnn.nnn.nnn/mm
1858 Deny from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
1863 <H4>Description</H4>
1865 <P>The <CODE>Deny</CODE> directive specifies a hostname, IP address, or
1866 network that is allowed access to the server. <CODE>Deny</CODE>
1867 directives are cummulative, so multiple <CODE>Deny</CODE> directives
1868 can be used to allow access for multiple hosts or networks. The
1869 <CODE>/mm</CODE> notation specifies a CIDR netmask:
1871 <CENTER><TABLE BORDER="1">
1873 <TH WIDTH="10%">mm</TH>
1874 <TH WIDTH="20%">netmask</TH>
1875 <TH WIDTH="10%">mm</TH>
1876 <TH WIDTH="20%">netmask</TH>
1879 <TD ALIGN="CENTER">0</TD>
1880 <TD ALIGN="CENTER">0.0.0.0</TD>
1881 <TD ALIGN="CENTER">8</TD>
1882 <TD ALIGN="CENTER">255.0.0.0</TD>
1885 <TD ALIGN="CENTER">1</TD>
1886 <TD ALIGN="CENTER">128.0.0.0</TD>
1887 <TD ALIGN="CENTER">16</TD>
1888 <TD ALIGN="CENTER">255.255.0.0</TD>
1891 <TD ALIGN="CENTER">2</TD>
1892 <TD ALIGN="CENTER">192.0.0.0</TD>
1893 <TD ALIGN="CENTER">24</TD>
1894 <TD ALIGN="CENTER">255.255.255.0</TD>
1897 <TD ALIGN="CENTER">...</TD>
1898 <TD ALIGN="CENTER">...</TD>
1899 <TD ALIGN="CENTER">32</TD>
1900 <TD ALIGN="CENTER">255.255.255.255</TD>
1904 <P>The <CODE>@LOCAL</CODE> name will deny access from all local
1905 network interfaces, but not remote point-to-point interfaces. The
1906 <CODE>@IF(name)</CODE> name will deny access from the named
1909 <P>The <CODE>Deny</CODE> directive must appear inside a
1910 <A HREF="#Location"><CODE>Location</CODE></A> directive.
1913 <H3><A NAME="DocumentRoot">DocumentRoot</A></H3>
1919 DocumentRoot /usr/share/doc/cups
1920 DocumentRoot /foo/bar/doc/cups
1923 <H4>Description</H4>
1925 <P>The <CODE>DocumentRoot</CODE> directive specifies the location of
1926 web content for the HTTP server in CUPS. If an absolute path is not
1927 specified then it is assumed to be relative to the
1928 <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
1929 default directory is <VAR>/usr/share/doc/cups</VAR>.
1931 <P>Documents are first looked up in a sub-directory for the primary
1932 language requested by the client (e.g. <VAR>/usr/share/doc/cups/fr/...</VAR>)
1933 and then directly under the <CODE>DocumentRoot</CODE> directory
1934 (e.g. <VAR>/usr/share/doc/cups/...</VAR>), so it is possible to localize
1935 the web content by providing subdirectories for each language needed.
1938 <H3><A NAME="Encryption">Encryption</A></H3>
1945 Encryption IfRequested
1950 <H4>Description</H4>
1952 <P>The <CODE>Encryption</CODE> directive must appear instead a
1953 <A HREF="#Location"><CODE>Location</CODE></A>
1954 section and specifies the encryption settings for that location.
1955 The default setting is <CODE>IfRequested</CODE> for all locations.
1958 <H3><A NAME="ErrorLog">ErrorLog</A></H3>
1964 ErrorLog /var/log/cups/error_log
1965 ErrorLog /var/log/cups/error_log-%s
1969 <H4>Description</H4>
1971 <P>The <CODE>ErrorLog</CODE> directive sets the name of the error log
1972 file. If the filename is not absolute then it is assumed to be relative
1973 to the <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
1974 default error log file is <VAR>/var/log/cups/error_log</VAR>.
1976 <P>The server name can be included in the filename by using
1977 <CODE>%s</CODE> in the name.
1979 <P>The special name "syslog" can be used to send the error information
1980 to the system log instead of a plain file.
1983 <H3><A NAME="FilterLimit">FilterLimit</A></H3>
1994 <H4>Description</H4>
1996 <P>The <CODE>FilterLimit</CODE> directive sets the maximum cost
1997 of all running job filters. It can be used to limit the number
1998 of filter programs that are run on a server to minimize disk,
1999 memory, and CPU resource problems. A limit of 0 disables filter
2002 <P>An average print to a non-PostScript printer needs a filter
2003 limit of about 200. A PostScript printer needs about half that
2004 (100). Setting the limit below these thresholds will effectively
2005 limit the scheduler to printing a single job at any time.
2007 <P>The default limit is 0.
2010 <H3><A NAME="FilterNice">FilterNice</A></H3>
2021 <H4>Description</H4>
2023 <P>The <CODE>FilterNice</CODE> directive sets the scheduling
2024 priority of job filters. Values larger than 0 give filters a
2025 lower priority while values smaller than 0 give filters a higher
2026 priority. The <CODE>FilterNice</CODE> value does not affect the
2027 priority of job backends.
2029 <P>The default priority is 0.
2032 <H3><A NAME="FontPath">FontPath</A></H3>
2038 FontPath /foo/bar/fonts
2039 FontPath /usr/share/cups/fonts:/foo/bar/fonts
2042 <H4>Description</H4>
2044 <P>The <CODE>FontPath</CODE> directive specifies the font path to use when
2045 searching for fonts. The default font path is
2046 <CODE>/usr/share/cups/fonts</CODE>.
2049 <H3><A NAME="Group">Group</A></H3>
2060 <H4>Description</H4>
2062 <P>The <CODE>Group</CODE> directive specifies the UNIX group that
2063 filter and CGI programs run as. The default group is <CODE>sys</CODE>,
2064 <CODE>system</CODE>, or <CODE>root</CODE> depending on the operating
2068 <H3><A NAME="HideImplicitMembers">HideImplicitMembers</A></H3>
2074 HideImplicitMembers Yes
2075 HideImplicitMembers No
2078 <H4>Description</H4>
2080 <P>The <CODE>HideImplicitMembers</CODE> directive controls
2081 whether the individual printers in an implicit class are shown
2082 to the user. The default is <CODE>No</CODE>.</P>
2084 <P><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
2085 must be enabled for this directive to have any effect.</P>
2088 <H3><A NAME="HostNameLookups">HostNameLookups</A></H3>
2096 HostNameLookups Double
2099 <H4>Description</H4>
2101 <P>The <CODE>HostNameLookups</CODE> directive controls whether
2102 or not CUPS looks up the hostname for connecting clients. The
2103 <CODE>Double</CODE> setting causes CUPS to verify that the
2104 hostname resolved from the address matches one of the addresses
2105 returned for that hostname. <CODE>Double</CODE> lookups also
2106 prevent clients with unregistered addresses from connecting
2109 The default is <CODE>Off</CODE> to avoid the potential server
2110 performance problems with hostname lookups. Set this option to
2111 <CODE>On</CODE> or <CODE>Double</CODE> only if absolutely
2115 <H3><A NAME="ImplicitClasses">ImplicitClasses</A></H3>
2125 <H4>Description</H4>
2127 <P>The <CODE>ImplicitClasses</CODE> directive controls whether implicit
2128 classes are created based upon the available network printers and classes.
2129 The default setting is <CODE>On</CODE> but is automatically turned
2130 <CODE>Off</CODE> if <A HREF="#Browsing"><CODE>Browsing</CODE></A> is
2131 turned <CODE>Off</CODE>.
2134 <H3><A NAME="ImplicitAnyClasses">ImplicitAnyClasses</A></H3>
2140 ImplicitAnyClasses On
2141 ImplicitAnyClasses Off
2144 <H4>Description</H4>
2146 <P>The <CODE>ImplicitAnyClasses</CODE> directive controls
2147 whether implicit classes for local and remote printers are
2148 created with the name <CODE>AnyPrinter</CODE>. The default
2149 setting is <CODE>Off</CODE>.</P>
2151 <P><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
2152 must be enabled for this directive to have any effect.</P>
2155 <H3><A NAME="Include">Include</A></H3>
2162 Include /foo/bar/filename
2165 <H4>Description</H4>
2167 <P>The <CODE>Include</CODE> directive includes the named file in
2168 the <CODE>cupsd.conf</CODE> file. If no leading path is
2169 provided, the file is assumed to be relative to the
2170 <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory.</P>
2173 <H3><A NAME="KeepAlive">KeepAlive</A></H3>
2183 <H4>Description</H4>
2185 <P>The <CODE>KeepAlive</CODE> directive controls whether or not to support
2186 persistent HTTP connections. The default is <CODE>On</CODE>.
2188 <P>HTTP/1.1 clients automatically support persistent connections, while
2189 HTTP/1.0 clients must specifically request them using the
2190 <CODE>Keep-Alive</CODE> attribute in the <CODE>Connection:</CODE>
2191 field of each request.
2194 <H3><A NAME="KeepAliveTimeout">KeepAliveTimeout</A></H3>
2204 <H4>Description</H4>
2206 <P>The <CODE>KeepAliveTimeout</CODE> directive controls how long a
2207 persistent HTTP connection will remain open after the last request. The
2208 default is 60 seconds.
2211 <H3><A NAME="Limit">Limit</A></H3>
2217 <Limit GET POST>
2226 <H4>Description</H4>
2228 <P>The <CODE>Limit</CODE> directive groups access control directives for
2229 specific types of HTTP requests and must appear inside a
2230 <A HREF="#Location"><CODE>Location</CODE></A> section. Access can be limited
2231 for individual request types (<CODE>DELETE</CODE>, <CODE>GET</CODE>,
2232 <CODE>HEAD</CODE>, <CODE>OPTIONS</CODE>, <CODE>POST</CODE>, <CODE>PUT</CODE>,
2233 and <CODE>TRACE</CODE>) or for all request types (<CODE>ALL</CODE>). The
2234 request type names are case-sensitive for compatibility with Apache.
2237 <H3><A NAME="LimitExcept">LimitExcept</A></H3>
2243 <LimitExcept GET POST>
2245 </LimitExcept>
2248 <H4>Description</H4>
2250 <P>The <CODE>LimitExcept</CODE> directive groups access control directives for
2251 specific types of HTTP requests and must appear inside a
2252 <A HREF="#Location"><CODE>Location</CODE></A> section. Unlike the
2253 <A HREF="#Limit"><CODE>Limit</CODE></A> directive, <CODE>LimitExcept</CODE>
2254 restricts access for all requests <I>except</I> those listed on the
2255 <CODE>LimitExcept</CODE> line.
2258 <H3><A NAME="LimitRequestBody">LimitRequestBody</A></H3>
2264 LimitRequestBody 10485760
2265 LimitRequestBody 10m
2269 <H4>Description</H4>
2271 <P>The <CODE>LimitRequestBody</CODE> directive controls the maximum size of
2272 print files, IPP requests, and HTML form data in HTTP POST requests. The
2273 default limit is 0 which disables the limit check.
2275 <P>Also see the identical
2276 <A HREF="#MaxRequestSize"><CODE>MaxRequestSize</CODE></A> directive.
2279 <H3><A NAME="Listen">Listen</A></H3>
2285 Listen 127.0.0.1:631
2286 Listen 192.0.2.1:631
2289 <H4>Description</H4>
2291 <P>The <CODE>Listen</CODE> directive specifies a network address and port
2292 to listen for connections. Multiple <CODE>Listen</CODE> directives can be
2293 provided to listen on multiple addresses.
2295 <P>The <CODE>Listen</CODE> directive is similar to the
2296 <A HREF="#Port"><CODE>Port</CODE></A> directive but allows you to restrict
2297 access to specific interfaces or networks.
2300 <H3><A NAME="Location">Location</A></H3>
2310 <Location /admin>
2314 <Location /printers>
2318 <Location /printers/name>
2322 <Location /classes>
2326 <Location /classes/name>
2331 <H4>Description</H4>
2333 <P>The <CODE>Location</CODE> directive specifies access control and
2334 authentication options for the specified HTTP resource or path.
2336 <A HREF="#Allow"><CODE>Allow</CODE></A>,
2337 <A HREF="#AuthClass"><CODE>AuthClass</CODE></A>,
2338 <A HREF="#AuthGroupName"><CODE>AuthGroupName</CODE></A>,
2339 <A HREF="#AuthType"><CODE>AuthType</CODE></A>,
2340 <A HREF="#Deny"><CODE>Deny</CODE></A>,
2341 <A HREF="#Encryption"><CODE>Encryption</CODE></A>,
2342 <A HREF="#Limit"><CODE>Limit</CODE></A>,
2343 <A HREF="#LimitExcept"><CODE>LimitExcept</CODE></A>,
2344 <A HREF="#Order"><CODE>Order</CODE></A>,
2345 <A HREF="#Require"><CODE>Require</CODE></A>, and
2346 <A HREF="#Satisfy"><CODE>Satisfy</CODE></A>
2347 directives may all appear inside a location.
2349 <CENTER><TABLE BORDER="1"><CAPTION>Locations on the Server.</CAPTION>
2350 <TR><TH>Location</TH><TH>Description</TH></TR>
2351 <TR><TD>/</TD><TD>The path for all get operations (get-printers, get-jobs, etc.)</TD></TR>
2352 <TR><TD>/admin</TD><TD>The path for all administration operations (add-printer, delete-printer, start-printer, etc.)</TD></TR>
2353 <TR><TD>/admin/conf</TD><TD>The path for access to the ESP Print Pro configuration files (cupsd.conf, client.conf, etc.)</TD></TR>
2354 <TR><TD>/classes</TD><TD>The path for all classes</TD></TR>
2355 <TR><TD>/classes/name</TD><TD>The resource for class <CODE>name</CODE></TD></TR>
2356 <TR><TD>/jobs</TD><TD>The path for all jobs (hold-job, release-job, etc.)</TD></TR>
2357 <TR><TD>/jobs/id</TD><TD>The resource for job <CODE>id</CODE></TD></TR>
2358 <TR><TD>/printers</TD><TD>The path for all printers</TD></TR>
2359 <TR><TD>/printers/name</TD><TD>The path for printer <CODE>name</CODE></TD></TR>
2360 <TR><TD>/printers/name.ppd</TD><TD>The PPD file path for printer <CODE>name</CODE></TD></TR>
2363 <P>Note that more specific resources override the less specific ones.
2364 So the directives inside the <CODE>/printers/name</CODE> location will override ones from <CODE>/printers</CODE>.
2365 Directives inside <CODE>/printers</CODE> will override ones from <CODE>/</CODE>.
2366 None of the directives are inherited.
2367 More information can be found in section <A HREF="#PRINTING_SECURITY">"Printing System Security"</A>.
2370 <H3><A NAME="LogFilePerm">LogFilePerm</A></H3>
2380 <H4>Description</H4>
2382 <P>The <CODE>LogFilePerm</CODE> directive specifies the permissions
2383 to use when writing configuration files. The default is 0644.
2386 <H3><A NAME="LogLevel">LogLevel</A></H3>
2404 <H4>Description</H4>
2406 <P>The <CODE>LogLevel</CODE> directive specifies the level of logging
2407 for the <A HREF="#ErrorLog"><CODE>ErrorLog</CODE></A> file. The
2408 following values are recognized (each level logs everything under the
2413 <LI><CODE>none</CODE> - Log nothing.
2415 <LI><CODE>emerg</CODE> - Log emergency conditions that prevent the
2416 server from running.
2418 <LI><CODE>alert</CODE> - Log alerts that must be handled immediately.
2420 <LI><CODE>crit</CODE> - Log critical errors that don't prevent
2421 the server from running.
2423 <LI><CODE>error</CODE> - Log general errors.
2425 <LI><CODE>warn</CODE> - Log errors and warnings.
2427 <LI><CODE>notice</CODE> - Log temporary error conditions.
2429 <LI><CODE>info</CODE> - Log all requests and state changes (default).
2431 <LI><CODE>debug</CODE> - Log basic debugging information.
2433 <LI><CODE>debug2</CODE> - Log all debugging information.
2438 <H3><A NAME="MaxClients">MaxClients</A></H3>
2448 <H4>Description</H4>
2450 <P>The <CODE>MaxClients</CODE> directive controls the maximum number of
2451 simultaneous clients that will be allowed by the server. The default is
2454 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
2459 <P>Since each print job requires a file descriptor for the
2460 status pipe, the CUPS server internally limits the
2461 <CODE>MaxClients</CODE> value to 1/3 of the available file descriptors
2462 to avoid possible problems when printing large numbers of jobs.
2468 <H3><A NAME="MaxCopies">MaxCopies</A></H3>
2478 <H4>Description</H4>
2480 <P>The <CODE>MaxCopies</CODE> directive controls the maximum
2481 number of copies that a user can print of a job. The default is
2484 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
2489 <P>Most HP PCL laser printers internally limit the
2490 number of copies to 100.
2497 <H3><A NAME="MaxJobs">MaxJobs</A></H3>
2508 <H4>Description</H4>
2510 <P>The <CODE>MaxJobs</CODE> directive controls the maximum number of jobs
2511 that are kept in memory. Once the number of jobs reaches the limit, the
2512 oldest completed job is automatically purged from the system to make room
2513 for the new one. If all of the known jobs are still pending or active then
2514 the new job will be rejected.
2516 <P>Setting the maximum to 0 disables this functionality. The default
2520 <H3><A NAME="MaxJobsPerPrinter">MaxJobsPerPrinter</A></H3>
2526 MaxJobsPerPrinter 100
2527 MaxJobsPerPrinter 9999
2531 <H4>Description</H4>
2533 <P>The <CODE>MaxJobsPerPrinter</CODE> directive controls the maximum number of active jobs
2534 that are allowed for each printer or class. Once a printer or class reaches the limit, new jobs will be
2535 rejected until one of the active jobs is completed, stopped, aborted, or cancelled.
2537 <P>Setting the maximum to 0 disables this functionality. The default
2541 <H3><A NAME="MaxJobsPerUser">MaxJobsPerUser</A></H3>
2552 <H4>Description</H4>
2554 <P>The <CODE>MaxJobsPerUser</CODE> directive controls the maximum number of active jobs
2555 that are allowed for each user. Once a user reaches the limit, new jobs will be
2556 rejected until one of the active jobs is completed, stopped, aborted, or cancelled.
2558 <P>Setting the maximum to 0 disables this functionality. The default
2562 <H3><A NAME="MaxLogSize">MaxLogSize</A></H3>
2573 <H4>Description</H4>
2575 <P>The <CODE>MaxLogSize</CODE> directive controls the maximum size of each
2576 log file. Once a log file reaches or exceeds the maximum size it is closed
2577 and renamed to <VAR>filename.O</VAR>. This allows you to rotate the logs
2578 automatically. The default size is 1048576 bytes (1MB).
2580 <P>Setting the maximum size to 0 disables log rotation.
2583 <H3><A NAME="MaxRequestSize">MaxRequestSize</A></H3>
2589 MaxRequestSize 10485760
2594 <H4>Description</H4>
2596 <P>The <CODE>MaxRequestSize</CODE> directive controls the maximum size of
2597 print files, IPP requests, and HTML form data in HTTP POST requests. The
2598 default limit is 0 which disables the limit check.
2600 <P>Also see the identical
2601 <A HREF="#LimitRequestBody"><CODE>LimitRequestBody</CODE></A> directive.
2604 <H3><A NAME="Order">Order</A></H3>
2614 <H4>Description</H4>
2616 <P>The <CODE>Order</CODE> directive defines the default access control.
2617 The following values are supported:
2621 <LI><CODE>Allow,Deny</CODE> - Allow requests from all
2622 systems <I>except</I> for those listed in a <CODE>Deny</CODE>
2625 <LI><CODE>Deny,Allow</CODE> - Allow requests only from
2626 those listed in an <CODE>Allow</CODE> directive.
2630 <P>The <CODE>Order</CODE> directive must appear inside a
2631 <A HREF="#Location"><CODE>Location</CODE></A> directive.
2634 <H3><A NAME="PageLog">PageLog</A></H3>
2640 PageLog /var/log/cups/page_log
2641 PageLog /var/log/cups/page_log-%s
2645 <H4>Description</H4>
2647 <P>The <CODE>PageLog</CODE> directive sets the name of the page log
2648 file. If the filename is not absolute then it is assumed to be relative
2649 to the <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
2650 default page log file is <VAR>/var/log/cups/page_log</VAR>.
2652 <P>The server name can be included in the filename by using
2653 <CODE>%s</CODE> in the name.
2655 <P>The special name "syslog" can be used to send the page information
2656 to the system log instead of a plain file.
2659 <H3><A NAME="Port">Port</A></H3>
2669 <H4>Description</H4>
2671 <P>The <CODE>Port</CODE> directive specifies a port to listen on.
2672 Multiple <CODE>Port</CODE> lines can be specified to listen on multiple
2673 ports. The default port is 631.
2676 <H3><A NAME="PreserveJobHistory">PreserveJobHistory</A></H3>
2682 PreserveJobHistory On
2683 PreserveJobHistory Off
2686 <H4>Description</H4>
2688 <P>The <CODE>PreserveJobHistory</CODE> directive controls whether
2689 the history of completed, cancelled, or aborted print jobs is stored
2692 <P>A value of <CODE>On</CODE> (the default) preserves job information
2693 until the administrator purges it with the <CODE>cancel</CODE>
2696 <P>A value of <CODE>Off</CODE> removes the job information as soon as
2697 each job is completed, cancelled, or aborted.
2700 <H3><A NAME="PreserveJobFiles">PreserveJobFiles</A></H3>
2707 PreserveJobFiles Off
2710 <H4>Description</H4>
2712 <P>The <CODE>PreserveJobFiles</CODE> directive controls whether the
2713 document files of completed, cancelled, or aborted print jobs are
2716 <P>A value of <CODE>On</CODE> preserves job files until the
2717 administrator purges them with the <CODE>cancel</CODE> command. Jobs
2718 can be restarted (and reprinted) as desired until they are purged.
2720 <P>A value of <CODE>Off</CODE> (the default) removes the job files as
2721 soon as each job is completed, cancelled, or aborted.
2724 <H3><A NAME="Printcap">Printcap</A></H3>
2731 Printcap /etc/printcap
2732 Printcap /etc/printers.conf
2735 <H4>Description</H4>
2737 <P>The <CODE>Printcap</CODE> directive controls whether or not a
2738 printcap file is automatically generated and updated with a list
2739 of available printers. If specified with no value, then no
2740 printcap file will be generated. The default is to generate a
2741 file named <VAR>/etc/printcap</VAR>.
2743 <P>When a filename is specified (e.g. <VAR>/etc/printcap</VAR>), the
2744 printcap file is written whenever a printer is added or removed. The
2745 printcap file can then be used by applications that are hardcoded to
2746 look at the printcap file for the available printers.
2749 <H3><A NAME="PrintcapFormat">PrintcapFormat</A></H3>
2756 PrintcapFormat Solaris
2759 <H4>Description</H4>
2761 <P>The <CODE>PrintcapFormat</CODE> directive controls the output
2762 format of the printcap file. The default is to generate a BSD
2766 <H3><A NAME="PrintcapGUI">PrintcapGUI</A></H3>
2772 PrintcapGUI /usr/bin/glpoptions
2775 <H4>Description</H4>
2777 <P>The <CODE>PrintcapGUI</CODE> directive sets the program to
2778 use when displaying an option panel from an IRIX application
2779 that uses the Impressario print API. The default program is the
2780 ESP Print Pro "glpoptions" GUI.
2782 <P>The program must accept the <CODE>-d</CODE> option to specify
2783 a printer and the <CODE>-o</CODE> option to specify one or more
2784 options. After allowing the user to select/change options, the
2785 program must then write the list of printing options without the
2786 <CODE>-o</CODE> to the standard output.
2789 <H3><A NAME="RemoteRoot">RemoteRoot</A></H3>
2799 <H4>Description</H4>
2801 <P>The <CODE>RemoteRoot</CODE> directive sets the username for
2802 unauthenticated root requests from remote hosts. The default
2803 username is <VAR>remroot</VAR>. Setting <CODE>RemoteRoot</CODE>
2804 to <VAR>root</VAR> effectively disables this security mechanism.
2807 <H3><A NAME="RequestRoot">RequestRoot</A></H3>
2813 RequestRoot /var/spool/cups
2814 RequestRoot /foo/bar/spool/cups
2817 <H4>Description</H4>
2819 <P>The <CODE>RequestRoot</CODE> directive sets the directory for
2820 incoming IPP requests and HTML forms. If an absolute path is not
2821 provided then it is assumed to be relative to the
2822 <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
2823 default request directory is <VAR>/var/spool/cups</VAR>.
2826 <H3><A NAME="Require">Require</A></H3>
2832 Require group foo bar
2833 Require user john mary
2837 <H4>Description</H4>
2839 <P>The <CODE>Require</CODE> directive specifies that
2840 authentication is required for the resource. The
2841 <CODE>group</CODE> keyword specifies that the authenticated user
2842 must be a member of one or more of the named groups that follow.
2844 <P>The <CODE>user</CODE> keyboard specifies that the
2845 authenticated user must be one of the named users that follow.
2847 <P>The <CODE>valid-user</CODE> keyword specifies that any
2848 authenticated user may access the resource.
2850 <P>The default is to do no authentication. This directive must
2851 appear inside a <A HREF="#Location"><CODE>Location</CODE></A>
2855 <H3><A NAME="RIPCache">RIPCache</A></H3>
2866 <H4>Description</H4>
2868 <P>The <CODE>RIPCache</CODE> directive sets the size of the memory
2869 cache used by Raster Image Processor ("RIP") filters such as
2870 <CODE>imagetoraster</CODE> and <CODE>pstoraster</CODE>. The size can
2871 be suffixed with a "k" for kilobytes, "m" for megabytes, or
2872 "g" for gigabytes. The default cache size is "8m", or 8 megabytes.
2875 <H3><A NAME="RootCertDuration">RootCertDuration</A></H3>
2881 RootCertDuration 300
2885 <H4>Description</H4>
2887 <P>The <CODE>RootCertDuration</CODE> directive controls the
2888 interval between updates of the root authentication certificate.
2889 The default is <CODE>300</CODE> seconds which updates the root
2890 certificate approximately once every 5 minutes. Set the interval
2891 to 0 to disable certificate updates entirely.
2895 <H3><A NAME="RunAsUser">RunAsUser</A></H3>
2905 <H4>Description</H4>
2907 <P>The <CODE>RunAsUser</CODE> directive controls whether the
2908 scheduler runs as the unpriviledged user account (usually <CODE>lp</CODE>).
2909 The default is <CODE>No</CODE> which leaves the scheduler running as
2910 the <CODE>root</CODE> user.
2912 <P><B>Note:</B> Running as a non-priviledged user may prevent
2913 LPD and locally connected printers from working due to
2914 permission problems. The <CODE>lpd</CODE> backend will
2915 automatically use a non-priviledged mode that is not 100%
2916 compliant with RFC 1179. The <CODE>parallel</CODE>,
2917 <CODE>serial</CODE>, and <CODE>usb</CODE> backends will need
2918 write access to the corresponding device files.
2921 <H3><A NAME="Satisfy">Satisfy</A></H3>
2931 <H4>Description</H4>
2933 <P>The <CODE>Satisfy</CODE> directive specifies whether all
2934 conditions must be satisfied to allow access to the resource. If
2935 set to <CODE>all</CODE>, then all authentication and access
2936 control conditions must be satified to allow access.
2938 <P>Setting <CODE>Satisfy</CODE> to <CODE>any</CODE> allows a user to
2939 gain access if the authentication or access control requirements are
2940 satisfied. For example, you might require authentication for remote
2941 access, but allow local access without authentication.
2943 <P>The default is <CODE>all</CODE>. This directive must appear
2944 inside a <A HREF="#Location"><CODE>Location</CODE></A>
2948 <H3><A NAME="ServerAdmin">ServerAdmin</A></H3>
2954 ServerAdmin user@host
2955 ServerAdmin root@foo.bar.com
2958 <H4>Description</H4>
2960 <P>The <CODE>ServerAdmin</CODE> directive identifies the email address for the
2961 administrator on the system. By default the administrator email address is
2962 <CODE>root@server</CODE>, where <CODE>server</CODE> is the server name.
2965 <H3><A NAME="ServerBin">ServerBin</A></H3>
2971 ServerBin /usr/lib/cups
2972 ServerBin /foo/bar/lib/cups
2975 <H4>Description</H4>
2977 <P>The <CODE>ServerBin</CODE> directive sets the directory for
2978 server-run executables. If an absolute path is not provided then it is
2979 assumed to be relative to the
2980 <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
2981 default executable directory is <VAR>/usr/lib/cups</VAR>.
2984 <H3><A NAME="ServerCertificate">ServerCertificate</A></H3>
2990 ServerCertificate /etc/cups/ssl/server.crt
2993 <H4>Description</H4>
2995 <P>The <CODE>ServerCertificate</CODE> directive specifies the
2996 location of the SSL certificate file used by the server when
2997 negotiating encrypted connections. The certificate must not be
2998 encrypted (password protected) since the scheduler normally runs
2999 in the background and will be unable to ask for a password.
3000 The default certificate file is <VAR>/etc/cups/ssl/server.crt</VAR>.
3003 <H3><A NAME="ServerKey">ServerKey</A></H3>
3009 ServerKey /etc/cups/ssl/server.key
3012 <H4>Description</H4>
3014 <P>The <CODE>ServerKey</CODE> directive specifies the location
3015 of the SSL private key file used by the server when negotiating
3016 encrypted connections. The default key file is
3017 <VAR>/etc/cups/ssl/server.crt</VAR>.
3020 <H3><A NAME="ServerName"></A>ServerName</H3>
3026 ServerName foo.domain.com
3027 ServerName myserver.domain.com
3030 <H4>Description</H4>
3032 <P>The <CODE>ServerName</CODE> directive specifies the hostname that is
3033 reported to clients. By default the server name is the hostname.
3036 <H3><A NAME="ServerRoot">ServerRoot</A></H3>
3042 ServerRoot /etc/cups
3043 ServerRoot /foo/bar/cups
3046 <H4>Description</H4>
3048 <P>The <CODE>ServerRoot</CODE> directive specifies the absolute path to
3049 the server configuration and state files. It is also used to resolve
3050 relative paths in the <VAR>cupsd.conf</VAR> file. The default server
3051 directory is <VAR>/etc/cups</VAR>.
3054 <H3><A NAME="ServerTokens">ServerTokens</A></H3>
3061 ServerTokens ProductOnly
3064 ServerTokens Minimal
3069 <H4>Description</H4>
3071 <P>The <CODE>ServerTokens</CODE> directive specifies the information
3072 that is included in the Server header of HTTP responses. The default value
3073 is <tt>Minor</tt> which generates "CUPS/1.1".
3076 <H3><A NAME="SSLListen">SSLListen</A></H3>
3082 SSLListen 127.0.0.1:443
3083 SSLListen 192.0.2.1:443
3086 <H4>Description</H4>
3088 <P>The <CODE>SSLListen</CODE> directive specifies a network
3089 address and port to listen for secure connections. Multiple
3090 <CODE>SSLListen</CODE> directives can be provided to listen on
3093 <P>The <CODE>SSLListen</CODE> directive is similar to the
3094 <A HREF="#SSLPort"><CODE>SSLPort</CODE></A> directive but allows
3095 you to restrict access to specific interfaces or networks.
3098 <H3><A NAME="SSLPort">SSLPort</A></H3>
3107 <H4>Description</H4>
3109 <P>The <CODE>SSLPort</CODE> directive specifies a port to listen
3110 on for secure connections. Multiple <CODE>SSLPort</CODE> lines
3111 can be specified to listen on multiple ports.
3114 <H3><A NAME="SystemGroup">SystemGroup</A></H3>
3125 <H4>Description</H4>
3127 <P>The <CODE>SystemGroup</CODE> directive specifies the system
3128 administration group for <CODE>System</CODE> authentication. More
3129 information can be found later in this chapter in
3130 <A HREF="#PRINTING_SECURITY">"Printing System Security"</A>.
3133 <H3><A NAME="TempDir">TempDir</A></H3>
3140 TempDir /foo/bar/tmp
3143 <H4>Description</H4>
3145 <P>The <CODE>TempDir</CODE> directive specifies an absolute path for
3146 the directory to use for temporary files. The default directory is
3147 <VAR>/var/tmp</VAR>.
3149 <P>Temporary directories must be world-writable and should have the
3150 "sticky" permission bit enabled so that other users cannot delete
3151 filter temporary files. The following commands will create an
3152 appropriate temporary directory called <VAR>/foo/bar/tmp</VAR>:
3155 <B>mkdir /foo/bar/tmp ENTER</B>
3156 <B>chmod a+rwxt /foo/bar/tmp ENTER</B>
3160 <H3><A NAME="Timeout">Timeout</A></H3>
3170 <H4>Description</H4>
3172 <P>The <CODE>Timeout</CODE> directive controls the amount of time to
3173 wait before an active HTTP or IPP request times out. The default
3174 timeout is 300 seconds.
3177 <H3><A NAME="User">User</A></H3>
3187 <H4>Description</H4>
3189 <P>The <CODE>User</CODE> directive specifies the UNIX user that
3190 filter and CGI programs run as. The default user is <CODE>lp</CODE>.
3193 <H2><A NAME="PRINTING_SECURITY">Printing System Security</A></H2>
3195 <P>CUPS provides support for address, certificate, and password (Basic
3196 and Digest) based authentication and access control. Certificate and
3197 password authentication provide ways to limit access to individual
3200 <P>Address based access control allows you to limit access to specific
3201 systems, networks, or domains. While this does not provide authentication,
3202 it does allow you to limit the potential users of your system efficiently.
3204 <P>CUPS maintains a list of locations that have access control and/or
3205 authentication enabled. Locations are specified using the
3206 <A HREF="#Location"><CODE>Location</CODE></A> directive:
3209 <Location /resource>
3210 <A HREF="#AuthClass">AuthClass</A> ...
3211 <A HREF="#AuthGroupName">AuthGroupName</A> ...
3212 <A HREF="#AuthType">AuthType</A> ...
3214 <A HREF="#Order">Order</A> ...
3215 <A HREF="#Allow">Allow</A> from ...
3216 <A HREF="#Deny">Deny</A> from ...
3220 <P>Locations generally follow the directory structure of the
3221 <A HREF="#DocumentRoot"><CODE>DocumentRoot</CODE></A> directory, however
3222 CUPS does have several virtual locations for administration, classes, jobs,
3225 <CENTER><TABLE BORDER="1">
3228 <TH>Description</TH>
3232 <TD>The path for all administration operations.</TD>
3236 <TD>The path for all classes.</TD>
3239 <TD>/classes/name</TD>
3240 <TD>The resource for class <CODE>name</CODE>.</TD>
3244 <TD>The path for all jobs.</TD>
3248 <TD>The resource for job <CODE>id</CODE>.</TD>
3252 <TD>The path for all printers.</TD>
3255 <TD>/printers/name</TD>
3256 <TD>The path for printer <CODE>name</CODE>.</TD>
3259 <TD>/printers/name.ppd</TD>
3260 <TD>The PPD file path for printer <CODE>name</CODE>.</TD>
3264 <H3><A NAME="CERTIFICATES">Authentication Using Certificates</A></H3>
3266 <P>CUPS supports a local certificate-based authentication scheme that
3267 can be used in place of <CODE>Basic</CODE> or <CODE>Digest</CODE>
3268 authentication by clients connecting through the <CODE>localhost</CODE>
3269 interface. Certificate authentication is not supported or allowed from
3270 clients on any other interface.
3272 <P>Certificates are 128-bit random numbers that refer to an internal
3273 authentication record in the server. A client connecting via the
3274 <CODE>localhost</CODE> interface sends a request with an
3275 authorization header of:
3278 Authorization: Local 0123456789ABCDEF0123456789ABCDEF
3281 <P>The server then looks up the local certificate and authenticates
3282 using the username associated with it.
3284 <P>Certificates are generated by the server automatically and stored in
3285 the <VAR>/etc/cups/certs</VAR> directory using the process ID of the
3286 CGI program started by the server. Certificate files are only readable
3287 by the <A HREF="#User"><CODE>User</CODE></A> and
3288 <A HREF="#Group"><CODE>Group</CODE></A> defined in the
3289 <VAR>cupsd.conf</VAR> file. When the CGI program ends the certificate
3290 is removed and invalidated automatically.
3292 <P>The special file <VAR>/etc/cups/certs/0</VAR> defines the <I>root
3293 certificate</I> which can be used by any client running as the super-user
3294 or another user that is part of the group defined by the
3295 <A HREF="#SystemGroup"><CODE>SystemGroup</CODE></A> directive. The
3296 root certificate is automatically regenerated every 5 minutes.
3298 <H3>Using Basic Authentication</H3>
3300 <P>Basic authentication uses UNIX users and passwords to authenticate
3301 access to resources such as printers and classes, and to limit access
3302 to administrative functions.</P>
3304 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
3309 <P>Basic authentication sends the username and password Base64
3310 encoded from the client to the server, so it offers no
3311 protection against eavesdropping. This means that a malicious
3312 user can monitor network packets and discover valid users and
3313 passwords that could result in a serious compromise in network
3314 security. Use Basic authentication with extreme care.
3319 <P>The CUPS implementation of Basic authentication does not allow access
3320 through user accounts without a password. If you try to authenticate
3321 using an account without a password, your access will be immediately
3324 <P>Once a valid username and password is authenticated by CUPS, any
3325 additional group membership requirements are checked.</P>
3327 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
3332 <P>The root user is considered by CUPS to be a member of every
3339 <P>Use the <CODE>AuthType</CODE> directive to enable Basic authentication:
3346 <H3>Using Digest Authentication</H3>
3348 <P>Digest authentication uses users and passwords defined in the
3349 <VAR>/etc/cups/passwd.md5</VAR> file to authenticate access to
3350 resources such as printers and classes, and to limit access to
3351 administrative functions.</P>
3353 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
3358 <P>Unlike Basic authentication, Digest passes the MD5 sum
3359 (basically a complicated checksum) of the username and password
3360 instead of the strings themselves. Also, Digest authentication
3361 does not use the UNIX password file, so if an attacker does
3362 discover the original password it is less likely to result in a
3363 serious security problem so long as you use a different UNIX
3364 password than the corresponding Digest password.
3366 <P>The current CUPS implementation of Digest authentication
3367 uses the client's hostname or IP address for the "nonce" value.
3368 The nonce value is an additional string added to the username
3369 and password to make guessing the password more difficult. The
3370 server checks that the nonce value matches the client's hostname
3371 or address and rejects the MD5 sum if it doesn't. Future versions
3372 of CUPS will support Digest "session" authentication which adds
3373 the request data to the MD5 sum, providing even better
3374 authentication and security.
3376 <P>Digest authentication does not guarantee that an attacker
3377 cannot gain unauthorized access, but it is safer than Basic
3378 authentication and should be used in place of Basic
3379 authentication whenever possible. <B>Support for Digest
3380 authentication in web browsers is not yet universally
3387 <P>The <CODE>lppasswd(1)</CODE> command is used to add, change, or
3388 remove accounts from the <VAR>passwd.md5</VAR> file. To add a
3389 user to the default system group, type:
3392 <B>lppasswd -a user ENTER</B>
3393 Password: <B>(password) ENTER</B> [password is not echoed]
3394 Password again: <B>(password) ENTER</B> [password is not echoed]
3398 <P>Once added, a user can change his/her password by typing:
3401 <B>lppasswd ENTER</B>
3402 Old password: <B>(password) ENTER</B> [password is not echoed]
3403 Password: <B>(password) ENTER</B> [password is not echoed]
3404 Password again: <B>(password) ENTER</B> [password is not echoed]
3408 <P>To remove a user from the password file, type:
3411 <B>lppasswd -x user ENTER</B>
3414 <P>Once a valid username and password is authenticated by CUPS, any
3415 additional group membership requirements are checked.</P>
3417 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
3422 <P>The root user is considered by CUPS to be a member of every
3428 <P>Use the <CODE>AuthType</CODE> directive to enable Digest authentication:
3434 <H3>System and Group Authentication</H3>
3436 <P>The <A HREF="#AuthClass"><CODE>AuthClass</CODE></A> directive controls
3437 the level of authentication to perform. <CODE>System</CODE> and
3438 <CODE>Group</CODE> authentication extend the normal user-based authentication
3439 to require membership in a UNIX group. For <CODE>System</CODE> authentication
3440 each user must belong to the <CODE>sys</CODE>, <CODE>system</CODE>, or
3441 <CODE>root</CODE> group; the actual group depends on the operating system.
3443 <P>For <CODE>Group</CODE> authentication each user must belong to the
3444 group named by the <A HREF="#AuthGroupName"><CODE>AuthGroupName</CODE></A>
3448 <Location /path>
3451 AuthGroupName mygroup
3455 <P>The named group must be a valid UNIX user group, usually defined in the
3456 <VAR>/etc/group</VAR> or <VAR>/etc/netgroup</VAR> files. Additionally, when
3457 using Digest authentication you need to create user accounts with the named
3461 <B>lppasswd -g mygroup -a user ENTER</B>
3462 Password: <B>(password) ENTER</B> [password is not echoed]
3463 Password again: <B>(password) ENTER</B> [password is not echoed]
3467 <H2><A NAME="PRINTER_ACCOUNTING">Printer Accounting</A></H2>
3469 <P>CUPS maintains a log of all accesses, errors, and
3470 pages that are printed. The log files are normally stored in the
3471 <VAR>/var/log/cups</VAR> directory. You can change this by
3472 editing the <VAR>/etc/cups/cupsd.conf</VAR> configuration file.
3474 <H3>The access_log File</H3>
3476 <P>The <VAR>access_log</VAR> file lists each HTTP resource that is accessed
3477 by a web browser or CUPS/IPP client. Each line is in the so-called "Common
3478 Log Format" used by many web servers and web reporting tools:
3481 host group user date-time \"method resource version\" status bytes
3483 127.0.0.1 - - [20/May/1999:19:20:29 +0000] "POST /admin/ HTTP/1.1" 401 0
3484 127.0.0.1 - mike [20/May/1999:19:20:31 +0000] "POST /admin/ HTTP/1.1" 200 0
3487 <P>The <I>host</I> field will normally only be an IP address unless you
3488 have enabled the <A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A>
3489 directive in the <VAR>cupsd.conf</VAR> file.
3491 <P>The <I>group</I> field always contains "-" in CUPS.
3493 <P>The <I>user</I> field is the authenticated username of the requesting user.
3494 If no username and password is supplied for the request then this field
3497 <P>The <I>date-time</I> field is the date and time of the request in local time
3498 and is in the format:
3501 [DD/MON/YYYY:HH:MM:SS +ZZZZ]
3504 <P>where <I>ZZZZ</I> is the timezone offset in hours and minutes from Greenwich
3505 Mean Time (a.k.a. GMT a.k.a. ZULU.)
3507 <P>The <I>method</I> field is the HTTP method used ("GET", "PUT", "POST", etc.)
3509 <P>The <I>resource</I> field is the filename of the requested resource.
3511 <P>The <I>version</I> field is the HTTP specification version used by the
3512 client. For CUPS clients this will always be "HTTP/1.1".
3514 <P>The <I>status</I> field contains the HTTP result status of the
3515 request. Usually it is "200", but other HTTP status codes are possible.
3516 For example, 401 is the "unauthorized access" status in the example
3519 <P>The <I>bytes</I> field contains the number of bytes in the request.
3520 For POST requests the <I>bytes</I> field contains the number of bytes
3521 that was received from the client.
3523 <H3>The error_log File</H3>
3525 <P>The <VAR>error_log</VAR> file lists messages from the scheduler (errors,
3529 level date-time message
3531 I [20/May/1999:19:18:28 +0000] Job 1 queued on 'DeskJet' by 'mike'.
3532 I [20/May/1999:19:21:02 +0000] Job 2 queued on 'DeskJet' by 'mike'.
3533 I [20/May/1999:19:22:24 +0000] Job 2 was cancelled by 'mike'.
3536 <P>The <I>level</I> field contains the type of message:
3540 <LI><CODE>E</CODE> - An error occurred.
3542 <LI><CODE>W</CODE> - The server was unable to perform some action.
3544 <LI><CODE>I</CODE> - Informational message.
3546 <LI><CODE>D</CODE> - Debugging message.
3550 <P>The <I>date-time</I> field contains the date and time of when the page
3551 started printing. The format of this field is identical to the <I>data-time</I>
3552 field in the <VAR>access_log</VAR> file.
3554 <P>The <I>message</I> fields contains a free-form textual message.
3556 <H3>The page_log File</H3>
3558 <P>The <VAR>page_log</VAR> file lists each page that is sent to a printer.
3559 Each line contains the following information:
3562 printer user job-id date-time page-number num-copies job-billing
3564 DeskJet root 2 [20/May/1999:19:21:05 +0000] 1 0 acme-123
3567 <P>The <I>printer</I> field contains the name of the printer that
3568 printed the page. If you send a job to a printer class, this field will
3569 contain the name of the printer that was assigned the job.
3571 <P>The <I>user</I> field contains the name of the user (the IPP
3572 <CODE>requesting-user-name</CODE> attribute) that submitted this file for
3575 <P>The <I>job-id</I> field contains the job number of the page being printed.
3576 Job numbers are reset to 1 whenever the CUPS server is started, so don't depend
3577 on this number being unique!
3579 <P>The <I>date-time</I> field contains the date and time of when the page
3580 started printing. The format of this field is identical to the <I>data-time</I>
3581 field in the <VAR>access_log</VAR> file.
3583 <P>The <I>page-number</I> and <I>num-pages</I> fields contain the page number
3584 and number of copies being printed of that page. For printer that can not
3585 produce copies on their own, the <I>num-pages</I> field will always be 1.
3587 <P>The <I>job-billing</I> field contains a copy of the
3588 <CODE>job-billing</CODE> attribute provided with the IPP
3589 <CODE>create-job</CODE> or <CODE>print-job</CODE> requests or "-" if none
3593 <H2><A NAME="FILE_TYPING_FILTERING">File Typing and Filtering</A></H2>
3595 <P>CUPS provides a MIME-based file typing and filtering mechanism to
3596 convert files to a printable format for each printer. On startup the
3597 CUPS server reads MIME database files from the <VAR>/etc/cups</VAR>
3598 directory (or a directory specified by the
3599 <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directive) to build
3600 a file type and conversion database in memory. These database files are
3601 plain ASCII text and can be edited with your favorite text editor.
3603 <P>The <VAR>mime.types</VAR> and <VAR>mime.convs</VAR> files define the
3604 standard file types and filters that are available on the system.
3608 <P>The <VAR>mime.types</VAR> file defines the known file types. Each line
3609 of the file starts with the MIME type and may be followed by one or
3610 more file type recognition rules. For example, the
3611 <CODE>text/html</CODE> file type is defined as:
3614 text/html html htm \
3615 printable(0,1024) + \
3616 (string(0,"<HTML>") string(0,"<!DOCTYPE"))
3619 <P>The first two rules say that any file with an extension of
3620 <VAR>.html</VAR> or <VAR>.htm</VAR> is a HTML file. The third rule
3621 says that any file whose first 1024 characters are printable text and
3622 starts with the strings <CODE><HTML></CODE> or
3623 <CODE><!DOCTYPE</CODE> is a HTML file as well.
3625 <P>The first two rules deal solely with the name of the file being
3626 typed. This is useful when the original filename is known, however for
3627 print files the server doesn't have a filename to work with. The third
3628 rule takes care of this possibility and automatically figures out the
3629 file type based upon the contents of the file instead.
3631 <P>The available tests are:
3635 <LI><CODE>( expr )</CODE> - Parenthesis for expression grouping
3637 <LI><CODE>+</CODE> - Logical AND
3639 <LI><CODE>,</CODE> or whitespace - Logical OR
3641 <LI><CODE>!</CODE> - Logical NOT
3643 <LI><CODE>match("pattern")</CODE> - Pattern match on filename
3645 <LI><CODE>extension</CODE> - Pattern match on "*.extension"
3647 <LI><CODE>ascii(offset,length)</CODE> - True if bytes are valid
3648 printable ASCII (CR, NL, TAB, BS, 32-126)
3650 <LI><CODE>printable(offset,length)</CODE> - True if bytes are
3651 printable 8-bit chars (CR, NL, TAB, BS, 32-126, 160-254)
3653 <LI><CODE>string(offset,"string")</CODE> - True if bytes are
3656 <LI><CODE>contains(offset,range,"string")</CODE> - True if the
3657 range of bytes contains the string
3659 <LI><CODE>char(offset,value)</CODE> - True if byte is identical
3661 <LI><CODE>short(offset,value)</CODE> - True if 16-bit integer
3662 is identical (network or "big-endian" byte order)
3664 <LI><CODE>int(offset,value)</CODE> - True if 32-bit integer is
3665 identical (network or "big-endian" byte order)
3667 <LI><CODE>locale("string")</CODE> - True if current locale
3672 <P>All numeric values can be in decimal (123), octal (0123), or hexadecimal
3676 <P>Strings can be in quotes, all by themselves, as a string
3677 of hexadecimal values, or some combination:
3683 <737472696e67>
3687 <P>As shown in the <CODE>text/html</CODE> example, rules can continue on
3688 multiple lines using the backslash (\) character. A more complex example is
3689 the <CODE>image/jpeg</CODE> rules:
3692 image/jpeg jpeg jpg jpe string(0,<FFD8FF>) &&\
3693 (char(3,0xe0) char(3,0xe1) char(3,0xe2) char(3,0xe3)\
3694 char(3,0xe4) char(3,0xe5) char(3,0xe6) char(3,0xe7)\
3695 char(3,0xe8) char(3,0xe9) char(3,0xea) char(3,0xeb)\
3696 char(3,0xec) char(3,0xed) char(3,0xee) char(3,0xef))
3699 <P>This rule states that any file with an extension of
3700 <VAR>.jpeg</VAR>, <VAR>.jpg</VAR>, or <VAR>.jpe</VAR> is a JPEG file.
3701 In addition, any file starting with the hexadecimal string
3702 <CODE><FFD8FF></CODE> (JPEG Start-Of-Image) followed by a
3703 character between and including <CODE>0xe0</CODE> and <CODE>0xef</CODE>
3704 (JPEG APPn markers) is also a JPEG file.
3708 <P>The <VAR>mime.convs</VAR> file defines all of the filter programs that
3709 are known to the system. Each line consists of:
3712 source destination cost program
3714 text/plain application/postscript 50 texttops
3715 application/vnd.cups-postscript application/vnd.cups-raster 50 pstoraster
3716 image/* application/vnd.cups-postscript 50 imagetops
3717 image/* application/vnd.cups-raster 50 imagetoraster
3720 <P>The <I>source</I> field is a MIME type, optionally using a wildcard for
3721 the super-type or sub-type (e.g. "text/plain", "image/*", "*/postscript").
3723 <P>The <I>destination</I> field is a MIME type defined in the
3724 <VAR>mime.types</VAR> file.
3726 <P>The <I>cost</I> field defines a relative cost for the filtering
3727 operation from 1 to 100. The cost is used to choose between two
3728 different sets of filters when converting a file. For example, to convert
3729 from <CODE>image/jpeg</CODE> to <CODE>application/vnd.cups-raster</CODE>,
3730 you could use the <CODE>imagetops</CODE> and <CODE>pstoraster</CODE>
3731 filters for a total cost of 100, or the <CODE>imagetoraster</CODE> filter
3732 for a total cost of 50.
3734 <P>The <I>program</I> field defines the filter program to run; the
3735 special program "-" can be used to make two file types equivalent. The
3736 program must accept the standard filter arguments and environment
3737 variables described in the CUPS Interface Design Description and CUPS
3738 Software Programmers Manual:
3741 program job user title options [filename]
3744 <P>If specified, the <I>filename</I> argument defines a file to read
3745 when filtering, otherwise the filter must read from the standard input.
3746 All filtered output must go to the standard output.
3749 <H3>Adding Filetypes and Filters</H3>
3751 <P>Adding a new file type or filter is fairly straight-forward. Rather
3752 than adding the new type and filter to the <VAR>mime.types</VAR> and
3753 <VAR>mime.convs</VAR> files which are overwritten when you upgrade to a
3754 new version of CUPS, you simple need to create new files with
3755 <VAR>.types</VAR> and <VAR>.convs</VAR> extensions in the
3756 <VAR>/etc/cups</VAR> directory. We recommend that you use the product
3757 or format name, e.g.:
3764 <P>If you are providing a filter for a common file format or printer,
3765 add the company or author name:
3772 <P>This will help to prevent name collisions if you install many
3773 different file types and filters.
3775 <P>Once you choose the names for these files, create them using your
3776 favorite text editor as described earlier in this chapter. Once you
3777 have created the files, restart the <CODE>cupsd</CODE> process as
3778 described earlier in <A HREF="#RESTARTING">"Restarting the CUPS Server"</A>.
3780 <H3>Printer Drivers and PPD Files</H3>
3782 <P>Most CUPS printer drivers utilize one or more printer-specific filters
3783 and a PPD file for each printer model. Printer driver filters are registered
3784 via the PPD file using <CODE>cupsFilter</CODE> attributes:
3787 *cupsFilter: "application/vnd.cups-raster 0 rastertohp"
3790 <P>The filter is specified using the source file type only; the destination
3791 file type is assumed to be <CODE>printer/name</CODE> - suitable for sending
3794 <H3>Writing Your Own Filter or Printer Driver</H3>
3796 <P>CUPS supports an unlimited number of file formats and filters, and can
3797 handle any printer. If you'd like to write a filter or printer driver for
3798 your favorite file format or printer, consult the CUPS Software Programmers
3799 Manual for step-by-step instructions.
3802 <H1 ALIGN="RIGHT"><A NAME="PRINTING_OTHER">7 - Printing with Other Systems</A></H1>
3804 <P>This chapter describes how to print from client systems that use the
3805 LPD, Mac OS, or Windows printing protocols.
3809 <P>CUPS is based on the IPP protocol, so any system that supports IPP
3810 can send jobs to and receive jobs from CUPS automatically. However, not
3811 all systems support IPP yet. This chapter will show you how to connect
3812 these systems to your CUPS server, either to accept jobs from your
3813 server for printing, or to send jobs to your server.
3815 <H2>Printing from LPD Clients</H2>
3817 <P>CUPS supports limited functionality for LPD-based clients. With LPD you can
3818 print files to specific printers, list the queue status, and so forth. However,
3819 the automatic client configuration and printer options are not supported by
3820 the LPD protocol, so you must manually configure each client for the printers
3823 <P>The <CODE>cups-lpd(8)</CODE> program provides support for LPD
3824 clients and can be used from either the <CODE>inetd(8)</CODE> or
3825 <CODE>xinetd(8)</CODE> programs. Add the following line to the
3826 <VAR>/etc/inetd.conf</VAR> file to enable LPD support on your
3827 server through the <CODE>inetd</CODE> program:
3830 printer stream tcp nowait lp /usr/lib/cups/daemon/cups-lpd cups-lpd
3833 <P>The path to the <CODE>cups-lpd</CODE> may vary depending on your
3836 <P>Once you have added this line, send the <CODE>inetd</CODE>
3837 process a <CODE>HUP</CODE> signal or reboot the system:
3840 <B>killall -HUP inetd ENTER</B> [IRIX and some versions of Linux]
3841 <B>kill -HUP <I>pid</I> ENTER [Others]</B>
3842 <B>reboot ENTER [For all systems if the HUP signal fails]</B>
3845 <P>If you are using the <CODE>xinetd</CODE> program, create a
3846 file named <VAR>/etc/xinetd.d/printer</VAR> containing the
3852 socket_type = stream
3856 server = /usr/lib/cups/daemon/cups-lpd
3860 <P>The <CODE>xinetd</CODE> program automatically reads the new
3861 configuration file and enables LPD printing support.
3863 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
3867 <P><CODE>cups-lpd</CODE> currently does not perform any
3868 access control based on the settings in
3869 <VAR>cupsd.conf</VAR> or in the <VAR>hosts.allow</VAR>
3870 or <VAR>hosts.deny</VAR> files used by TCP wrappers.
3871 Therefore, running <CODE>cups-lpd</CODE> on your server
3872 will allow any computer on your network (and perhaps the
3873 entire Internet) to print to your server.
3875 <P>While <CODE>xinetd</CODE> has built-in access control
3876 support, you should use the TCP wrappers package with
3877 <CODE>inetd</CODE> to limit access to only those
3878 computers that should be able to print through your
3885 <H2>Printing to LPD Servers</H2>
3887 <P>CUPS provides the <CODE>lpd</CODE> backend for printing to LPD-based
3888 servers and printers. Use a device URI of <CODE>lpd://server/name</CODE>
3889 to print to a printer on an LPD server, where <CODE>server</CODE>
3890 is the hostname or IP address of the server and <CODE>name</CODE> is
3893 <P>Microsoft Windows NT provides an LPD service under the name "TCP/IP
3894 Printing Services". To enable LPD printing on NT, open the "Services"
3895 control panel, select the "TCP/IP Printing Services" service, and click
3896 on the "Start" button. Any shared printer will then be available via
3899 <H2>Printing from Mac OS Clients</H2>
3901 <P>CUPS does not provide Mac OS support directly. However, there are several
3902 free and commercial software packages that do.
3904 <H3>Columbia Appletalk Package (CAP)</H3>
3906 <P>Because the CAP LaserWriter server (<CODE>lwsrv(8)</CODE>) does
3907 not support specification of PPD files, we do not recommend that you
3908 use CAP with CUPS. However, you can run the <CODE>lpsrv</CODE> program
3909 for limited printing with the command:
3912 lwsrv -n "<I>Name</I>" -p <I>printer</I> -a /usr/lib/adicts -f /usr/lib/LW+Fonts
3915 <P>where <CODE>Name</CODE> is the name you want to use when sharing the
3916 printer, and <CODE>printer</CODE> is the name of the CUPS print queue.
3919 <H3>XINET KA/Spool</H3>
3921 <P>To use your system as a print server for Mac OS clients,
3922 configure each printer using a <CODE>papserver(8)</CODE> in the
3923 <VAR>/usr/adm/appletalk/services</VAR> file, specifying the
3924 corresponding PPD file in the <VAR>/etc/cups/ppd</VAR> directory for
3925 each printer. For a printer named <CODE>MyPrinter</CODE> the entry
3929 /usr/etc/appletalk/papserver -I -L -P /etc/cups/ppd/MyPrinter.ppd \
3930 "Printer Description" MyPrinter
3933 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
3938 <P>Enter the text above on a single line without the backslash (\)
3946 <P>To use your system as a print server for Mac OS clients,
3947 configure each printer in the <VAR>papd.conf</VAR> file, specifying the
3948 corresponding PPD file in the <VAR>/etc/cups/ppd</VAR> directory for
3949 each printer. For a printer named <CODE>MyPrinter</CODE> the entry
3953 Printer Description:MyPrinter@MyServer:\
3954 :pr=|/usr/bin/lp -d MyPrinter:\
3956 :pd=/etc/cups/ppd/MyPrinter.ppd:
3961 <H2>Printing to Mac OS Servers</H2>
3963 <P>CUPS currently does not provide a backend to communicate with a Mac OS
3964 server. However, you can write and install a short shell script
3965 in the <VAR>/usr/lib/cups/backend</VAR> directory that sends a print file
3966 using the appropriate command. The following is a short script that will
3967 run the <CODE>papif</CODE> command provided with CAP.
3969 <P>After copying this script to <VAR>/usr/lib/cups/backend/cap</VAR>,
3970 specify a device URI of <CODE>cap://server/printer</CODE> to use this
3971 backend with a print queue.
3976 <I>"/usr/lib/cups/backend/cap"</I>
3979 # Usage: cap job user title copies options [filename]
3982 # No arguments means show available devices...
3984 if test ${#argv} = 0; then
3985 echo "network cap \"Unknown\" \"Mac OS Printer via CAP\""
3989 # Collect arguments...
3994 if test ${#argv} = 5; then
3995 # Get print file from stdin; copies have already been handled...
3996 file=/var/tmp/$$.prn
4000 # Print file is on command-line...
4004 # Create a dummy cap.printers file for this printer based
4005 # upon a device URI of "cap://server/printer"...
4007 echo $PRINTER/$DEVICE_URI | \
4008 awk -F/ '{print $1 "=" $5 ":LaserWriter@" $4}' > /var/tmp/$$.cap
4010 CAPPRINTERS=/var/tmp/$$.cap; export CAPPRINTERS
4012 # Send the file to the printer, once for each copy. This assumes that you
4013 # have properly initialized the cap.printers file...
4015 while [ $copies -gt 0 ]; do
4016 papif -n $user < $file
4018 copies=`expr $copies - 1`
4021 # Remove any temporary files...
4022 if test ${#argv} = 5; then
4026 /bin/rm -f /var/tmp/$$.cap
4032 <H2>Printing from Windows Clients</H2>
4034 <P>While CUPS does not provide Windows support directly, the free
4035 SAMBA software package does. SAMBA version 2.0.6 is the first release
4036 of SAMBA that supports CUPS. You can download SAMBA from:
4039 <A HREF="http://www.samba.org">http://www.samba.org</A>
4042 <P>To configure SAMBA for CUPS, edit the <VAR>smb.conf</VAR> file and
4043 replace the existing printing commands and options with the line:
4047 printcap name = cups
4050 <P>That's all there is to it! Remote users will now be able to browse and
4051 print to printers on your system.
4053 <H3>Exporting Printer Drivers</H3>
4055 <P>You can optionally export printer drivers from your CUPS
4056 server using the <CODE>cupsaddsmb</CODE> command and the SAMBA
4057 2.2.0 or higher software.
4059 <P>Before you can export the printers you must download the
4060 current Adobe PostScript printer drivers from the Adobe web
4061 site (<A HREF="http://www.adobe.com/">http://www.adobe.com/</A>).
4062 Use the free <CODE>unzip</CODE> software to extract the files
4063 from the self-extracting ZIP file containing the drivers; you
4064 will need the following files:
4078 <P>Copy these files to the <VAR>/usr/share/cups/drivers</VAR>
4079 directory - you may need to rename some of the files so the
4080 filenames are all UPPERCASE.
4082 <P>Next, add a <CODE>print$</CODE> share for the printer
4083 drivers to your <VAR>smb.conf</VAR> file:
4087 comment = Printer Drivers
4088 path = /etc/samba/drivers
4095 <P>The directory for your printer drivers can be anywhere on the
4096 system; just make sure it is writable by the users specified by
4097 the <CODE>write list</CODE> directive. Also, make sure that you
4098 have SAMBA passwords defined for each user in the <CODE>write
4099 list</CODE> using the <CODE>smbpasswd(1)</CODE> command.
4100 Otherwise you will not be able to authenticate
4102 <P>Finally, run the <CODE>cupsaddsmb</CODE> command to export
4103 the printer drivers for one or more queues:
4106 <B>cupsaddsmb -U root printer1 ... printerN <I>ENTER</I></B>
4109 <P>Running <CODE>cupsaddsmb</CODE> with the <CODE>-a</CODE> option
4110 will export all printers:
4113 <B>cupsaddsmb -U root -a <I>ENTER</I></B>
4116 <H2>Printing to Windows Servers</H2>
4118 <P>CUPS can print to Windows servers in one of two ways. The first way uses
4119 the LPD protocol on the CUPS system and the "TCP/IP Printing Services" on
4120 the Windows system. You can find out more about this configuration in the
4121 <A HREF="#LPD">LPD</A> section earlier in this chapter.
4123 <P>The second way is through the Microsoft Server Message Block ("SMB")
4124 protocol. Support for this protocol is provided with the free SAMBA
4125 software package. You can download SAMBA from:
4128 <A HREF="http://www.samba.org">http://www.samba.org</A>
4131 <P>To configure CUPS for SAMBA, run the following command:
4134 <B>ln -s `which smbspool` /usr/lib/cups/backend/smb ENTER</B>
4137 <P>The <CODE>smbspool(1)</CODE> program is provided with SAMBA starting
4138 with SAMBA 2.0.6. Once you have made the link you can configure your
4139 printers with one of the following device URIs:
4142 smb://workgroup/server/sharename
4143 smb://server/sharename
4144 smb://user:pass@workgroup/server/sharename
4145 smb://user:pass@server/sharename
4148 <P>The <CODE>workgroup</CODE> name need only be specified if your
4149 system is using a different workgroup. The <CODE>user:pass</CODE>
4150 strings are required when printing to Windows NT servers or to shares
4151 with passwords enabled under Windows 95 and 98.
4154 <H1 ALIGN="RIGHT"><A NAME="LICENSE">A - Software License Agreement</A></H1>
4156 <EMBED SRC="../LICENSE.html">
4159 <H1 ALIGN="RIGHT"><A NAME="COMMON_NETWORK">B - Common Network Settings</A></H1>
4161 <P>This appendix covers many of the popular TCP/IP network interfaces
4162 and printer servers available on the market today.
4164 <H2>Configuring a Network Interface</H2>
4166 <P>When you first install a network printer or print server on your
4167 LAN, you need to set the Internet Protocol ("IP") address. On most
4168 higher-end "workgroup" printers, you can set the address through the
4169 printer control panel. However, in most cases you will want to assign
4170 the addresses remotely from your workstation. This makes administration
4171 a bit easier and avoids assigning duplicate addresses accidentally.
4173 <P>To setup your printer or print server for remote address assignment,
4174 you'll need the Ethernet Media Access Control ("MAC") address, also
4175 sometimes called a node address, and the IP address you want to use for
4176 the device. The Ethernet MAC address can often be found on the printer
4177 test page or bottom of the print server.
4180 <H3>Configuring the IP Address Using ARP</H3>
4182 <P>The easiest way to set the IP address of a network device is to use
4183 the <CODE>arp(8)</CODE> command. The <CODE>arp</CODE> sends an Address
4184 Resolution Protocol ("ARP") packet to the specified Ethernet MAC address,
4185 setting the network device's IP address:
4188 <B>arp -s ip-address ethernet-address ENTER</B>
4189 <B>arp -s host.domain.com 08:00:69:00:12:34 ENTER</B>
4190 <B>arp -s 192.0.2.2 08:00:69:00:12:34 ENTER</B>
4193 <H3>Configuring the IP Address Using RARP</H3>
4195 <P>The most flexible way to remotely assign IP addresses under UNIX
4196 is through the Reverse Address Resolution Protocol ("RARP"). RARP
4197 allows a network device to request an IP address using its Ethernet
4198 MAC address, and one or more RARP servers on the network will
4199 respond with an ARP packet with the IP address the device can use.
4201 <P>RARP should be used when you have to manage many printers or print
4202 servers, or when you have a network device that does not remember its
4203 IP address after a power cycle. If you just have a single printer or
4204 print server, the <CODE>arp</CODE> command is the way to go.
4206 <P>Some UNIX operating systems use a program called
4207 <CODE>rarpd(8)</CODE> to manage RARP. Others, like Linux, support this
4208 protocol in the kernel. For systems that provide the <CODE>rarpd</CODE>
4209 program you will need to start it before RARP lookups will work:
4215 <P>Under IRIX you can enable this functionality by default using:
4218 <B>chkconfig rarpd on ENTER</B>
4221 <P>Both the <CODE>rarpd</CODE> program and kernel RARP support read a
4222 list of Ethernet and IP addresses from the file <VAR>/etc/ethers</VAR>.
4223 Each line contains the Ethernet address (colon delimited) followed by
4224 an IP address or hostname like:
4227 08:00:69:00:12:34 myprinter.mydomain.com
4228 08:00:69:00:12:34 192.0.2.2
4231 <P>Add a line to this file and cycle the power on the printer or print
4232 server to set its address.
4235 <H3>Configuring the IP Address Using BOOTP</H3>
4237 <P>The BOOTP protocol is used when you need to provide additional information
4238 such as the location of a configuration file to the network interface. Using
4239 the standard <CODE>bootpd(8)</CODE> program supplied with UNIX you simply need to
4240 add a line to the <VAR>/etc/bootptab</VAR> file; for IRIX:
4243 myprinter 08:00:69:00:12:34 192.0.2.2 <VAR>myprinter.boot</VAR>
4247 <P>Newer versions of <CODE>bootpd</CODE> use a different format:
4250 myprinter:ha=080069001234:ip=192.0.2.2:<VAR>t144=myprinter.boot</VAR>
4253 <P>The <VAR>myprinter.boot</VAR> file resides in the <VAR>/usr/local/boot</VAR>
4254 directory by default. If you do not need to provide a boot file you may leave
4255 the last part of the line blank.</P>
4258 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
4263 <P>Some versions of UNIX do not enable the BOOTP service by
4264 default. The <VAR>/etc/inetd.conf</VAR> usually contains a
4265 line for the BOOTP service that can be uncommented if
4271 <H2>Verifying the Printer Connection</H2>
4273 <P>To test that the IP address has been successfully assigned and that the
4274 printer is properly connected to your LAN, type:
4277 <B>ping ip-address ENTER</B>
4280 <P>If the connection is working properly you will see something like:
4283 <B>ping myprinter ENTER</B>
4284 PING myprinter (192.0.2.2): 56 data bytes
4285 64 bytes from 192.0.2.2: icmp_seq=0 ttl=15 time=5 ms
4286 64 bytes from 192.0.2.2: icmp_seq=1 ttl=15 time=3 ms
4287 64 bytes from 192.0.2.2: icmp_seq=2 ttl=15 time=3 ms
4288 64 bytes from 192.0.2.2: icmp_seq=3 ttl=15 time=3 ms
4291 <P>If not, verify that the printer or print server is connected to the
4292 LAN, it is powered on, the LAN cabling is good, and the IP address is
4293 set correctly. You can usually see the current IP address and network
4294 status by printing a configuration or test page on the device.
4297 <H2>Common Network Interface Settings</H2>
4299 <P>Once you have set the IP address you can access the printer or print
4300 server using the <CODE>ipp</CODE>, <CODE>lpd</CODE>, or
4301 <CODE>socket</CODE> backends. The following is a list of common network
4302 interfaces and printer servers and the settings you should use with
4305 <CENTER><TABLE BORDER="1">
4306 <TR VALIGN="TOP" ALIGN="LEFT">
4307 <TH>Model/Manufacturer</TH>
4308 <TH>Device URI(s)</TH>
4310 <TR ALIGN="LEFT" VALIGN="TOP">
4311 <TD>Apple LaserWriter</TD>
4312 <TD>lpd://<I>address</I>/PASSTHRU</TD>
4315 <TR ALIGN="LEFT" VALIGN="TOP">
4316 <TD>Axis w/o IPP<BR>
4317 <A HREF="#AXIS">(see directions)</A></TD>
4318 <TD>socket://<I>address</I>:9100<BR>
4319 socket://<I>address</I>:9101<BR>
4320 socket://<I>address</I>:9102</TD>
4323 <TR ALIGN="LEFT" VALIGN="TOP">
4325 <TD>ipp://<I>address</I>/LPT1<BR>
4326 ipp://<I>address</I>/LPT2<BR>
4327 ipp://<I>address</I>/COM1</TD>
4330 <TR ALIGN="LEFT" VALIGN="TOP">
4331 <TD>Castelle LANpress<SUP>TM</SUP></TD>
4332 <TD>lpd://<I>address</I>/pr1<BR>
4333 lpd://<I>address</I>/pr2<BR>
4334 lpd://<I>address</I>/pr3</TD>
4337 <TR ALIGN="LEFT" VALIGN="TOP">
4338 <TD>DPI NETPrint</TD>
4339 <TD>lpd://<I>address</I>/pr1<BR>
4340 lpd://<I>address</I>/pr2<BR>
4341 lpd://<I>address</I>/pr3</TD>
4343 <TR ALIGN="LEFT" VALIGN="TOP">
4344 <TD>EFI® Fiery® RIP</TD>
4345 <TD>lpd://<I>address</I>/print</TD>
4347 <TR ALIGN="LEFT" VALIGN="TOP">
4348 <TD>EPSON® Multiprotocol Ethernet Interface Board</TD>
4349 <TD>socket://<I>address</I></TD>
4352 <TR ALIGN="LEFT" VALIGN="TOP">
4353 <TD>Extended System ExtendNET</TD>
4354 <TD>lpd://<I>address</I>/pr1<BR>
4355 lpd://<I>address</I>/pr2<BR>
4356 lpd://<I>address</I>/pr3</TD>
4359 <TR ALIGN="LEFT" VALIGN="TOP">
4360 <TD>Hewlett Packard JetDirect w/o IPP</TD>
4361 <TD>socket://<I>address</I>:9100<BR>
4362 socket://<I>address</I>:9101<BR>
4363 socket://<I>address</I>:9102</TD>
4366 <TR ALIGN="LEFT" VALIGN="TOP">
4367 <TD>Hewlett Packard JetDirect w/IPP</TD>
4368 <TD>ipp://<I>address</I>/ipp<BR>
4369 ipp://<I>address</I>/ipp/port1<BR>
4370 ipp://<I>address</I>/ipp/port2<BR>
4371 ipp://<I>address</I>/ipp/port3</TD>
4374 <TR ALIGN="LEFT" VALIGN="TOP">
4375 <TD>Intel® NetportExpress XL, PRO/100</TD>
4376 <TD>lpd://<I>address</I>/LPT1_PASSTHRU<BR>
4377 lpd://<I>address</I>/LPT2_PASSTHRU<BR>
4378 lpd://<I>address</I>/COM1_PASSTHRU</TD>
4380 <TR ALIGN="LEFT" VALIGN="TOP">
4381 <TD>Lexmark<SUP>TM</SUP> MarkNet</TD>
4382 <TD>lpd://<I>address</I>/ps</TD>
4385 <TR ALIGN="LEFT" VALIGN="TOP">
4386 <TD>Linksys EtherFast®<BR>
4387 <A HREF="#LINKSYS">(see directions)</A></TD>
4388 <TD>socket://<I>address</I>:4010<BR>
4389 socket://<I>address</I>:4020<BR>
4390 socket://<I>address</I>:4030</TD>
4392 <TR ALIGN="LEFT" VALIGN="TOP">
4394 <TD>lpd://<I>address</I>/ps</TD>
4396 <TR ALIGN="LEFT" VALIGN="TOP">
4397 <TD>QMS® CrownNet<SUP>TM</SUP></TD>
4398 <TD>lpd://<I>address</I>/ps</TD>
4400 <TR ALIGN="LEFT" VALIGN="TOP">
4401 <TD>Tektronix® PhaserShare<SUP>TM</SUP></TD>
4402 <TD>socket://<I>address</I>:9100</TD>
4404 <TR ALIGN="LEFT" VALIGN="TOP">
4405 <TD>XEROX® 4512 NIC</TD>
4406 <TD>lpd://<I>address</I>/PORT1</TD>
4408 <TR ALIGN="LEFT" VALIGN="TOP">
4409 <TD>XEROX® XNIC</TD>
4410 <TD>lpd://<I>address</I>/PASSTHRU</TD>
4412 <TR ALIGN="LEFT" VALIGN="TOP">
4413 <TD>XEROX® (most others)</TD>
4414 <TD>socket://<I>address</I>:5503</TD>
4418 <H2><A NAME="AXIS">Configuring Axis Print Servers</A></H2>
4420 <P>The Axis print servers can be configured using ARP, RARP, or BOOTP.
4421 However, on models that do not provide IPP support an additional step
4422 must be performed to configure the TCP/IP portion of the print server
4426 <P>Each print server contains a configuration file named
4427 <VAR>config</VAR> that contains a list of network parameters used by
4428 the server. To modify this file you must first download it from the
4429 print server using the <CODE>ftp(1)</CODE> program:
4432 <B>ftp ip-address ENTER</B>
4433 Connected to ip-address.
4434 220 Axis NPS ### FTP Printer Server V#.## MON DD YEAR ready.
4435 ftp> <B>user root ENTER</B>
4436 331 User name ok, need password
4437 Password: <B>pass ENTER</B> <I>(this is not echoed)</I>
4439 ftp> <B>get config ENTER</B>
4440 local: config remote: config
4441 200 PORT command successful.
4442 150 Opening data connection for config (192,0,2,2),
4444 226 Transfer complete.
4445 ##### bytes received in #.## seconds (##### Kbytes/s)
4446 ftp> <B>quit ENTER</B>
4451 <P>Next, edit the file with your favorite text editor and locate the
4452 lines beginning with:
4467 Change the <CODE>RTN_OPT</CODE> line to read:
4470 RTN_OPT. : <B>NO</B>
4474 <P>This disables the Reverse TELNET protocol and enables the standard
4475 TELNET protocol on the print server. Next, assign a port number for
4476 each parallel and serial port on the server as follows:
4479 RTEL_PR1. : <B>9100</B>
4480 RTEL_PR2. : <B>9101</B>
4481 RTEL_PR3. : <B>9102</B>
4482 RTEL_PR4. : <B>9103</B>
4483 RTEL_PR5. : <B>9104</B>
4484 RTEL_PR6. : <B>9105</B>
4485 RTEL_PR7. : <B>9106</B>
4486 RTEL_PR8. : <B>9107</B>
4490 <P>This essentially makes the Axis print server look like a Hewlett
4491 Packard JetDirect EX print server. Save the file and then upload the
4492 new <VAR>config</VAR> file using the <CODE>ftp</CODE> command:
4495 <B>ftp ip-address ENTER</B>
4496 Connected to ip-address.
4497 220 Axis NPS ### FTP Printer Server V#.## MON DD YEAR ready.
4498 ftp> <B>user root ENTER</B>
4499 331 User name ok, need password
4500 Password: <B>pass ENTER</B> <I>(this is not echoed)</I>
4502 ftp> <B>put config CONFIG ENTER</B>
4503 local: config remote: CONFIG
4504 200 PORT command successful.
4505 150 Opening data connection for config (192,0,2,2), (mode ascii).
4506 226 Transfer complete.
4507 ##### bytes received in #.## seconds (##### Kbytes/s)
4508 ftp> <B>get hardreset ENTER</B>
4509 local: hardreset remote: hardreset
4510 200 PORT command successful.
4511 421 Axis NPS ### hard reset, closing connection.
4512 ftp> <B>quit ENTER</B>
4516 <P>Your Axis print server is now ready for use!
4518 <H2><A NAME="LINKSYS">Configuring Linksys Print Servers</A></H2>
4520 <P>The Linksys print servers can be configured using ARP, RARP, or
4521 BOOTP. Like older Axis print servers, an additional step must be
4522 performed to configure the TCP/IP portion of the print server for use
4526 <P>Each print server contains a configuration file named
4527 <VAR>CONFIG</VAR> that contains a list of network parameters used by
4528 the server. To modify this file you must first download it from the
4529 print server using the <CODE>ftp(1)</CODE> program:
4532 <B>ftp -n ip-address ENTER</B>
4533 Connected to ip-address.
4534 220 Print Server Ready.
4535 Remote system type is Print.
4536 ftp> <B>get CONFIG ENTER</B>
4537 local: CONFIG remote: CONFIG
4539 150 Open ASCII Mode Connection.
4540 WARNING! 68 bare linefeeds received in ASCII mode
4541 File may not have transferred correctly.
4542 226 Transfer complete.
4543 ##### bytes received in #.## seconds (##### Kbytes/s)
4544 ftp> <B>quit ENTER</B>
4549 <P>Next, edit the file with your favorite text editor and locate the
4550 lines beginning with:
4558 <P>Change the port number for
4559 each parallel and serial port on the server as follows:
4562 0100 L1_PROUT:<B>P1</B>
4563 0120 L2_PROUT:<B>P2</B>
4564 0140 L3_PROUT:<B>P3</B>
4568 <P>This maps each virtual printer with a physical port. Save the file and then upload the
4569 new <VAR>CONFIG</VAR> file using the <CODE>ftp</CODE> command:
4572 <B>ftp -n ip-address ENTER</B>
4573 Connected to ip-address.
4574 220 Print Server Ready.
4575 Remote system type is Print.
4576 ftp> <B>put CONFIG ENTER</B>
4577 local: CONFIG remote: CONFIG
4579 150 Open ASCII Mode Connection.
4580 226 Transfer complete.
4581 ##### bytes received in #.## seconds (##### Kbytes/s)
4582 ftp> <B>quit ENTER</B>
4586 <P>Your Linksys print server is now ready for use!
4589 <H1 ALIGN="RIGHT"><A NAME="PRINTER_DRIVERS">C - Printer Drivers</A></H1>
4591 <P>This appendix lists the printer drivers that are provided with CUPS.
4593 <H2>Printer Drivers</H2>
4595 <P>CUPS includes the following printer drivers:
4599 <LI><A HREF="#EPSON9">EPSON 9-pin Dot Matrix</A>, <VAR>epson9.ppd</VAR>
4601 <LI><A HREF="#EPSON24">EPSON 24-pin Dot Matrix</A>, <VAR>epson24.ppd</VAR>
4603 <LI><A HREF="#STCOLOR">EPSON Stylus Color</A>, <VAR>stcolor.ppd</VAR>
4605 <LI><A HREF="#STPHOTO">EPSON Stylus Photo</A>, <VAR>stphoto.ppd</VAR>
4607 <LI><A HREF="#DESKJET">HP DeskJet</A>, <VAR>deskjet.ppd</VAR>
4609 <LI><A HREF="#LASERJET">HP LaserJet</A>, <VAR>laserjet.ppd</VAR>
4613 <H2><A NAME="EPSON9">EPSON 9-pin Dot Matrix</A></H2>
4615 <P>The EPSON 9-pin Dot Matrix driver (<VAR>epson9.ppd</VAR>) supports
4616 9-pin dot matrix printers that implement the ESC/P command set. It
4617 provides 60x72, 120x72, and 240x72 DPI output in black only.
4619 <H2><A NAME="EPSON24">EPSON 24-pin Dot Matrix</A></H2>
4621 <P>The EPSON 24-pin Dot Matrix driver (<VAR>epson9.ppd</VAR>) supports
4622 24-pin dot matrix printers that implement the ESC/P command set. It
4623 provides 120x180, 180x180, 360x180, and 360x360 DPI output in black
4626 <H2><A NAME="STCOLOR">EPSON Stylus Color</A></H2>
4628 <P>The EPSON Stylus Color driver (<VAR>stcolor.ppd</VAR>) supports
4629 EPSON Stylus Color printers that implement the ESC/P2 command set. It
4630 provides 180, 360, and 720 DPI output in black and color (CMYK).
4632 <H2><A NAME="STPHOTO">EPSON Stylus Photo</A></H2>
4634 <P>The EPSON Stylus Photo driver (<VAR>stphoto.ppd</VAR>) supports
4635 EPSON Stylus Photo printers that implement the ESC/P2 command set. It
4636 provides 180, 360, and 720 DPI output in black and color (CMYKcm).
4638 <H2><A NAME="DESKJET">HP DeskJet</A></H2>
4640 <P>The HP DeskJet driver (<VAR>deskjet.ppd</VAR>) supports HP DeskJet
4641 printers that implement the PCL command set. It provides 150, 300, and
4642 600 DPI output in black and color (CMYK).
4644 <P>The DeskJet printers that implement the HP-PPA command set (720C,
4645 722C, 820C, and 1100C) are <B>not</B> supported due to a complete lack
4646 of documentation and support from Hewlett Packard.
4648 <P>The duplexer provided with the HP DeskJet 900 series printers is also
4649 not supported for similar reasons.
4651 <H2><A NAME="LASERJET">HP LaserJet</A></H2>
4653 <P>The HP LaserJet driver (<VAR>laserjet.ppd</VAR>) supports HP
4654 LaserJet printers that implement the PCL command set. It provides 150,
4655 300, and 600 DPI output in black only and supports the duplexer if
4658 <P>LaserJet printers that do not implement PCL (3100, 3150) are not
4659 supported due to a complete lack of documentation and support from
4663 <H1 ALIGN="RIGHT"><A NAME="FILES">D - List of Files</A></H1>
4665 <P>This appendix lists the files and directories that are installed for
4666 the Common UNIX Printing System.
4668 <CENTER><TABLE BORDER="1" WIDTH="80%">
4671 <TH>Description</TH>
4674 <TD>/etc/cups/certs/</TD>
4675 <TD>The location of authentication certificate files for local
4679 <TD>/etc/cups/classes.conf</TD>
4680 <TD>The printer classes configuration file for the scheduler.</TD>
4683 <TD>/etc/cups/cupsd.conf</TD>
4684 <TD>The scheduler configuration file.</TD>
4687 <TD>/etc/cups/interfaces/</TD>
4688 <TD>The location of System V interface scripts for printers.</TD>
4691 <TD>/etc/cups/mime.convs</TD>
4692 <TD>The list of standard file filters included with CUPS.</TD>
4695 <TD>/etc/cups/mime.types</TD>
4696 <TD>The list of recognized file types for CUPS.</TD>
4699 <TD>/etc/cups/ppd/</TD>
4700 <TD>The location of PostScript Printer Description ("PPD") files for
4704 <TD>/etc/cups/printers.conf</TD>
4705 <TD>The printer configuration file for the scheduler.</TD>
4708 <TD>/usr/bin/cancel</TD>
4709 <TD>The System V cancel job(s) command.</TD>
4712 <TD>/usr/bin/disable</TD>
4713 <TD>The System V disable printer command.</TD>
4716 <TD>/usr/bin/enable</TD>
4717 <TD>The System V enable printer command.</TD>
4720 <TD>/usr/bin/lp</TD>
4721 <TD>The System V print command.</TD>
4724 <TD>/usr/bin/lpoptions</TD>
4725 <TD>Sets user-defined printing options and defaults.</TD>
4728 <TD>/usr/bin/lppasswd</TD>
4729 <TD>Adds, changes, or removes Digest password accounts.</TD>
4732 <TD>/usr/bin/lpq</TD>
4733 <TD>The Berkeley status command.</TD>
4736 <TD>/usr/bin/lpr</TD>
4737 <TD>The Berkeley print command.</TD>
4740 <TD>/usr/bin/lprm</TD>
4741 <TD>The Berkeley cancel job(s) command.</TD>
4744 <TD>/usr/bin/lpstat</TD>
4745 <TD>The System V status command.</TD>
4748 <TD>/usr/include/cups/</TD>
4749 <TD>CUPS API header files.</TD>
4752 <TD>/usr/lib32/libcups.a<BR>
4753 /usr/lib32/libcupsimage.a</TD>
4754 <TD>Static libraries (IRIX 6.5)</TD>
4757 <TD>/usr/lib/libcups.a<BR>
4758 /usr/lib/libcupsimage.a</TD>
4759 <TD>Static libraries (all others)</TD>
4762 <TD>/usr/lib/libcups.sl.2<BR>
4763 /usr/lib/libcupsimage.sl.2</TD>
4764 <TD>Shared libraries (HP-UX)</TD>
4767 <TD>/usr/lib32/libcups.so.2<BR>
4768 /usr/lib32/libcupsimage.so.2</TD>
4769 <TD>Shared libraries (IRIX 6.5)</TD>
4772 <TD>/usr/lib/libcups.so.2<BR>
4773 /usr/lib/libcupsimage.so.2</TD>
4774 <TD>Shared libraries (all others)</TD>
4777 <TD>/usr/lib/cups/backend/</TD>
4778 <TD>Backends for various types of printer connections.</TD>
4781 <TD>/usr/lib/cups/cgi-bin/</TD>
4782 <TD>CGI programs for the scheduler.</TD>
4785 <TD>/usr/lib/cups/daemon/</TD>
4786 <TD>Daemons for polling and LPD support.</TD>
4789 <TD>/usr/lib/cups/filter/</TD>
4790 <TD>Filters for various types of files.</TD>
4793 <TD>/usr/lib/locale/</TD>
4794 <TD>The location of language-specific message files. (System V)</TD>
4797 <TD>/usr/lib/nls/msg/</TD>
4798 <TD>The location of language-specific message files. (Compaq Tru64 UNIX)</TD>
4801 <TD>/usr/share/locale/</TD>
4802 <TD>The location of language-specific message files. (Linux, *BSD)</TD>
4805 <TD>/usr/sbin/accept</TD>
4806 <TD>The accept-jobs command.</TD>
4809 <TD>/usr/sbin/cupsd</TD>
4810 <TD>The CUPS print scheduler.</TD>
4813 <TD>/usr/sbin/lpadmin</TD>
4814 <TD>The System V printer administration tool.</TD>
4817 <TD>/usr/sbin/lpc</TD>
4818 <TD>The Berkeley printer administration tool.</TD>
4821 <TD>/usr/sbin/lpinfo</TD>
4822 <TD>The get-devices and get-ppds command.</TD>
4825 <TD>/usr/sbin/lpmove</TD>
4826 <TD>The move-jobs command.</TD>
4829 <TD>/usr/sbin/reject</TD>
4830 <TD>The reject-jobs command.</TD>
4833 <TD>/usr/share/catman/a_man/<BR>
4834 /usr/share/catman/u_man/</TD>
4835 <TD>Man pages (IRIX)</TD>
4838 <TD>/usr/share/man/</TD>
4839 <TD>Man pages (Compaq Tru64 UNIX, HP-UX, Solaris)</TD>
4843 <TD>Man pages (all others)</TD>
4846 <TD>/usr/share/cups/data/</TD>
4847 <TD>The location of filter data files.</TD>
4850 <TD>/usr/share/cups/data/testprint.ps</TD>
4851 <TD>The PostScript test page file.</TD>
4854 <TD>/usr/share/cups/fonts/</TD>
4855 <TD>The location of PostScript fonts for the PostScript RIP.</TD>
4858 <TD>/usr/share/cups/model/</TD>
4859 <TD>The location of PostScript Printer Description ("PPD") files and
4860 interface scripts that may be used to setup a printer queue.</TD>
4863 <TD>/usr/share/cups/pstoraster/</TD>
4864 <TD>Other PostScript RIP initialization files.</TD>
4867 <TD>/usr/share/cups/pstoraster/Fontmap</TD>
4868 <TD>The font mapping file (converts filenames to fontnames)</TD>
4871 <TD>/usr/share/cups/templates/</TD>
4872 <TD>The location of HTML template files for the web interfaces.</TD>
4875 <TD>/usr/share/doc/cups/</TD>
4876 <TD>Documentation and web page data for the scheduler.</TD>
4879 <TD>/var/log/cups/</TD>
4880 <TD>The location of scheduler log files.</TD>
4883 <TD>/var/spool/cups/</TD>
4884 <TD>The location of print files waiting to be printed.</TD>
4889 <H1 ALIGN="RIGHT"><A NAME="FAQ">E - Troubleshooting Common Problems</A></H1>
4891 <P>This appendix covers some of the common problems first-time users
4892 encounter when installing and configuring CUPS.
4894 <P>Commercial support for CUPS is available from Easy Software Products.
4895 For more information please contact us at:
4899 <LI>WWW: <A HREF="http://www.easysw.com">
4900 <CODE>http://www.easysw.com</CODE></A>
4902 <LI>EMail: <A HREF="mailto:info@easysw.com">info@easysw.com</A>
4904 <LI>Telephone (M-F, 9-5 EST): +1.301.373.9600
4908 <H2>My Applications Don't See the Available Printers</H2>
4910 <P>Many applications read the <VAR>/etc/printcap</VAR> file to
4911 get a list of available printers.
4913 <P>The default CUPS configuration creates the
4914 <VAR>/etc/printcap</VAR> file automatically. To enable or
4915 disable automatic creation and updating of this file, use the <A
4916 HREF="#Printcap"><CODE>Printcap</CODE></A> directive described
4917 in <A HREF="#PRINTING_MANAGEMENT">Chapter 6, "Printing System
4920 <H2>CUPS Doesn't Recognize My Username or Password!</H2>
4922 <P>CUPS will ask you for a UNIX username and password when you perform
4923 printer administration tasks remotely or via a web browser. The default
4924 configuration requires that you use the <CODE>root</CODE> username and
4925 the corresponding password to authenticate the request.
4927 <P>CUPS does not allow you to authenticate an administration request
4928 with an account that has no password for security reasons. If you do
4929 not have a password on your <CODE>root</CODE> account then you won't be
4930 able to add printers remotely or via the web interface!
4933 <P>To disable password authentication you need to edit the
4934 <VAR>/etc/cups/cupsd.conf</VAR> file and comment out the
4942 <P>for the <VAR>/admin</VAR> location. Then restart the CUPS server as
4943 described in <A HREF="#PRINTING_MANAGEMENT">Chapter 6, "Printing System
4944 Management"</A>.</P>
4946 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
4951 <P>Disabling password checks will allow any local user to
4952 change your printer and class configuration, but remote
4953 administration from another machine will still not be allowed.
4958 <H2><A NAME="ALLOW_REMOTE">I Can't Do Administration Tasks from Another Machine!</A></H2>
4960 <P>The default CUPS configuration limits administration to the local
4961 machine. To open up access, edit the <VAR>/etc/cups/cupsd.conf</VAR>
4962 and comment out the lines reading:
4967 Allow from 127.0.0.1
4970 <P>for the <VAR>/admin</VAR> location. Then restart the CUPS server as
4971 described in <A HREF="#PRINTING_MANAGEMENT">Chapter 6, "Printing System
4972 Management"</A>.</P>
4974 <CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
4979 <P>Allowing administration access from all hosts is a potential
4980 security risk. Please read <A HREF="#PRINTING_SECURITY">Chapter
4981 6, "Printing System Management"</A> for a description of these
4982 risks and ways to minimize them.
4988 <H2>I Can't Do Administration Tasks from My Web Browser!</H2>
4990 <P>This problem is usually caused by:
4994 <LI>not specifying the correct password for the
4997 <LI>accessing the CUPS server using the hostname or IP
4998 address of the server without enabling remote access for
4999 administration functions. This can be corrected by following
5000 the instructions in the <A HREF="#ALLOW_REMOTE">"I Can't Do
5001 Administration Tasks from Another Machine!"</A> section earlier
5004 <LI>not setting a password on the root account. CUPS will not
5005 authenticate a user account that does not have a password for
5008 <LI>authenticating using an account other than root, but the
5009 account you are using is not a member of the system group.
5011 <LI>configuring CUPS to use Digest authentication, but
5012 your web browser does not support Digest authentication.
5016 <H2>Connection Refused Messages</H2>
5018 <P>Under normal circumstances, "connection refused" messages for a
5019 networked printer should be expected from time to time. Most network
5020 interfaces only allow a single connection to be made at any given time
5021 (one job at a time) and will refuse access to all other systems while
5022 the first connection is active. CUPS automatically retries the
5023 connection once every 30 seconds.
5025 <P>If the problem persists and you are unable to print any jobs to the printer,
5026 verify that another machine is not maintaining a connection with the printer,
5027 and that you have selected the proper port or printer name for the printer.
5029 <P>Also, most external print servers will refuse connections if the connected
5030 printer is turned off or is off-line. Verify that the affected printer is
5031 turned on and is online.
5033 <H2>Write Error Messages</H2>
5035 <P>If you get "write error" messages on a printer queue the printer
5036 interface (usually a Hewlett Packard JetDirect interface) has timed out
5037 and reset the network connection from your workstation.
5039 <P>The error is caused by that startup delay between the initial setup
5040 of the printer or plotter and the first page of print data that is
5044 <P>To correct the problem, change the idle timeout on the interface to at least
5045 180 seconds or 3 minutes. To change the timeout on a Hewlett Packard
5046 JetDirect interface, type:
5049 <B>telnet ip-address ENTER</B>
5051 Trying ip-address...
5052 Connected to ip-address.
5053 Escape character is `^]'.
5055 Please type [Return] two times, to initialize telnet configuration
5057 > <B>idle-timeout: 180 ENTER</B>