]> git.ipfire.org Git - thirdparty/cups.git/blame - doc/sam.shtml
projects / thirdparty / cups.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Copyright update.
[thirdparty/cups.git] / doc / sam.shtml
CommitLineData
6a921799 1<HTML>
2<HEAD>
1d9595ab 3 <META NAME="COPYRIGHT" CONTENT="Copyright 1997-2003, All Rights Reserved">
753453e4 4 <META NAME="DOCNUMBER" CONTENT="CUPS-SAM-1.2.0">
6a921799 5 <META NAME="Author" CONTENT="Easy Software Products">
78021ed9 6 <TITLE>CUPS Software Administrators Manual</TITLE>
6a921799 7</HEAD>
8<BODY>
9
e75387bc 10<H1 ALIGN="RIGHT">Preface</H1>
6a921799 11
766ec9c5 12<P>This software administrators manual provides printer administration
38138d28 13information for the Common UNIX Printing System<SUP>TM</SUP>
753453e4 14("CUPS<SUP>TM</SUP>"), version 1.2.0.
6a921799 15
1aee2644 16<EMBED SRC="system-overview.shtml">
e15022a6 17
38138d28 18<!-- NEED 3in -->
6a921799 19<H2>Document Overview</H2>
20
21<P>This software administrators manual is organized into the following sections:</P>
22
23<UL>
766ec9c5 24 <LI><A HREF="#OVERVIEW">1 - Printing System Overview</A>
25 <LI><A HREF="#BUILDING_INSTALLING">2 - Building and Installing CUPS</A>
fd7cc15d 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>
e75387bc 30 <LI><A HREF="#PRINTING_OTHER">7 - Printing with Other Systems</A>
766ec9c5 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>
fd7cc15d 34 <LI><A HREF="#FILES">D - List of Files</A>
35 <LI><A HREF="#FAQ">E - Troubleshooting Common Problems</A>
6a921799 36</UL>
37
ecf3075f 38<H2>Notation Conventions</H2>
39
7bfde0bb 40<P>Various font and syntax conventions are used in this guide. Examples and
ecf3075f 41their meanings and uses are explained below:
42
43<CENTER><TABLE WIDTH="80%">
44<TR>
45 <TH>Example</TH>
46 <TD>&nbsp;&nbsp;&nbsp;</TD>
47 <TH>Description</TH>
48</TR>
49<TR><TD>&nbsp;</TD></TR>
50<TR VALIGN="TOP">
51 <TD><CODE>lpstat</CODE><BR>
52 <CODE>lpstat(1)</CODE></TD>
53
54 <TD>&nbsp;&nbsp;&nbsp;</TD>
55
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
58 number.</TD>
59</TR>
60<TR><TD>&nbsp;</TD></TR>
61<TR VALIGN="TOP">
62 <TD><VAR>/var</VAR><BR>
63 <VAR>/usr/share/cups/data/testprint.ps</VAR></TD>
64
65 <TD>&nbsp;&nbsp;&nbsp;</TD>
66
67 <TD>File and directory names.</TD>
68</TR>
69<TR><TD>&nbsp;</TD></TR>
70<TR VALIGN="TOP">
71 <TD NOWRAP><TT>Request ID is Printer-123</TT></TD>
72
73 <TD>&nbsp;&nbsp;&nbsp;</TD>
74
75 <TD>Screen output.</TD>
76</TR>
77<TR><TD>&nbsp;</TD></TR>
78<TR VALIGN="TOP">
79 <TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD>
80
81 <TD>&nbsp;&nbsp;&nbsp;</TD>
82
9cfa8573 83 <TD>Literal user input; special keys like <KBD>ENTER</KBD> are
ecf3075f 84 in ALL CAPS.</TD>
85</TR>
86<TR><TD>&nbsp;</TD></TR>
87<TR VALIGN="TOP">
88 <TD>12.3</TD>
89
90 <TD>&nbsp;&nbsp;&nbsp;</TD>
91
92 <TD>Numbers in the text are written using the period (.) to indicate
93 the decimal point.</TD>
94</TR>
95</TABLE></CENTER>
96
97<!-- NEED 3in -->
98<H2>Abbreviations</H2>
99
100The following abbreviations are used throughout this manual:
101
102<UL>
103<DL>
104
105 <DT>kb
106 <DD>Kilobytes, or 1024 bytes<BR>&nbsp;
107
108 <DT>Mb
109 <DD>Megabytes, or 1048576 bytes<BR>&nbsp;
110
111 <DT>Gb
112 <DD>Gigabytes, or 1073741824 bytes<BR>&nbsp;
113
114</DL>
115</UL>
116
117<H2>Other References</H2>
118
119<UL>
120<DL>
121
122 <DT>CUPS Software Programmers Manual
123
124 <DD>A programmer guide for interfacing with and/or extending the CUPS
125 software.<BR>&nbsp;
126
127 <DT>CUPS Software Users Manual
128
129 <DD>An end-user guide for using the CUPS software.<BR>&nbsp;
130
131</DL>
132</UL>
133
134
3d9e2586 135<EMBED SRC="printing-overview.shtml">
9da2dc55 136
7bfde0bb 137
766ec9c5 138<H1 ALIGN="RIGHT"><A NAME="BUILDING_INSTALLING">2 - Building and Installing CUPS</A></H1>
ba8a42d9 139
140<P>This chapter shows how to build and install the Common UNIX Printing System.
e15022a6 141If you are installing a binary distribution from the CUPS web site, proceed to
aca0f695 142the section titled, <A HREF="#BINARY">Installing a Binary Distribution</A>.
e15022a6 143
144<H2>Installing a Source Distribution</H2>
ba8a42d9 145
766ec9c5 146<P>This section describes how to compile and install CUPS on your system
147from the source code.
148
aca0f695 149<H3><A NAME="REQUIREMENTS">Requirements</A></H3>
ba8a42d9 150
551d3a88 151<P>You'll need ANSI-compliant C and C++ compilers to build CUPS on your
3d9e2586 152system. As its name implies, CUPS is designed to run on the UNIX
153operating system, however the CUPS interface library and most of the
38138d28 154filters and backends supplied with CUPS should also compile and run
155under Microsoft Windows.
ba8a42d9 156
157<P>For the image file filters and PostScript RIP, you'll need the JPEG,
158PNG, TIFF, and ZLIB libraries. CUPS will build without these, but with
aca0f695 159significantly reduced functionality. Easy Software Products maintains a
160mirror of the current versions of these libraries at:
ba8a42d9 161
162<UL><PRE>
163<A HREF="ftp://ftp.easysw.com/pub/libraries">ftp://ftp.easysw.com/pub/libraries</A>
164</PRE></UL>
165
166<P>If you make changes to the man pages you'll need GNU groff or another
167nroff-like package. GNU groff is available from:
168
169<UL><PRE>
170<A HREF="ftp://ftp.gnu.org/pub/groff">ftp://ftp.gnu.org/pub/groff</A>
171</PRE></UL>
172
173<P>The documentation is formatted using the HTMLDOC software. If you need to
174make changes you can get the HTMLDOC software from:
175
176<UL><PRE>
177<A HREF="http://www.easysw.com/htmldoc">http://www.easysw.com/htmldoc</A>
178</PRE></UL>
179
753453e4 180<P>Finally, you'll need a <CODE>make</CODE> program that
181understands the <CODE>include</CODE> directive - FreeBSD,
182NetBSD, and OpenBSD developers should use the <CODE>gmake</CODE>
183program.
184
aca0f695 185<H3><A NAME="COMPILING">Compiling CUPS</A></H3>
ba8a42d9 186
187<P>CUPS uses GNU autoconf to configure the makefiles and source code
766ec9c5 188for your system. Type the following command to configure CUPS for your
189system:
ba8a42d9 190
191<UL><PRE>
766ec9c5 192<B>./configure ENTER</B>
ba8a42d9 193</PRE></UL>
194
195<P>The default installation will put the CUPS software in the
766ec9c5 196<VAR>/etc</VAR>, <VAR>/usr</VAR>, and <VAR>/var</VAR> directories on
197your system, which will overwrite any existing printing commands on
198your system. Use the <CODE>--prefix</CODE> option to install the CUPS
199software in another location:
ba8a42d9 200
201<UL><PRE>
fd7cc15d 202<B>./configure --prefix=/some/directory ENTER</B>
ba8a42d9 203</PRE></UL>
204
205<P>If the PNG, JPEG, TIFF, and ZLIB libraries are not installed in a
250b9cef 206system default location (typically <VAR>/usr/include</VAR> and
551d3a88 207<VAR>/usr/lib</VAR>) you'll need to set the <CODE>CFLAGS</CODE>,
208<CODE>CXXFLAGS</CODE>, and <CODE>LDFLAGS</CODE> environment variables
209prior to running configure:
ba8a42d9 210
211<UL><PRE>
551d3a88 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>
b1d503b0 215<B>setenv DSOFLAGS "-L/some/directory" ENTER</B>
551d3a88 216<B>./configure ... ENTER</B>
217</PRE></UL>
218
219<P>or:
220
221<UL><PRE>
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>
b1d503b0 225<B>DSOFLAGS="-L/some/directory"; export DSOFLAGS ENTER</B>
766ec9c5 226<B>./configure ... ENTER</B>
ba8a42d9 227</PRE></UL>
228
7428af94 229<P>To enable support for encryption, you'll also want to add the
230"--enable-ssl" option:
231
232<UL><PRE>
233./configure --enable-ssl
234</PRE></UL>
235
236<P>SSL and TLS support require the OpenSSL library, available at:
237
238<UL><PRE>
239<A HREF="http://www.openssl.org">http://www.openssl.org</A>
240</PRE></UL>
241
753453e4 242<P>If the OpenSSL headers and libraries are not installed in the
243standard directories, use the <CODE>--with-openssl-includes</CODE>
244and <CODE>--with-openssl-libs</CODE> options:</P>
245
246<UL><PRE>
247./configure --enable-ssl \
248 --with-openssl-includes=/foo/bar/include \
249 --with-openssl-libs=/foo/bar/lib
250</PRE></UL>
251
ba8a42d9 252<P>Once you have configured things, just type:
253
254<UL><PRE>
766ec9c5 255<B>make ENTER</B>
ba8a42d9 256</PRE></UL>
257
258<P>to build the software.
259
fd7cc15d 260<!-- NEED 4in -->
aca0f695 261<H3><A NAME="INSTALLING">Installing the Software</A></H3>
ba8a42d9 262
766ec9c5 263<P>Use the "install" target to install the software:
ba8a42d9 264
265<UL><PRE>
766ec9c5 266<B>make install ENTER</B>
ba8a42d9 267</PRE></UL>
268
fd7cc15d 269<CENTER><TABLE WIDTH="80%" BORDER="1" BGCOLOR="#cccccc" CELLPADDING="5">
270<TR>
271 <TD>
766ec9c5 272 <B>WARNING:</B>
273
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
551d3a88 277 to reinstall the old printing system from your operating system CDs.
fd7cc15d 278 </TD>
279</TR>
280</TABLE></CENTER>
766ec9c5 281
9cfa8573 282<H3><A NAME="RUNNING">Running the Software</A></H3>
ba8a42d9 283
fd7cc15d 284<P>Once you have installed the software you can start the CUPS server by
ba8a42d9 285typing:
6a921799 286
ba8a42d9 287<UL><PRE>
766ec9c5 288<B>/usr/sbin/cupsd ENTER</B>
ba8a42d9 289</PRE></UL>
6a921799 290
fd7cc15d 291<!-- NEED 4in -->
aca0f695 292<H2><A NAME="BINARY">Installing a Binary Distribution</A></H2>
e15022a6 293
aca0f695 294<P>CUPS comes in a variety of binary distribution formats. Easy
295Software Products provides binaries in TAR format with installation and
296removal scripts ("portable" distributions), and in RPM and DPKG formats
297for Red Hat and Debian-based distributions. Portable distributions are
298available for all platforms, while the RPM and DPKG distributions are
299only available for Linux.
300
fd7cc15d 301<CENTER><TABLE WIDTH="80%" BORDER="1" BGCOLOR="#cccccc" CELLPADDING="5">
302<TR>
303 <TD>
e15022a6 304 <B>WARNING:</B>
305
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
aca0f695 309 to remove the CUPS software with the provided script and/or
551d3a88 310 reinstall the old printing system from your operating system CDs.
fd7cc15d 311 </TD>
312</TR>
313</TABLE></CENTER>
e15022a6 314
aca0f695 315
316<H3><A NAME="PORTABLE-BINARY">Installing a Portable Distribution</A></H3>
317
318<P>To install the CUPS software from a portable distribution you will
766ec9c5 319need to be logged in as root; doing an <CODE>su</CODE> is good enough.
320Once you are the root user, run the installation script with:
e15022a6 321
322<UL><PRE>
766ec9c5 323<B>./cups.install ENTER</B>
e15022a6 324</PRE></UL>
325
326<P>After asking you a few yes/no questions the CUPS software will be
327installed and the scheduler will be started automatically.
328
551d3a88 329<!-- NEED 2in -->
aca0f695 330<H3><A NAME="RPM-BINARY">Installing an RPM Distribution</A></H3>
331
766ec9c5 332<P>To install the CUPS software from an RPM distribution you will need
333to be logged in as root; doing an <CODE>su</CODE> is good enough. Once
334you are the root user, run RPM with:
aca0f695 335
336<UL><PRE>
766ec9c5 337<B>rpm -e lpr</B>
338<B>rpm -i cups-1.1-linux-M.m.n-intel.rpm ENTER</B>
aca0f695 339</PRE></UL>
340
341<P>After a short delay the CUPS software will be
342installed and the scheduler will be started automatically.
343
344<H3><A NAME="DPKG-BINARY">Installing an Debian Distribution</A></H3>
2f89d155 345
aca0f695 346<P>To install the CUPS software from a Debian distribution you will
766ec9c5 347need to be logged in as root; doing an <CODE>su</CODE> is good enough.
348Once you are the root user, run dpkg with:
2f89d155 349
aca0f695 350<UL><PRE>
766ec9c5 351<B>dpkg -i cups-1.1-linux-M.m.n-intel.deb ENTER</B>
aca0f695 352</PRE></UL>
353
354<P>After a short delay the CUPS software will be installed and the
355scheduler will be started automatically.
2f89d155 356
38138d28 357
d3d79f52 358<H1 ALIGN="RIGHT"><A NAME="MANAGING_PRINTERS">3 - Managing Printers</A></H1>
aca0f695 359
fd7cc15d 360<P>This chapter describes how to add your first printer and how to
361manage your printers.
38138d28 362
363<H2>The Basics</H2>
aca0f695 364
766ec9c5 365<P>Each printer queue has a name associated with it; the printer name
366must start with a letter and can contain up to 127 letters, numbers,
38138d28 367and the underscore (_). Case is not significant, e.g. "PRINTER", "Printer",
368and "printer" are considered to be the same name.
aca0f695 369
370<P>Printer queues also have a device associated with them. The device can be
371a parallel port, a network interface, and so forth. Devices within CUPS use
372Uniform Resource Identifiers ("URIs") which are a more general form of
373Uniform Resource Locators ("URLs") that are used in your web browser. For
766ec9c5 374example, the first parallel port in Linux usually uses a device URI of
38138d28 375<CODE>parallel:/dev/lp1</CODE>.
376
fd7cc15d 377<!-- NEED 2.5in -->
38138d28 378<P>You can see a complete list of supported devices by running the
551d3a88 379<CODE>lpinfo(8)</CODE> command:
766ec9c5 380
381<UL><PRE>
38138d28 382<B>lpinfo -v ENTER</B>
38138d28 383network socket
384network http
385network ipp
386network lpd
387direct parallel:/dev/lp1
388serial serial:/dev/ttyS1?baud=115200
389serial serial:/dev/ttyS2?baud=115200
551d3a88 390direct usb:/dev/usb/lp0
38138d28 391network smb
766ec9c5 392</PRE></UL>
aca0f695 393
38138d28 394<P>The <CODE>-v</CODE> option specifies that you want a list of available
395devices. The first word in each line is the type of device (direct, file,
396network, or serial) and is followed by the device URI or method name for
397that device. File devices have device URIs of the form
398<CODE>file:/directory/filename</CODE> while network devices use the more
399familiar <CODE>method://server</CODE> or <CODE>method://server/path</CODE>
400format.
401
aca0f695 402<P>Finally, printer queues usually have a PostScript Printer Description
403("PPD") file associated with them. PPD files describe the capabilities of
404each printer, the page sizes supported, etc., and are used for PostScript
405and non-PostScript printers. CUPS includes PPD files for HP LaserJet, HP
406DeskJet, EPSON 9-pin, EPSON 24-pin, and EPSON Stylus printers.
407
fd7cc15d 408<H2>Adding Your First Printer</H2>
409
410<P>CUPS provides two methods for adding printers: a command-line
551d3a88 411program called <CODE>lpadmin(8)</CODE> and a Web interface. The
fd7cc15d 412<CODE>lpadmin</CODE> command allows you to perform most printer
413administration tasks from the command-line and is located in
414<VAR>/usr/sbin</VAR>. The Web interface is located at:
415
416<UL><PRE>
417<A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
418</PRE></UL>
419
420<P>and steps you through printer configuration. If you don't like
421command-line interfaces, try the <A HREF="#ADD_WEB">Web interface</A> instead.
422
423<H3>Adding Your First Printer from the Command-Line</H3>
aca0f695 424
38138d28 425<P>Run the <CODE>lpadmin</CODE> command with the <CODE>-p</CODE> option to add a
426printer to CUPS:
aca0f695 427
428<UL><PRE>
fd7cc15d 429<B>/usr/sbin/lpadmin -p <I>printer</I> -E -v <I>device</I> -m <I>ppd</I> ENTER</B>
aca0f695 430</PRE></UL>
431
9cfa8573 432<P>For a HP DeskJet printer connected to the parallel port this would look
38138d28 433like:
aca0f695 434
38138d28 435<UL><PRE>
fd7cc15d 436<B>/usr/sbin/lpadmin -p DeskJet -E -v parallel:/dev/lp1 -m deskjet.ppd ENTER</B>
38138d28 437</PRE></UL>
aca0f695 438
9cfa8573 439<P>Similarly, a HP LaserJet printer using a JetDirect network interface at
38138d28 440IP address 11.22.33.44 would be added with the command:
aca0f695 441
442<UL><PRE>
fd7cc15d 443<B>/usr/sbin/lpadmin -p LaserJet -E -v socket://11.22.33.44 -m laserjet.ppd ENTER</B>
aca0f695 444</PRE></UL>
445
38138d28 446<P>As you can see, <CODE>deskjet.ppd</CODE> and <CODE>laserjet.ppd</CODE> are
447the PPD files for the HP DeskJet and HP LaserJet drivers included with CUPS.
448You'll find a complete list of PPD files and the printers they will work with
449in <A HREF="#PRINTER_DRIVERS">Appendix C, "Printer Drivers"</A>.
450
753453e4 451
452<P>For a dot matrix printer connected to the serial port this would might look like:
453
454<UL><PRE>
455<B>/usr/sbin/lpadmin -p DotMatrix -E -v serial:/dev/ttyS0?baud=9600+size=8+parity=none+flow=soft deskjet.ppd ENTER</B>
456</PRE></UL>
457
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.
460If you do not need flow control, delete the "+flow=soft" portion.
461
462
fd7cc15d 463<H3><A NAME="ADD_WEB">Adding Your First Printer from the Web</A></H3>
38138d28 464
465<P>The CUPS web server provides a user-friendly "wizard" interface for
466adding your printers. Rather than figuring out which device URI and PPD file
467to use, you can instead click on the appropriate listings and fill in some
468simple information. Enter the following URL in your web browser to begin:
aca0f695 469
470<UL><PRE>
38138d28 471<A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
aca0f695 472</PRE></UL>
2f89d155 473
38138d28 474<P>Click on the <VAR>Add Printer</VAR> button to add a printer.
766ec9c5 475
38138d28 476<H2>Managing Printers from the Command-Line</H2>
ba8a42d9 477
fd7cc15d 478<P>The <CODE>lpadmin</CODE> command enables you to perform most printer
38138d28 479administration tasks from the command-line. You'll find <CODE>lpadmin</CODE>
480in the <VAR>/usr/sbin</VAR> directory.
ba8a42d9 481
38138d28 482<H3>Adding and Modifying Printers</H3>
ba8a42d9 483
38138d28 484<P>Run the <CODE>lpadmin</CODE> command with the <CODE>-p</CODE> option
485to add or modify a printer:
ba8a42d9 486
487<UL><PRE>
fd7cc15d 488<B>/usr/sbin/lpadmin -p <I>printer</I> <I>options</I> ENTER</B>
ba8a42d9 489</PRE></UL>
490
38138d28 491<P>The <I>options</I> arguments can be any of the following:
e15022a6 492
38138d28 493<UL>
494<DL>
ba8a42d9 495
38138d28 496 <DT>-c <I>class</I>
ba8a42d9 497
38138d28 498 <DD>Adds the named printer to printer class <VAR>class</VAR>.
499 If the class does not exist then it is created.
ba8a42d9 500
38138d28 501 <DT>-i <I>interface</I>
ba8a42d9 502
38138d28 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
507 a printer.
ba8a42d9 508
38138d28 509 <DT>-m <I>model</I>
6a921799 510
38138d28 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>.
e15022a6 516
38138d28 517 <DT>-r <I>class</I>
e15022a6 518
9cfa8573 519 <DD>Removes the named printer from printer class <VAR>class</VAR>.
38138d28 520 If the resulting class becomes empty then it is removed.
e15022a6 521
38138d28 522 <DT>-v <I>device-uri</I>
e15022a6 523
38138d28 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.
e15022a6 527
38138d28 528 <DT>-D <I>info</I>
6a921799 529
38138d28 530 <DD>Provides a textual description of the printer, e.g.
531 "John's Personal Printer".
6a921799 532
38138d28 533 <DT>-E
6a921799 534
38138d28 535 <DD>Enables the printer and accepts job. This option is
536 equivalent to running the <CODE>enable(1)</CODE> and
551d3a88 537 <CODE>accept(8)</CODE> commands on the printer.
6a921799 538
38138d28 539 <DT>-L <I>location</I>
ba8a42d9 540
38138d28 541 <DD>Provides a textual location for the printer, e.g.
542 "Computer Lab 5".
ba8a42d9 543
38138d28 544 <DT>-P <I>ppd-file</I>
ba8a42d9 545
38138d28 546 <DD>Specifies a local PPD file for the printer driver.
547
548</DL>
549</UL>
550
551<H3>Deleting Printers</H3>
552
553<P>Run the <CODE>lpadmin</CODE> command with the <CODE>-x</CODE> option
554to delete a printer:
ba8a42d9 555
556<UL><PRE>
fd7cc15d 557<B>/usr/sbin/lpadmin -x <I>printer</I> ENTER</B>
ba8a42d9 558</PRE></UL>
6a921799 559
38138d28 560<H3>Setting the Default Printer</H3>
6a921799 561
38138d28 562<P>Run the <CODE>lpadmin</CODE> command with the <CODE>-d</CODE> option
563to set a default printer:
ba8a42d9 564
565<UL><PRE>
fd7cc15d 566<B>/usr/sbin/lpadmin -d <I>printer</I> ENTER</B>
ba8a42d9 567</PRE></UL>
568
38138d28 569<P>The default printer can be overridden by the user using the
570<CODE>lpoptions(1)</CODE> command.
ba8a42d9 571
38138d28 572<H3>Starting and Stopping Printers</H3>
7d49e4a2 573
574<P>The <CODE>enable</CODE> and <CODE>disable</CODE> commands start and stop
575printer queues, respectively:
576
577<UL><PRE>
766ec9c5 578<B>/usr/bin/enable <I>printer</I> ENTER</B>
579<B>/usr/bin/disable <I>printer</I> ENTER</B>
7d49e4a2 580</PRE></UL>
581
582<P>Printers that are disabled may still accept jobs for printing, but won't
583actually print any files until they are restarted. This is useful if the
fd7cc15d 584printer malfunctions and you need time to correct the problem. Any queued
7d49e4a2 585jobs are printed after the printer is enabled (started).
586
38138d28 587<H3>Accepting and Rejecting Print Jobs</H3>
7d49e4a2 588
589<P>The <CODE>accept</CODE> and <CODE>reject</CODE> commands accept and reject
590print jobs for the named printer, respectively:
591
592<UL><PRE>
fd7cc15d 593<B>/usr/sbin/accept <I>printer</I> ENTER</B>
594<B>/usr/sbin/reject <I>printer</I> ENTER</B>
7d49e4a2 595</PRE></UL>
596
597<P>As noted above, a printer can be stopped but accepting new print
598jobs. A printer can also be rejecting new print jobs while it finishes
599those that have been queued. This is useful for when you must perform
600maintenance on the printer and will not have it available to users for
601a long period of time.
602
9cfa8573 603<H3>Setting Quotas on a Printer</H3>
604
605<P>CUPS supports page and size-based quotas for each printer.
606The quotas are tracked individually for each user, but a single set of
607limits applies to all users for a partiuclar printer. For example, you
608can limit every user to 5 pages per day on an expensive printer, but
609you cannot limit every user except Johnny.</P>
610
611<P>The <I>job-k-limit</I>, <I>job-page-limit</I>, and <I>job-quota-peiod</I>
612options determine whether and how quotas are enforced for a printer.
613The <I>job-quota-period</I> option determines the time interval for
614quota tracking. The interval is expressed in seconds, so a day is
61586,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>
618
619<P>For quotas to be enforced, the period and at least one of the limits
620must be set to a non-zero value. The following options will enable
621quotas:</P>
622
623<UL>
624<PRE>
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>
627</PRE>
628</UL>
629
630<P>Or, you can combine all three options on the same line.</P>
631
632<H3>Restricting User Access to a Printer</H3>
633
634<P>The <CODE>-u</CODE> option of the <CODE>lpadmin</CODE> command controls which users can
635print to a printer. The default configuration allows all users to print
636to a printer:</P>
637
638<UL>
639<PRE>
640<B>/usr/sbin/lpadmin -p <I>printer</I> -u allow:all <I>ENTER</I></B>
641</PRE>
642</UL>
643
644<P>CUPS supports allow and deny lists so that you can specify a
645list of users who are allowed to print or not allowed to print. Along
646with your list of users, you can specify whether they are allowed or
647not allowed to use the printer:</P>
648
649<UL>
650<PRE>
651<B>/usr/sbin/lpadmin -p <I>printer</I> -u allow:peter,paul,mary <I>ENTER</I></B>
652</PRE>
653</UL>
654
655<P>This command allows peter, paul, and mary to print to the named
656printer, but all other users cannot print. The command:</P>
657
658<UL>
659<PRE>
660<B>/usr/sbin/lpadmin -p <I>printer</I> -u deny:peter,paul,mary <I>ENTER</I></B>
661</PRE>
662</UL>
663
664<P>has the opposite effect. All users except peter, paul, and mary will
665be able to print to the named printer.</P>
666
667<CENTER>
668<TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
669<TR>
670 <TD><B>NOTE:</B>
671
672 <P>The <I>allow</I> and <I>deny</I> options are not cummulative. That
673 is, you must provide the complete list of users to allow or deny each
674 time.</P>
675
676 <P>Also, CUPS only maintains one list of users - the list can
677 allow or deny users from printing. If you specify an allow list and
678 then specify a deny list, the deny list will replace the allow list -
679 only one list is active at any time.</P>
680
681 </TD>
682</TR>
683</TABLE>
684</CENTER>
685
38138d28 686<H2>Managing Printers from the Web</H2>
687
688<P>The Web interface is located at:
689
690<UL><PRE>
691<A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
692</PRE></UL>
693
694<P>From there you can perform all printer management tasks with a few
695simple mouse clicks.
696
697
fd7cc15d 698<H1 ALIGN="RIGHT"><A NAME="PRINTER_CLASSES">4 - Printer Classes</A></H1>
38138d28 699
700<P>This chapter describes what printer classes are and how to manage them.
701
702<H2>The Basics</H2>
703
704<P>CUPS provides collections of printers called <I>printer classes</I>. Jobs
705sent to a class are forwarded to the first available printer in the class.
706Classes can themselves be members of other classes, so it is possible for
707you to define very large, distributed printer classes for high-availability
708printing.
709
710<P>CUPS also supports <I>implicit classes</I>. Implicit classes work just
711like printer classes, but they are created automatically based upon the
712available printers and classes on the network. This allows you to setup
713multiple print servers with identical printer configurations and have the
714client machines send their print jobs to the first available server. If
715one or more servers go down, the jobs are automatically redirected to the
716servers that are running, providing fail-safe printing.
717
718<H2>Managing Printer Classes from the Command-Line</H2>
719
720<P>Run the <CODE>lpadmin</CODE> command with the <CODE>-p</CODE> and <CODE>-c</CODE> options
721to add a printer to a class:
722
723<UL><PRE>
fd7cc15d 724<B>/usr/sbin/lpadmin -p <I>printer</I> -c <I>class</I> ENTER</B>
38138d28 725</PRE></UL>
726
727<P>The <I>class</I> is created automatically if it doesn't exist. To remove a
728printer from a class use the <CODE>-r</CODE> option:
729
730<UL><PRE>
fd7cc15d 731<B>/usr/sbin/lpadmin -p <I>printer</I> -r <I>class</I> ENTER</B>
38138d28 732</PRE></UL>
733
734<P>To remove the entire class just use the <CODE>-x</CODE> option:
735
736<UL><PRE>
fd7cc15d 737<B>/usr/sbin/lpadmin -x <I>class</I> ENTER</B>
38138d28 738</PRE></UL>
739
740<H2>Managing Printer Classes from the Web Interface</H2>
741
742<P>The Web interface is located at:
743
744<UL><PRE>
745<A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
746</PRE></UL>
747
748<P>The <VAR>Add Class</VAR> and <VAR>Modify Class</VAR> interfaces provide a
749list of available printers; click on the printers of interest to add them to
750the class.
751
752<H2>Implicit Classes</H2>
753
754<P>A noted earlier, implicit classes are created automatically from the
fd7cc15d 755available network printers and classes. To disable this functionality,
756set the <A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
757directive to <CODE>Off</CODE> in the <CODE>cupsd.conf</CODE> file. You
758will find more information on doing this in
759<A HREF="#PRINTING_MANAGEMENT">Chapter 6, "Printing System
760Management"</A>.
38138d28 761
762
fd7cc15d 763<H1 ALIGN="RIGHT"><A NAME="CLIENT_SETUP">5 - Client Setup</A></H1>
38138d28 764
765<P>This chapter discusses several ways to configure CUPS clients for
766printing.
767
fd7cc15d 768<H2>The Basics</H2>
38138d28 769
770<P>A client is any machine that sends print jobs to another machine for
771final printing. Clients can also be servers if they communicate directly with
772any printers of their own.
773
38138d28 774<P>CUPS supports several methods of configuring client machines:
775
fd7cc15d 776<UL>
38138d28 777 <LI><A HREF="#CLIENT_MANUAL">Manual configuration of print queues.</A>
38138d28 778 <LI><A HREF="#CLIENT_SERVER">Specifying a single server for printing.</A>
38138d28 779 <LI><A HREF="#CLIENT_AUTO">Automatic configuration of print queues.</A>
38138d28 780 <LI><A HREF="#CLIENT_POLL">Specifying multiple servers for printing.</A>
9cfa8573 781 <LI><A HREF="#CLIENT_RELAY">Relaying printers to other clients.</A>
fd7cc15d 782</UL>
38138d28 783
784<H3><A NAME="CLIENT_MANUAL">Manual Configuration of Print Queues</A></H3>
785
786<P>The most tedious method of configuring client machines is to configure
787each remote queue by hand using the <CODE>lpadmin</CODE> command:
788
789<UL><PRE>
790<B>lpadmin -p <I>printer</I> -E -v ipp://<I>server</I>/printers/<I>printer</I> ENTER</B>
791</PRE></UL>
792
fd7cc15d 793<P>The <CODE>printer</CODE> name is the name of the printer on the server
794machine. The <CODE>server</CODE> name is the hostname or IP address of the
38138d28 795server machine. Repeat the <CODE>lpadmin</CODE> command for each remote
9cfa8573 796printer you wish to use.</P>
797
798<CENTER>
799<TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
800 <TR>
801 <TD><B> NOTE:</B>
802 <P>Manual configuration of print queues is not recommended for large
803 numbers of client machines because of the administration nightmare it
804 creates. For busy networks, consider subnetting groups of clients and
805 polling and relaying printer information instead.</P>
806 </TD>
807 </TR>
808</TABLE>
809</CENTER>
38138d28 810
811<H3><A NAME="CLIENT_SERVER">Specifying a Single Server for Printing</A></H3>
812
813<P>CUPS can be configured to run without a local spooler and send all
814jobs to a single server. However, if that server goes down then all
815printing will be disabled. Use this configuration only as absolutely needed.
816
817<P>The default server is normally "localhost". To override the default
551d3a88 818server create a file named <VAR>/etc/cups/client.conf</VAR> and add
38138d28 819a line reading:
820
821<UL><PRE>
822ServerName <I>server</I>
823</PRE></UL>
824
825<P>to the file. The <VAR>server</VAR> name can be the hostname or IP address
826of the default server.
827
828<P>The default server can also be customized on a per-user basis. To set a
fd7cc15d 829user-specific server create a file named <VAR>~/.cupsrc</VAR> and add a line
38138d28 830reading:
831
832<UL><PRE>
833ServerName <I>server</I>
834</PRE></UL>
835
551d3a88 836<P>to the file. The <VAR>server</VAR> name can be the hostname or IP
837address of the default server.
38138d28 838
839<H3><A NAME="CLIENT_AUTO">Automatic Configuration of Print Queues</A></H3>
840
841<P>CUPS supports automatic client configuration of printers on the same
fd7cc15d 842subnet. To configure printers on the same subnet, <I>do nothing</I>.
843Each client should see the available printers within 30 seconds
844automatically. The printer and class lists are updated automatically as
845printers and servers are added or removed.
2f89d155 846
fd7cc15d 847<P>If you want to see printers on other subnets as well, use the
9cfa8573 848<A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A>
849directive as described next.</P>
850
851<CENTER>
852<TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
853 <TR>
854 <TD><B> NOTE:</B>
855 <P>The<A HREF="#BrowseAddress"> <CODE>BrowseAddress</CODE></A> directive
856 enables broadcast traffic from your server. The default configuration
857 braodcasts printer information every 30 seconds. Although this printer
858 information does not use much bandwidth, typically about 80 bytes per
859 printer, it can add up with large numbers of servers and printers.</P>
860 <P>Use the <A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A>
861 and <A HREF="#BrowseTimeout"><CODE>BrowseTimeout</CODE></A> directives to tune
862 the amount of data that is added to your network load. In addition,
863 subnets can be used to minimize the amount of traffic that is carried
864 by the &quot;backbone&quot; of your large network.</P>
865 </TD>
866 </TR>
867</TABLE>
868</CENTER>
2f89d155 869
38138d28 870<H3><A NAME="CLIENT_POLL">Specifying Multiple Servers for Printing</A></H3>
871
872<P>If you have CUPS servers on different subnets, then you should configure
873CUPS to poll those servers. Polling provides the benefits of automatic
874configuration without significant configuration on the clients, and multiple
875clients on the same subnet can share the same configuration information.
876
9cfa8573 877<P>Polling is enabled by specifying one or more
878<A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A>
879directives in the <VAR>/etc/cups/cupsd.conf</VAR> file.
880For information on making these changes, see
881<A HREF="#PRINTING_MANAGEMENT">Chapter 6, "Printing System Management"</A>.
2f89d155 882
9cfa8573 883<P>Multiple <A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A> lines can
884be used to poll multiple CUPS servers. To limit the amount of
885polling you do from client machines, you can have only one of the
886clients do the polling and relay that information to the others on the
887same subnet (described next).</P>
888
889<H3><A NAME="CLIENT_RELAY">Relaying Printers to Other Clients</A></H3>
890
891<P>When you have clients and servers spread across multiple subnets, the
892polling method is inefficient. CUPS provides a
893<A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A> directive that enables a
894single client to relay (broadcast) the polled printer information to the local subnet.</P>
895
896<P>For example, Server A and Server B are on subnet 1 and subnet 2,
897while the clients are on subnet 3.
898To provide printers to all of the clients in subnet 3,
899client C will be configured with the following directives in <VAR>/etc/cups/cupsd.conf</VAR>:</P>
900
901<UL><PRE>
902# Poll the two servers
903<B>
904BrowsePoll ServerA ENTER
905BrowsePoll ServerB ENTER
906</B>
907
908# Relay the printers to the local subnet
909<B>
910BrowseRelay 127.0.0.1 192.168.3.255 ENTER
911</B></PRE></UL>
912
913<P>The <A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A> line specifies a source address and mask.
914Any browse packets coming from a matching address wil be sent to the given broadcast address.
915In this case, we want the packets from the local machine (127.0.0.1) relayed to the other clients.</P>
916
917<P>As printers are found using polling,
918they are relayed from client C to the rest of the clients through a broadcast on subnet 3.
919The rest of the clients can use the standard <VAR>cupsd.conf</VAR> configuration.</P>
920
921<P>The <A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A> directive can also be used to relay
922browsing packets from one network interface to another.
923For example, if client C in the previous example had network interfaces attaches to both
924subnet 1 and subnet 2, it could use the <A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A> directive exclusively:
925
926<UL><PRE>
927# Relay the printers from subnet 1 and 2 to subnet 3
928<B>
929BrowseRelay 192.168.1 192.168.3.255 ENTER
930BrowseRelay 192.168.2 192.168.3.255 ENTER
931</B></PRE></UL>
932
933<H2>Load Balancing and Failsafe Operation</H2>
934
935<P>When using server polling or broadcasting, CUPS clients can
936automatically merge identical printers on multiple servers into a
937single <I>implicit class</I> queue. Clients assume that printers with
938the same name on multiple servers are in fact the same printer or type
939of printer being served by multiple machines.</P>
940
941<P>If you have two printers, LaserJet@ServerA and LaserJet@ServerB, a
942third implicit class called <I>LaserJet</I> will be created
943automatically on the client that refers to both printers. If the client
944also has a local printer with the name LaserJet then an implicit class
945named <I>AnyLaserJet</I> will be created instead.</P>
946
947<P>The client will alternate between servers and automatically stop
948sending jobs to a server if it goes down, providing a load-balancing
949effect and fail-safe operation with automatic switchover.</P>
950
951<CENTER><TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
952 <TR>
953 <TD><B> NOTE:</B>
954 <P>Note that implicit classes (<A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>)
955 are enabled by default.</P>
956 </TD>
957 </TR>
958</TABLE></CENTER>
2f89d155 959
fd7cc15d 960<H1 ALIGN="RIGHT"><A NAME="PRINTING_MANAGEMENT">6 - Printing System Management</A></H1>
6a921799 961
e15022a6 962<P>This chapter shows how you can configure the CUPS server.
963
38138d28 964<H2>The Basics</H2>
9da2dc55 965
fd7cc15d 966<P>Several text files are used to configure CUPS. All of the server
967configuration files are located in the <VAR>/etc/cups</VAR> directory:
38138d28 968
969<UL>
970<DL>
971
fd7cc15d 972 <!-- NEED 1in -->
38138d28 973 <DT>classes.conf
974
975 <DD>This file contains information on each printer class.
976 Normally you manipulate this file using the
fd7cc15d 977 <CODE>lpadmin</CODE> command or the Web interface.<BR>&nbsp;
38138d28 978
fd7cc15d 979 <!-- NEED 1in -->
38138d28 980 <DT>client.conf
981
982 <DD>This file provides the default server name for client
fd7cc15d 983 machines. See <A HREF="#CLIENT_SETUP">Chapter 5, "Client
984 Setup"</A> for more information.<BR>&nbsp;
38138d28 985
fd7cc15d 986 <!-- NEED 1in -->
38138d28 987 <DT>cupsd.conf
988
989 <DD>This file controls how the CUPS server
990 (<VAR>/usr/sbin/cupsd</VAR>) operates and is normally edited by
fd7cc15d 991 hand.<BR>&nbsp;
38138d28 992
fd7cc15d 993 <!-- NEED 1in -->
38138d28 994 <DT>mime.convs
995
996 <DD>This file contains a list of standard file conversion filters
fd7cc15d 997 and their costs. You normally do not edit this file.<BR>&nbsp;
38138d28 998
fd7cc15d 999 <!-- NEED 1in -->
38138d28 1000 <DT>mime.types
1001
1002 <DD>This file contains a list of standard file formats and how to
fd7cc15d 1003 recognize them. You normally do not edit this file.<BR>&nbsp;
38138d28 1004
fd7cc15d 1005 <!-- NEED 1in -->
38138d28 1006 <DT>printers.conf
1007
1008 <DD>This file contains information on each printer. Normally
1009 you manipulate this file using the <CODE>lpadmin</CODE> command
fd7cc15d 1010 or the Web Interface.<BR>&nbsp;
38138d28 1011
1012</DL>
1013</UL>
1014
551d3a88 1015<H2><A NAME="RESTARTING">Restarting the CUPS Server</A></H2>
1016
38138d28 1017<P>Once you have made a change to a configuration file you need to
fd7cc15d 1018restart the CUPS server by sending it a <CODE>HUP</CODE> signal or using the
38138d28 1019supplied initialization script. The CUPS distributions install the
1020script in the <VAR>init.d</VAR> directory with the name
1021<VAR>cups</VAR>. The location varies based upon the operating system:
1022
1023<UL><PRE>
9cfa8573 1024<B>/etc/software/init.d/cups restart ENTER</B>
38138d28 1025<B>/etc/rc.d/init.d/cups restart ENTER</B>
1026<B>/etc/init.d/cups restart ENTER</B>
1027<B>/sbin/init.d/cups restart ENTER</B>
1028</PRE></UL>
1029
1030<H2>Changing the Server Configuration</H2>
1031
1032<P>The <VAR>/etc/cups/cupsd.conf</VAR> file contains configuration
1033<I>directives</I> that control how the server functions. Each directive
1034is listed on a line by itself followed by its value. Comments are
551d3a88 1035introduced using the number sign ("#") character at the beginning of a
1036line. Since the server configuration file consists of plain text, you
1037can use your favorite text editor to make changes to it.
38138d28 1038
fd7cc15d 1039<!-- NEED 4in -->
e75387bc 1040<H2>Server Directives</H2>
38138d28 1041
e75387bc 1042<P>The <VAR>cupsd.conf</VAR> file contains many directives that
1043determine how the server operates:
38138d28 1044
1045<UL>
e75387bc 1046<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
1047<TR>
1048<TD VALIGN="TOP">
1049
1050 <LI><A HREF="#AccessLog"><CODE>AccessLog</CODE></A>
1051 <LI><A HREF="#Allow"><CODE>Allow</CODE></A>
1052 <LI><A HREF="#AuthClass"><CODE>AuthClass</CODE></A>
1053 <LI><A HREF="#AuthGroupName"><CODE>AuthGroupName</CODE></A>
1054 <LI><A HREF="#AuthType"><CODE>AuthType</CODE></A>
04d756fc 1055 <LI><A HREF="#AutoPurgeJobs"><CODE>AutoPurgeJobs</CODE></A>
e75387bc 1056 <LI><A HREF="#BrowseAddress"><CODE>BrowseAddress</CODE></A>
1057 <LI><A HREF="#BrowseAllow"><CODE>BrowseAllow</CODE></A>
1058 <LI><A HREF="#BrowseDeny"><CODE>BrowseDeny</CODE></A>
1059 <LI><A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A>
1060 <LI><A HREF="#BrowseOrder"><CODE>BrowseOrder</CODE></A>
1061 <LI><A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A>
1062 <LI><A HREF="#BrowsePort"><CODE>BrowsePort</CODE></A>
753453e4 1063 <LI><A HREF="#BrowseProtocols"><CODE>BrowseProtocols</CODE></A>
e75387bc 1064 <LI><A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A>
6380867c 1065 <LI><A HREF="#BrowseShortNames"><CODE>BrowseShortNames</CODE></A>
e75387bc 1066 <LI><A HREF="#BrowseTimeout"><CODE>BrowseTimeout</CODE></A>
1067 <LI><A HREF="#Browsing"><CODE>Browsing</CODE></A>
d11458ff 1068 <LI><A HREF="#Classification"><CODE>Classification</CODE></A>
753453e4 1069 <LI><A HREF="#ClassifyOverride"><CODE>ClassifyOverride</CODE></A>
9cfa8573 1070 <LI><A HREF="#ConfigFilePerm"><CODE>ConfigFilePerm</CODE></A>
6380867c 1071 <LI><A HREF="#DataDir"><CODE>DataDir</CODE></A>
b1d503b0 1072 <LI><A HREF="#DefaultCharset"><CODE>DefaultCharset</CODE></A>
1073 <LI><A HREF="#DefaultLanguage"><CODE>DefaultLanguage</CODE></A>
1074 <LI><A HREF="#Deny"><CODE>Deny</CODE></A>
1075 <LI><A HREF="#DocumentRoot"><CODE>DocumentRoot</CODE></A>
9cfa8573 1076 <LI><A HREF="#Encryption"><CODE>Encryption</CODE></A>
e75387bc 1077
1078</TD>
1079<TD VALIGN="TOP">
1080&nbsp;&nbsp;&nbsp;
1081</TD>
1082<TD VALIGN="TOP">
1083
e75387bc 1084 <LI><A HREF="#ErrorLog"><CODE>ErrorLog</CODE></A>
d0a31f54 1085 <LI><A HREF="#FilterLimit"><CODE>FilterLimit</CODE></A>
9cfa8573 1086 <LI><A HREF="#FilterNice"><CODE>FilterNice</CODE></A>
b1d503b0 1087 <LI><A HREF="#FontPath"><CODE>FontPath</CODE></A>
e75387bc 1088 <LI><A HREF="#Group"><CODE>Group</CODE></A>
753453e4 1089 <LI><A HREF="#HideImplicitMembers"><CODE>HideImplicitMembers</CODE></A>
e75387bc 1090 <LI><A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A>
1091 <LI><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
753453e4 1092 <LI><A HREF="#ImplicitAnyClasses"><CODE>ImplicitAnyClasses</CODE></A>
1093 <LI><A HREF="#Include"><CODE>Include</CODE></A>
e75387bc 1094 <LI><A HREF="#KeepAliveTimeout"><CODE>KeepAliveTimeout</CODE></A>
1095 <LI><A HREF="#KeepAlive"><CODE>KeepAlive</CODE></A>
b1d503b0 1096 <LI><A HREF="#Limit"><CODE>Limit</CODE></A>
1097 <LI><A HREF="#LimitExcept"><CODE>LimitExcept</CODE></A>
1098 <LI><A HREF="#LimitRequestBody"><CODE>LimitRequestBody</CODE></A>
e75387bc 1099 <LI><A HREF="#Listen"><CODE>Listen</CODE></A>
1100 <LI><A HREF="#Location"><CODE>Location</CODE></A>
9cfa8573 1101 <LI><A HREF="#LogFilePerm"><CODE>LogFilePerm</CODE></A>
e75387bc 1102 <LI><A HREF="#LogLevel"><CODE>LogLevel</CODE></A>
1103 <LI><A HREF="#MaxClients"><CODE>MaxClients</CODE></A>
2e9f3b68 1104 <LI><A HREF="#MaxCopies"><CODE>MaxCopies</CODE></A>
04d756fc 1105 <LI><A HREF="#MaxJobs"><CODE>MaxJobs</CODE></A>
0e5b6226 1106 <LI><A HREF="#MaxJobsPerPrinter"><CODE>MaxJobsPerPrinter</CODE></A>
1107 <LI><A HREF="#MaxJobsPerUser"><CODE>MaxJobsPerUser</CODE></A>
e75387bc 1108 <LI><A HREF="#MaxLogSize"><CODE>MaxLogSize</CODE></A>
1109 <LI><A HREF="#MaxRequestSize"><CODE>MaxRequestSize</CODE></A>
b1d503b0 1110 <LI><A HREF="#Order"><CODE>Order</CODE></A>
9cfa8573 1111 <LI><A HREF="#PageLog"><CODE>PageLog</CODE></A>
e75387bc 1112
1113</TD>
1114<TD VALIGN="TOP">
1115&nbsp;&nbsp;&nbsp;
1116</TD>
1117<TD VALIGN="TOP">
1118
0e5b6226 1119 <LI><A HREF="#Port"><CODE>Port</CODE></A>
e75387bc 1120 <LI><A HREF="#PreserveJobFiles"><CODE>PreserveJobFiles</CODE></A>
1121 <LI><A HREF="#PreserveJobHistory"><CODE>PreserveJobHistory</CODE></A>
1122 <LI><A HREF="#Printcap"><CODE>Printcap</CODE></A>
b1d503b0 1123 <LI><A HREF="#PrintcapFormat"><CODE>PrintcapFormat</CODE></A>
9ae34eb7 1124 <LI><A HREF="#PrintcapGUI"><CODE>PrintcapGUI</CODE></A>
08ffbb44 1125 <LI><A HREF="#RemoteRoot"><CODE>RemoteRoot</CODE></A>
e75387bc 1126 <LI><A HREF="#RequestRoot"><CODE>RequestRoot</CODE></A>
b1d503b0 1127 <LI><A HREF="#Require"><CODE>Require</CODE></A>
e75387bc 1128 <LI><A HREF="#RIPCache"><CODE>RIPCache</CODE></A>
9cfa8573 1129 <LI><A HREF="#RootCertDuration"><CODE>RootCertDuration</CODE></A>
b1d503b0 1130 <LI><A HREF="#RunAsUser"><CODE>RunAsUser</CODE></A>
1131 <LI><A HREF="#Satisfy"><CODE>Satisfy</CODE></A>
e75387bc 1132 <LI><A HREF="#ServerAdmin"><CODE>ServerAdmin</CODE></A>
1133 <LI><A HREF="#ServerBin"><CODE>ServerBin</CODE></A>
b1d503b0 1134 <LI><A HREF="#ServerCertificate"><CODE>ServerCertificate</CODE></A>
1135 <LI><A HREF="#ServerKey"><CODE>ServerKey</CODE></A>
e75387bc 1136 <LI><A HREF="#ServerName"><CODE>ServerName</CODE></A>
1137 <LI><A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A>
b1d503b0 1138 <LI><A HREF="#SSLListen"><CODE>SSLListen</CODE></A>
1139 <LI><A HREF="#SSLPort"><CODE>SSLPort</CODE></A>
e75387bc 1140 <LI><A HREF="#SystemGroup"><CODE>SystemGroup</CODE></A>
1141 <LI><A HREF="#TempDir"><CODE>TempDir</CODE></A>
1142 <LI><A HREF="#Timeout"><CODE>Timeout</CODE></A>
1143 <LI><A HREF="#User"><CODE>User</CODE></A>
1144
1145</TD>
1146</TR>
1147</TABLE>
38138d28 1148</UL>
1149
e75387bc 1150<!-- NEED 3in -->
1151<H3><A NAME="AccessLog">AccessLog</A></H3>
1152<HR>
38138d28 1153
e75387bc 1154<H4>Examples</H4>
38138d28 1155
1156<UL><PRE>
e75387bc 1157AccessLog /var/log/cups/access_log
6380867c 1158AccessLog /var/log/cups/access_log-%s
e75387bc 1159AccessLog syslog
38138d28 1160</PRE></UL>
1161
e75387bc 1162<H4>Description</H4>
38138d28 1163
e75387bc 1164<P>The <CODE>AccessLog</CODE> directive sets the name of the access log
1165file. If the filename is not absolute then it is assumed to be relative
1166to the <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
1167access log file is stored in "common log format" and can be used by any
1168web access reporting tool to generate a report on CUPS server activity.
38138d28 1169
6380867c 1170<P>The server name can be included in the filename by using
1171<CODE>%s</CODE> in the name.
1172
551d3a88 1173<P>The special name "syslog" can be used to send the access information
1174to the system log instead of a plain file.
1175
e75387bc 1176<P>The default access log file is <VAR>/var/log/cups/access_log</VAR>.
38138d28 1177
551d3a88 1178<!-- NEED 6in -->
e75387bc 1179<H3><A NAME="Allow">Allow</A></H3>
1180<HR>
38138d28 1181
e75387bc 1182<H4>Examples</H4>
38138d28 1183
e75387bc 1184<UL><PRE>
1185Allow from All
1186Allow from None
1187Allow from *.domain.com
1188Allow from .domain.com
1189Allow from host.domain.com
1190Allow from nnn.*
1191Allow from nnn.nnn.*
1192Allow from nnn.nnn.nnn.*
1193Allow from nnn.nnn.nnn.nnn
1194Allow from nnn.nnn.nnn.nnn/mm
1195Allow from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
9cfa8573 1196Allow from @LOCAL
1197Allow from @IF(name)
e75387bc 1198</PRE></UL>
38138d28 1199
e75387bc 1200<H4>Description</H4>
38138d28 1201
e75387bc 1202<P>The <CODE>Allow</CODE> directive specifies a hostname, IP address,
1203or network that is allowed access to the server. <CODE>Allow</CODE>
1204directives are cummulative, so multiple <CODE>Allow</CODE> directives
1205can be used to allow access for multiple hosts or networks. The
1206<CODE>/mm</CODE> notation specifies a CIDR netmask:
38138d28 1207
e75387bc 1208<CENTER><TABLE BORDER="1">
1209<TR>
fd7cc15d 1210 <TH WIDTH="10%">mm</TH>
1211 <TH WIDTH="20%">netmask</TH>
1212 <TH WIDTH="10%">mm</TH>
1213 <TH WIDTH="20%">netmask</TH>
e75387bc 1214</TR>
1215<TR>
fd7cc15d 1216 <TD ALIGN="CENTER">0</TD>
1217 <TD ALIGN="CENTER">0.0.0.0</TD>
1218 <TD ALIGN="CENTER">8</TD>
1219 <TD ALIGN="CENTER">255.0.0.0</TD>
e75387bc 1220</TR>
1221<TR>
fd7cc15d 1222 <TD ALIGN="CENTER">1</TD>
1223 <TD ALIGN="CENTER">128.0.0.0</TD>
1224 <TD ALIGN="CENTER">16</TD>
1225 <TD ALIGN="CENTER">255.255.0.0</TD>
e75387bc 1226</TR>
1227<TR>
fd7cc15d 1228 <TD ALIGN="CENTER">2</TD>
1229 <TD ALIGN="CENTER">192.0.0.0</TD>
1230 <TD ALIGN="CENTER">24</TD>
1231 <TD ALIGN="CENTER">255.255.255.0</TD>
e75387bc 1232</TR>
1233<TR>
fd7cc15d 1234 <TD ALIGN="CENTER">...</TD>
1235 <TD ALIGN="CENTER">...</TD>
1236 <TD ALIGN="CENTER">32</TD>
1237 <TD ALIGN="CENTER">255.255.255.255</TD>
e75387bc 1238</TR>
1239</TABLE></CENTER>
38138d28 1240
9cfa8573 1241<P>The <CODE>@LOCAL</CODE> name will allow access from all local
1242network interfaces, but not remote point-to-point interfaces. The
1243<CODE>@IF(name)</CODE> name will allow access from the named
1244interface.
1245
e75387bc 1246<P>The <CODE>Allow</CODE> directive must appear inside a
1247<A HREF="#Location"><CODE>Location</CODE></A> directive.
38138d28 1248
e75387bc 1249<!-- NEED 3in -->
1250<H3><A NAME="AuthClass">AuthClass</A></H3>
1251<HR>
38138d28 1252
e75387bc 1253<H4>Examples</H4>
38138d28 1254
e75387bc 1255<UL><PRE>
1256AuthClass Anonymous
1257AuthClass User
1258AuthClass System
1259AuthClass Group
1260</PRE></UL>
38138d28 1261
e75387bc 1262<H4>Description</H4>
38138d28 1263
fd7cc15d 1264<P>The <CODE>AuthClass</CODE> directive defines what level of authentication
1265is required:
38138d28 1266
e75387bc 1267<UL>
38138d28 1268
e75387bc 1269 <LI><CODE>Anonymous</CODE> - No authentication should be performed
1270 (default.)
38138d28 1271
e75387bc 1272 <LI><CODE>User</CODE> - A valid username and password is required.
38138d28 1273
e75387bc 1274 <LI><CODE>System</CODE> - A valid username and password is
fd7cc15d 1275 required, and the username must belong to the "sys" group; this
1276 can be changed using the
1277 <A HREF="#SystemGroup"><CODE>SystemGroup</CODE></A> directive.
38138d28 1278
e75387bc 1279 <LI><CODE>Group</CODE> - A valid username and password is
1280 required, and the username must belong to the group named by
1281 the <CODE>AuthGroupName</CODE> directive.
38138d28 1282
e75387bc 1283</UL>
38138d28 1284
e75387bc 1285<P>The <CODE>AuthClass</CODE> directive must appear inside a
1286<A HREF="#Location"><CODE>Location</CODE></A> directive.
38138d28 1287
e75387bc 1288<!-- NEED 3in -->
1289<H3><A NAME="AuthGroupName">AuthGroupName</A></H3>
1290<HR>
9da2dc55 1291
e75387bc 1292<H4>Examples</H4>
38138d28 1293
e75387bc 1294<UL><PRE>
1295AuthGroupName mygroup
fd7cc15d 1296AuthGroupName lp
e75387bc 1297</PRE></UL>
38138d28 1298
e75387bc 1299<H4>Description</H4>
38138d28 1300
e75387bc 1301<P>The <CODE>AuthGroupName</CODE> directive sets the group to use for
1302<CODE>Group</CODE> authentication.
38138d28 1303
e75387bc 1304<P>The <CODE>AuthGroupName</CODE> directive must appear inside a
1305<A HREF="#Location"><CODE>Location</CODE></A> directive.
38138d28 1306
e75387bc 1307<!-- NEED 3in -->
1308<H3><A NAME="AuthType">AuthType</A></H3>
1309<HR>
38138d28 1310
e75387bc 1311<H4>Examples</H4>
38138d28 1312
e75387bc 1313<UL><PRE>
1314AuthType None
1315AuthType Basic
1316AuthType Digest
753453e4 1317AuthType BasicDigest
e75387bc 1318</PRE></UL>
38138d28 1319
e75387bc 1320<H4>Description</H4>
38138d28 1321
e75387bc 1322<P>The <CODE>AuthType</CODE> directive defines the type of authentication to
1323perform:
38138d28 1324
e75387bc 1325<UL>
38138d28 1326
e75387bc 1327 <LI><CODE>None</CODE> - No authentication should be performed
1328 (default.)
38138d28 1329
e75387bc 1330 <LI><CODE>Basic</CODE> - Basic authentication should be
1331 performed using the UNIX password and group files.
38138d28 1332
e75387bc 1333 <LI><CODE>Digest</CODE> - Digest authentication should be
1334 performed using the <VAR>/etc/cups/passwd.md5</VAR> file.
38138d28 1335
753453e4 1336 <LI><CODE>BasicDigest</CODE> - Basic authentication should be
1337 performed using the <VAR>/etc/cups/passwd.md5</VAR> file.
1338
38138d28 1339</UL>
1340
753453e4 1341<P>When using <CODE>Basic</CODE>, <CODE>Digest</CODE>, or
1342<CODE>BasicDigest</CODE> authentication, clients connecting
1343through the <CODE>localhost</CODE> interface can also
e75387bc 1344authenticate using <A HREF="#CERTIFICATES">certificates</A>.
38138d28 1345
e75387bc 1346<P>The <CODE>AuthType</CODE> directive must appear inside a
1347<A HREF="#Location"><CODE>Location</CODE></A> directive.
38138d28 1348
04d756fc 1349<!-- NEED 3in -->
1350<H3><A NAME="AutoPurgeJobs">AutoPurgeJobs</A></H3>
1351<HR>
1352
1353<H4>Examples</H4>
1354
1355<UL><PRE>
1356AutoPurgeJobs Yes
1357AutoPurgeJobs No
1358</PRE></UL>
1359
1360<H4>Description</H4>
1361
1362<P>The <CODE>AutoPurgeJobs</CODE> directive specifies whether or not to purge
1363completed jobs once they are no longer required for quotas. This option has
1364no effect if quotas are not enabled. The default setting is <CODE>No</CODE>.
1365
fd7cc15d 1366<!-- NEED 5in -->
e75387bc 1367<H3><A NAME="BrowseAddress">BrowseAddress</A></H3>
1368<HR>
38138d28 1369
e75387bc 1370<H4>Examples</H4>
38138d28 1371
e75387bc 1372<UL><PRE>
1373BrowseAddress 255.255.255.255:631
1374BrowseAddress 192.0.2.255:631
fd7cc15d 1375BrowseAddress host.domain.com:631
9cfa8573 1376BrowseAddress @LOCAL
1377BrowseAddress @IF(name)
e75387bc 1378</PRE></UL>
38138d28 1379
e75387bc 1380<H4>Description</H4>
38138d28 1381
e75387bc 1382<P>The <CODE>BrowseAddress</CODE> directive specifies an address to
1383send browsing information to. Multiple <CODE>BrowseAddress</CODE>
1384directives can be specified to send browsing information to different
1385networks or systems.
38138d28 1386
9cfa8573 1387<P>The <CODE>@LOCAL</CODE> name will broadcast printer
1388information to all local interfaces. The <CODE>@IF(name)</CODE>
1389name will broadcast to the named interface.
1390
1391<P>No browse addresses are set by default.</P>
38138d28 1392
fd7cc15d 1393<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
1394<TR>
1395 <TD>
e75387bc 1396 <B>NOTE:</B>
38138d28 1397
e75387bc 1398 <P>If you are using HP-UX 10.20 and a subnet that is not 24,
1399 16, or 8 bits, printer browsing (and in fact all broadcast
1400 reception) will not work. This problem appears to be fixed in
1401 HP-UX 11.0.
fd7cc15d 1402 </TD>
1403</TR>
1404</TABLE></CENTER>
38138d28 1405
fd7cc15d 1406<!-- NEED 4in -->
e75387bc 1407<H3><A NAME="BrowseAllow">BrowseAllow</A></H3>
1408<HR>
9da2dc55 1409
e75387bc 1410<H4>Examples</H4>
9da2dc55 1411
1412<UL><PRE>
e75387bc 1413BrowseAllow from all
1414BrowseAllow from none
1415BrowseAllow from 192.0.2
1416BrowseAllow from 192.0.2.0/24
1417BrowseAllow from 192.0.2.0/255.255.255.0
1418BrowseAllow from *.domain.com
9cfa8573 1419BrowseAllow from @LOCAL
1420BrowseAllow from @IF(name)
9da2dc55 1421</PRE></UL>
1422
e75387bc 1423<H4>Description</H4>
9da2dc55 1424
e75387bc 1425<P>The <CODE>BrowseAllow</CODE> directive specifies a system or network
1426to accept browse packets from. The default is to accept browse packets
1427from all hosts.
9da2dc55 1428
fd7cc15d 1429<P>Host and domain name matching require that you enable the
e75387bc 1430<A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A> directive.
9da2dc55 1431
e75387bc 1432<P>IP address matching supports exact matches, partial addresses that
1433match networks using netmasks of 255.0.0.0, 255.255.0.0, and 255.255.255.0,
1434or network addresses using the specified netmask or bit count.
38138d28 1435
9cfa8573 1436<P>The <CODE>@LOCAL</CODE> name will allow browse data from all
1437local network interfaces, but not remote point-to-point
1438interfaces. The <CODE>@IF(name)</CODE> name will allow browse
1439data from the named interface.
1440
1441
fd7cc15d 1442<!-- NEED 4in -->
e75387bc 1443<H3><A NAME="BrowseDeny">BrowseDeny</A></H3>
1444<HR>
38138d28 1445
e75387bc 1446<H4>Examples</H4>
38138d28 1447
e75387bc 1448<UL><PRE>
1449BrowseDeny from all
1450BrowseDeny from none
1451BrowseDeny from 192.0.2
1452BrowseDeny from 192.0.2.0/24
1453BrowseDeny from 192.0.2.0/255.255.255.0
1454BrowseDeny from *.domain.com
9cfa8573 1455BrowseDeny from @LOCAL
1456BrowseDeny from @IF(name)
e75387bc 1457</PRE></UL>
38138d28 1458
e75387bc 1459<H4>Description</H4>
38138d28 1460
e75387bc 1461<P>The <CODE>BrowseDeny</CODE> directive specifies a system or network
1462to reject browse packets from. The default is to deny browse packets
1463from no hosts.
38138d28 1464
fd7cc15d 1465<P>Host and domain name matching require that you enable the
e75387bc 1466<A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A> directive.
38138d28 1467
e75387bc 1468<P>IP address matching supports exact matches, partial addresses that
1469match networks using netmasks of 255.0.0.0, 255.255.0.0, and 255.255.255.0,
1470or network addresses using the specified netmask or bit count.
38138d28 1471
9cfa8573 1472<P>The <CODE>@LOCAL</CODE> name will block browse data from all
1473local network interfaces, but not remote point-to-point
1474interfaces. The <CODE>@IF(name)</CODE> name will block browse
1475data from the named interface.
1476
1477
e75387bc 1478<!-- NEED 3in -->
1479<H3><A NAME="BrowseOrder">BrowseOrder</A></H3>
1480<HR>
38138d28 1481
e75387bc 1482<H4>Examples</H4>
38138d28 1483
e75387bc 1484<UL><PRE>
1485BrowseOrder allow,deny
1486BrowseOrder deny,allow
1487</PRE></UL>
38138d28 1488
e75387bc 1489<H4>Description</H4>
38138d28 1490
e75387bc 1491<P>The <CODE>BrowseOrder</CODE> directive specifies the order of allow/deny
1492processing. The default order is <CODE>deny,allow</CODE>:
38138d28 1493
e75387bc 1494<UL>
38138d28 1495
e75387bc 1496 <LI><CODE>allow,deny</CODE> - Browse packets are accepted unless
1497 specifically denied.
38138d28 1498
e75387bc 1499 <LI><CODE>deny,allow</CODE> - Browse packets are rejected unless
1500 specifically allowed.
38138d28 1501
e75387bc 1502</UL>
38138d28 1503
e75387bc 1504<!-- NEED 3in -->
1505<H3><A NAME="BrowseInterval">BrowseInterval</A></H3>
1506<HR>
38138d28 1507
e75387bc 1508<H4>Examples</H4>
38138d28 1509
e75387bc 1510<UL><PRE>
1511BrowseInterval 0
1512BrowseInterval 30
1513</PRE></UL>
38138d28 1514
e75387bc 1515<H4>Description</H4>
38138d28 1516
e75387bc 1517<P>The <CODE>BrowseInterval</CODE> directive specifies the maximum amount of
1518time between browsing updates. Specifying a value of 0 seconds disables
1519outgoing browse updates but allows a server to receive printer information
1520from other hosts.
38138d28 1521
e75387bc 1522<P>The <CODE>BrowseInterval</CODE> value should always be less than the
1523<A HREF="#BrowseTimeout"><CODE>BrowseTimeout</CODE></A> value. Otherwise
1524printers and classes will disappear from client systems between updates.
38138d28 1525
e75387bc 1526<!-- NEED 3in -->
1527<H3><A NAME="BrowsePoll">BrowsePoll</A></H3>
1528<HR>
38138d28 1529
e75387bc 1530<H4>Examples</H4>
6a921799 1531
e75387bc 1532<UL><PRE>
1533BrowsePoll 192.0.2.2:631
1534BrowsePoll host.domain.com:631
1535</PRE></UL>
e15022a6 1536
e75387bc 1537<H4>Description</H4>
e15022a6 1538
e75387bc 1539<P>The <CODE>BrowsePoll</CODE> directive polls a server for available
1540printers once every
1541<A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A> seconds.
1542Multiple <CODE>BrowsePoll</CODE> directives can be specified to poll
1543multiple servers.
e15022a6 1544
e75387bc 1545<P>If <CODE>BrowseInterval</CODE> is set to 0 then the server is polled
1546once every 30 seconds.
e15022a6 1547
e75387bc 1548<!-- NEED 3in -->
1549<H3><A NAME="BrowsePort">BrowsePort</A></H3>
1550<HR>
e15022a6 1551
e75387bc 1552<H4>Examples</H4>
e15022a6 1553
1554<UL><PRE>
e75387bc 1555BrowsePort 631
1556BrowsePort 9999
e15022a6 1557</PRE></UL>
1558
e75387bc 1559<H4>Description</H4>
38138d28 1560
e75387bc 1561<P>The <CODE>BrowsePort</CODE> directive specifies the UDP port number
9cfa8573 1562used for browse packets. The default port number is 631.</P>
38138d28 1563
fd7cc15d 1564<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
1565<TR>
1566 <TD>
e75387bc 1567 <B>NOTE:</B>
38138d28 1568
e75387bc 1569 <P>You must set the <CODE>BrowsePort</CODE> to the same value
1570 on all of the systems that you want to see.
fd7cc15d 1571 </TD>
1572</TR>
1573</TABLE></CENTER>
38138d28 1574
753453e4 1575<!-- NEED 3in -->
1576<H3><A NAME="BrowseProtocols">BrowseProtocols</A></H3>
1577<HR>
1578
1579<H4>Examples</H4>
1580
1581<UL><PRE>
1582BrowseProtocols CUPS
1583BrowseProtocols SLP
1584BrowseProtocols CUPS SLP
1585BrowseProtocols all
1586</PRE></UL>
1587
1588<H4>Description</H4>
1589
1590<P>The <CODE>BrowseProtocols</CODE> directive specifies the protocols to
1591use when collecting and distributing shared printers on the local network.
1592The default protocol is <CODE>CUPS</CODE>, which is a broadcast-based
9cfa8573 1593protocol.</P>
753453e4 1594
1595<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
1596<TR>
1597 <TD>
1598 <B>NOTE:</B>
1599
1600 <P>When using the <CODE>SLP</CODE> protocol, you must have at least
1601 one Directory Agent (DA) server on your network. Otherwise the
1602 CUPS scheduler (<CODE>cupsd</CODE>) will not respond to client
1603 requests for several seconds while polling the network.
1604 </TD>
1605</TR>
1606</TABLE></CENTER>
1607
fd7cc15d 1608<!-- NEED 4in -->
e75387bc 1609<H3><A NAME="BrowseRelay">BrowseRelay</A></H3>
1610<HR>
38138d28 1611
e75387bc 1612<H4>Examples</H4>
38138d28 1613
e75387bc 1614<UL><PRE>
1615BrowseRelay 193.0.2.1 192.0.2.255
1616BrowseRelay 193.0.2.0/255.255.255.0 192.0.2.255
1617BrowseRelay 193.0.2.0/24 192.0.2.255
1618BrowseRelay *.domain.com 192.0.2.255
1619BrowseRelay host.domain.com 192.0.2.255
1620</PRE></UL>
38138d28 1621
e75387bc 1622<H4>Description</H4>
38138d28 1623
e75387bc 1624<P>The <CODE>BrowseRelay</CODE> directive specifies source and destination
1625addresses for relaying browsing information from one host or network to
1626another. Multiple <CODE>BrowseRelay</CODE> directives can be specified
1627as needed.
38138d28 1628
e75387bc 1629<P><CODE>BrowseRelay</CODE> is typically used on systems that bridge
1630multiple subnets using one or more network interfaces. It can also be
1631used to relay printer information from polled servers with the line:
38138d28 1632
e75387bc 1633<UL><PRE>
1634BrowseRelay 127.0.0.1 255.255.255.255
1635</PRE></UL>
38138d28 1636
e75387bc 1637<P>This effectively provides access to printers on a WAN for all clients
fd7cc15d 1638on the LAN(s).
38138d28 1639
6380867c 1640<!-- NEED 3in -->
1641<H3><A NAME="BrowseShortNames">BrowseShortNames</A></H3>
1642<HR>
1643
1644<H4>Examples</H4>
1645
1646<UL><PRE>
1647BrowseShortNames Yes
1648BrowseShortNames No
1649</PRE></UL>
1650
1651<H4>Description</H4>
1652
1653<P>The <CODE>BrowseShortNames</CODE> directive specifies whether or not
1654short names are used for remote printers when possible. Short names are
1655just the remote printer name, without the server ("printer"). If more than
1656one remote printer is detected with the same name, the printers will have
1657long names ("printer@server1", "printer@server2".)
1658
1659<P>The default value for this option is <CODE>Yes</CODE>.
1660
e75387bc 1661<!-- NEED 3in -->
1662<H3><A NAME="BrowseTimeout">BrowseTimeout</A></H3>
1663<HR>
38138d28 1664
e75387bc 1665<H4>Examples</H4>
38138d28 1666
e75387bc 1667<UL><PRE>
1668BrowseTimeout 300
1669BrowseTimeout 60
1670</PRE></UL>
38138d28 1671
e75387bc 1672<H4>Description</H4>
e15022a6 1673
e75387bc 1674<P>The <CODE>BrowseTimeout</CODE> directive sets the timeout for
1675printer or class information that is received in browse packets. Once a
1676printer or class times out it is removed from the list of available
1677destinations.
e15022a6 1678
e75387bc 1679<P>The <CODE>BrowseTimeout</CODE> value should always be greater than the
1680<A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A> value. Otherwise
1681printers and classes will disappear from client systems between updates.
e15022a6 1682
551d3a88 1683<!-- NEED 4in -->
e75387bc 1684<H3><A NAME="Browsing">Browsing</A></H3>
1685<HR>
e15022a6 1686
e75387bc 1687<H4>Examples</H4>
e15022a6 1688
e75387bc 1689<UL><PRE>
1690Browsing On
1691Browsing Off
1692</PRE></UL>
e15022a6 1693
e75387bc 1694<H4>Description</H4>
e15022a6 1695
e75387bc 1696<P>The <CODE>Browsing</CODE> directive controls whether or not network printer
9cfa8573 1697browsing is enabled. The default setting is <CODE>On</CODE>.</P>
e15022a6 1698
fd7cc15d 1699<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
1700<TR>
1701 <TD>
e15022a6 1702 <B>NOTE:</B>
1703
1704 <P>If you are using HP-UX 10.20 and a subnet that is not 24,
1705 16, or 8 bits, printer browsing (and in fact all broadcast
1706 reception) will not work. This problem appears to be fixed in
1707 HP-UX 11.0.
fd7cc15d 1708 </TD>
1709</TR>
1710</TABLE></CENTER>
e15022a6 1711
d11458ff 1712<!-- NEED 3in -->
1713<H3><A NAME="Classification">Classification</A></H3>
1714<HR>
1715
1716<H4>Examples</H4>
1717
1718<UL><PRE>
1719Classification
1720Classification classified
1721Classification confidential
1722Classification secret
1723Classification topsecret
1724Classification unclassified
1725</PRE></UL>
1726
1727<H4>Description</H4>
1728
1729<P>The <CODE>Classification</CODE> directive sets the classification level
1730on the server. When this option is set, at least one of the banner pages
1731is forced to the classification level, and the classification is placed
1732on each page of output. The default is no classification level.
1733
753453e4 1734<!-- NEED 3in -->
1735<H3><A NAME="ClassifyOverride">ClassifyOverride</A></H3>
1736<HR>
1737
1738<H4>Examples</H4>
1739
1740<UL><PRE>
1741ClassifyOverride Yes
1742ClassifyOverride No
1743</PRE></UL>
1744
1745<H4>Description</H4>
1746
1747<P>The <CODE>ClassifyOverride</CODE> directive specifies whether users
1748can override the default classification level on the server. When the
1749server classification is set, users can change the classification using
1750the <CODE>job-sheets</CODE> option and can choose to only print one
1751security banner before or after the job. If the <CODE>job-sheets</CODE>
1752option is set to <CODE>none</CODE> then the server default classification
1753is used.
1754
1755<P>The default is to not allow classification overrides.
1756
9cfa8573 1757<!-- NEED 3in -->
1758<H3><A NAME="ConfigFilePerm">ConfigFilePerm</A></H3>
1759<HR>
1760
1761<H4>Examples</H4>
1762
1763<UL><PRE>
1764ConfigFilePerm 0644
1765ConfigFilePerm 0600
1766</PRE></UL>
1767
1768<H4>Description</H4>
1769
1770<P>The <CODE>ConfigFilePerm</CODE> directive specifies the permissions
1771to use when writing configuration files. The default is 0600.
1772
6380867c 1773<!-- NEED 3in -->
1774<H3><A NAME="DataDir">DataDir</A></H3>
1775<HR>
1776
1777<H4>Examples</H4>
1778
1779<UL><PRE>
1780DataDir /usr/share/cups
1781</PRE></UL>
1782
1783<H4>Description</H4>
1784
1785<P>The <CODE>DataDir</CODE> directive sets the directory to use for data
1786files.
1787
e75387bc 1788<!-- NEED 3in -->
1789<H3><A NAME="DefaultCharset">DefaultCharset</A></H3>
1790<HR>
e15022a6 1791
e75387bc 1792<H4>Examples</H4>
e15022a6 1793
1794<UL><PRE>
e75387bc 1795DefaultCharset utf-8
1796DefaultCharset iso-8859-1
1797DefaultCharset windows-1251
e15022a6 1798</PRE></UL>
1799
e75387bc 1800<H4>Description</H4>
ba8a42d9 1801
e75387bc 1802<P>The <CODE>DefaultCharset</CODE> directive sets the default character set
1803to use for client connections. The default character set is
1804<CODE>utf-8</CODE> but is overridden by the character set for the language
1805specified by the client or the <CODE>DefaultLanguage</CODE> directive.
e15022a6 1806
e75387bc 1807<!-- NEED 3in -->
1808<H3><A NAME="DefaultLanguage">DefaultLanguage</A></H3>
1809<HR>
e15022a6 1810
e75387bc 1811<H4>Examples</H4>
e15022a6 1812
1813<UL><PRE>
e75387bc 1814DefaultLanguage de
1815DefaultLanguage en
1816DefaultLanguage es
1817DefaultLanguage fr
1818DefaultLanguage it
e15022a6 1819</PRE></UL>
1820
e75387bc 1821<H4>Description</H4>
e15022a6 1822
e75387bc 1823<P>The <CODE>DefaultLanguage</CODE> directive specifies the default language
1824to use for client connections. Setting the default language also sets the
1825default character set if a language localization file exists for it. The
1826default language is "en" for English.
e15022a6 1827
fd7cc15d 1828<!-- NEED 5in -->
e75387bc 1829<H3><A NAME="Deny">Deny</A></H3>
1830<HR>
e15022a6 1831
e75387bc 1832<H4>Examples</H4>
e15022a6 1833
1834<UL><PRE>
1835Deny from All
1836Deny from None
1837Deny from *.domain.com
1838Deny from .domain.com
1839Deny from host.domain.com
1840Deny from nnn.*
1841Deny from nnn.nnn.*
1842Deny from nnn.nnn.nnn.*
1843Deny from nnn.nnn.nnn.nnn
1844Deny from nnn.nnn.nnn.nnn/mm
1845Deny from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
9cfa8573 1846Deny from @LOCAL
1847Deny from @IF(name)
e15022a6 1848</PRE></UL>
1849
e75387bc 1850<H4>Description</H4>
1851
1852<P>The <CODE>Deny</CODE> directive specifies a hostname, IP address, or
1853network that is allowed access to the server. <CODE>Deny</CODE>
1854directives are cummulative, so multiple <CODE>Deny</CODE> directives
1855can be used to allow access for multiple hosts or networks. The
ea0c2f2f 1856<CODE>/mm</CODE> notation specifies a CIDR netmask:
1857
766ec9c5 1858<CENTER><TABLE BORDER="1">
ea0c2f2f 1859<TR>
fd7cc15d 1860 <TH WIDTH="10%">mm</TH>
1861 <TH WIDTH="20%">netmask</TH>
1862 <TH WIDTH="10%">mm</TH>
1863 <TH WIDTH="20%">netmask</TH>
ea0c2f2f 1864</TR>
1865<TR>
fd7cc15d 1866 <TD ALIGN="CENTER">0</TD>
1867 <TD ALIGN="CENTER">0.0.0.0</TD>
1868 <TD ALIGN="CENTER">8</TD>
1869 <TD ALIGN="CENTER">255.0.0.0</TD>
ea0c2f2f 1870</TR>
1871<TR>
fd7cc15d 1872 <TD ALIGN="CENTER">1</TD>
1873 <TD ALIGN="CENTER">128.0.0.0</TD>
1874 <TD ALIGN="CENTER">16</TD>
1875 <TD ALIGN="CENTER">255.255.0.0</TD>
ea0c2f2f 1876</TR>
1877<TR>
fd7cc15d 1878 <TD ALIGN="CENTER">2</TD>
1879 <TD ALIGN="CENTER">192.0.0.0</TD>
1880 <TD ALIGN="CENTER">24</TD>
1881 <TD ALIGN="CENTER">255.255.255.0</TD>
ea0c2f2f 1882</TR>
1883<TR>
fd7cc15d 1884 <TD ALIGN="CENTER">...</TD>
1885 <TD ALIGN="CENTER">...</TD>
1886 <TD ALIGN="CENTER">32</TD>
1887 <TD ALIGN="CENTER">255.255.255.255</TD>
ea0c2f2f 1888</TR>
1889</TABLE></CENTER>
e15022a6 1890
9cfa8573 1891<P>The <CODE>@LOCAL</CODE> name will deny access from all local
1892network interfaces, but not remote point-to-point interfaces. The
1893<CODE>@IF(name)</CODE> name will deny access from the named
1894interface.
1895
e15022a6 1896<P>The <CODE>Deny</CODE> directive must appear inside a
e75387bc 1897<A HREF="#Location"><CODE>Location</CODE></A> directive.
e15022a6 1898
e75387bc 1899<!-- NEED 3in -->
1900<H3><A NAME="DocumentRoot">DocumentRoot</A></H3>
1901<HR>
e15022a6 1902
e75387bc 1903<H4>Examples</H4>
e15022a6 1904
e75387bc 1905<UL><PRE>
1906DocumentRoot /usr/share/doc/cups
1907DocumentRoot /foo/bar/doc/cups
1908</PRE></UL>
e15022a6 1909
e75387bc 1910<H4>Description</H4>
250b9cef 1911
e75387bc 1912<P>The <CODE>DocumentRoot</CODE> directive specifies the location of
1913web content for the HTTP server in CUPS. If an absolute path is not
1914specified then it is assumed to be relative to the
1915<A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
1916default directory is <VAR>/usr/share/doc/cups</VAR>.
e15022a6 1917
e75387bc 1918<P>Documents are first looked up in a sub-directory for the primary
1919language requested by the client (e.g. <VAR>/usr/share/doc/cups/fr/...</VAR>)
1920and then directly under the <CODE>DocumentRoot</CODE> directory
1921(e.g. <VAR>/usr/share/doc/cups/...</VAR>), so it is possible to localize
1922the web content by providing subdirectories for each language needed.
e15022a6 1923
b1d503b0 1924<!-- NEED 3in -->
1925<H3><A NAME="Encryption">Encryption</A></H3>
1926<HR>
1927
1928<H4>Examples</H4>
1929
1930<UL><PRE>
1931Encryption Never
1932Encryption IfRequested
1933Encryption Required
1934Encryption Always
1935</PRE></UL>
1936
1937<H4>Description</H4>
1938
1939<P>The <CODE>Encryption</CODE> directive must appear instead a
1940<A HREF="#Location"><CODE>Location</CODE></A>
1941section and specifies the encryption settings for that location.
1942The default setting is <CODE>IfRequested</CODE> for all locations.
1943
e75387bc 1944<!-- NEED 3in -->
551d3a88 1945<H3><A NAME="ErrorLog">ErrorLog</A></H3>
e75387bc 1946<HR>
e15022a6 1947
e75387bc 1948<H4>Examples</H4>
e15022a6 1949
e75387bc 1950<UL><PRE>
1951ErrorLog /var/log/cups/error_log
6380867c 1952ErrorLog /var/log/cups/error_log-%s
e75387bc 1953ErrorLog syslog
1954</PRE></UL>
e15022a6 1955
e75387bc 1956<H4>Description</H4>
e15022a6 1957
e75387bc 1958<P>The <CODE>ErrorLog</CODE> directive sets the name of the error log
1959file. If the filename is not absolute then it is assumed to be relative
1960to the <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
1961default error log file is <VAR>/var/log/cups/error_log</VAR>.
e15022a6 1962
6380867c 1963<P>The server name can be included in the filename by using
1964<CODE>%s</CODE> in the name.
1965
551d3a88 1966<P>The special name "syslog" can be used to send the error information
1967to the system log instead of a plain file.
1968
d0a31f54 1969<!-- NEED 3in -->
1970<H3><A NAME="FilterLimit">FilterLimit</A></H3>
1971<HR>
1972
1973<H4>Examples</H4>
1974
1975<UL><PRE>
1976FilterLimit 0
1977FilterLimit 200
1978FilterLimit 1000
1979</PRE></UL>
1980
1981<H4>Description</H4>
1982
1983<P>The <CODE>FilterLimit</CODE> directive sets the maximum cost
1984of all running job filters. It can be used to limit the number
1985of filter programs that are run on a server to minimize disk,
1986memory, and CPU resource problems. A limit of 0 disables filter
1987limiting.
1988
1989<P>An average print to a non-PostScript printer needs a filter
1990limit of about 200. A PostScript printer needs about half that
1991(100). Setting the limit below these thresholds will effectively
1992limit the scheduler to printing a single job at any time.
1993
1994<P>The default limit is 0.
1995
9cfa8573 1996<!-- NEED 3in -->
1997<H3><A NAME="FilterNice">FilterNice</A></H3>
1998<HR>
1999
2000<H4>Examples</H4>
2001
2002<UL><PRE>
2003FilterNice 0
2004FilterNice 39
2005FilterNice -10
2006</PRE></UL>
2007
2008<H4>Description</H4>
2009
2010<P>The <CODE>FilterNice</CODE> directive sets the scheduling
2011priority of job filters. Values larger than 0 give filters a
2012lower priority while values smaller than 0 give filters a higher
2013priority. The <CODE>FilterNice</CODE> value does not affect the
2014priority of job backends.
2015
2016<P>The default priority is 0.
2017
b1d503b0 2018<!-- NEED 3in -->
2019<H3><A NAME="FontPath">FontPath</A></H3>
2020<HR>
2021
2022<H4>Examples</H4>
2023
2024<UL><PRE>
2025FontPath /foo/bar/fonts
2026FontPath /usr/share/cups/fonts:/foo/bar/fonts
2027</PRE></UL>
2028
2029<H4>Description</H4>
2030
2031<P>The <CODE>FontPath</CODE> directive specifies the font path to use when
2032searching for fonts. The default font path is
2033<CODE>/usr/share/cups/fonts</CODE>.
2034
e75387bc 2035<!-- NEED 3in -->
2036<H3><A NAME="Group">Group</A></H3>
2037<HR>
e15022a6 2038
e75387bc 2039<H4>Examples</H4>
e15022a6 2040
e75387bc 2041<UL><PRE>
2042Group sys
2043Group system
2044Group root
2045</PRE></UL>
e15022a6 2046
e75387bc 2047<H4>Description</H4>
e15022a6 2048
e75387bc 2049<P>The <CODE>Group</CODE> directive specifies the UNIX group that
2050filter and CGI programs run as. The default group is <CODE>sys</CODE>,
2051<CODE>system</CODE>, or <CODE>root</CODE> depending on the operating
2052system.
e15022a6 2053
753453e4 2054<!-- NEED 3in -->
2055<H3><A NAME="HideImplicitMembers">HideImplicitMembers</A></H3>
2056<HR>
2057
2058<H4>Examples</H4>
2059
2060<UL><PRE>
2061HideImplicitMembers Yes
2062HideImplicitMembers No
2063</PRE></UL>
2064
2065<H4>Description</H4>
2066
2067<P>The <CODE>HideImplicitMembers</CODE> directive controls
2068whether the individual printers in an implicit class are shown
2069to the user. The default is <CODE>No</CODE>.</P>
2070
2071<P><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
2072must be enabled for this directive to have any effect.</P>
2073
e75387bc 2074<!-- NEED 3in -->
2075<H3><A NAME="HostNameLookups">HostNameLookups</A></H3>
2076<HR>
e15022a6 2077
e75387bc 2078<H4>Examples</H4>
e15022a6 2079
e75387bc 2080<UL><PRE>
2081HostNameLookups On
2082HostNameLookups Off
b1d503b0 2083HostNameLookups Double
e75387bc 2084</PRE></UL>
e15022a6 2085
e75387bc 2086<H4>Description</H4>
e15022a6 2087
b1d503b0 2088<P>The <CODE>HostNameLookups</CODE> directive controls whether
2089or not CUPS looks up the hostname for connecting clients. The
2090<CODE>Double</CODE> setting causes CUPS to verify that the
2091hostname resolved from the address matches one of the addresses
2092returned for that hostname. <CODE>Double</CODE> lookups also
2093prevent clients with unregistered addresses from connecting
2094to your server.
2095
2096The default is <CODE>Off</CODE> to avoid the potential server
2097performance problems with hostname lookups. Set this option to
2098<CODE>On</CODE> or <CODE>Double</CODE> only if absolutely
2099required.
e15022a6 2100
e75387bc 2101<!-- NEED 3in -->
2102<H3><A NAME="ImplicitClasses">ImplicitClasses</A></H3>
2103<HR>
e15022a6 2104
e75387bc 2105<H4>Examples</H4>
e15022a6 2106
2107<UL><PRE>
e75387bc 2108ImplicitClasses On
2109ImplicitClasses Off
e15022a6 2110</PRE></UL>
2111
e75387bc 2112<H4>Description</H4>
e15022a6 2113
e75387bc 2114<P>The <CODE>ImplicitClasses</CODE> directive controls whether implicit
2115classes are created based upon the available network printers and classes.
2116The default setting is <CODE>On</CODE> but is automatically turned
2117<CODE>Off</CODE> if <A HREF="#Browsing"><CODE>Browsing</CODE></A> is
2118turned <CODE>Off</CODE>.
e15022a6 2119
753453e4 2120<!-- NEED 3in -->
2121<H3><A NAME="ImplicitAnyClasses">ImplicitAnyClasses</A></H3>
2122<HR>
2123
2124<H4>Examples</H4>
2125
2126<UL><PRE>
2127ImplicitAnyClasses On
2128ImplicitAnyClasses Off
2129</PRE></UL>
2130
2131<H4>Description</H4>
2132
2133<P>The <CODE>ImplicitAnyClasses</CODE> directive controls
2134whether implicit classes for local and remote printers are
2135created with the name <CODE>AnyPrinter</CODE>. The default
2136setting is <CODE>Off</CODE>.</P>
2137
2138<P><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
2139must be enabled for this directive to have any effect.</P>
2140
2141<!-- NEED 3in -->
2142<H3><A NAME="Include">Include</A></H3>
2143<HR>
2144
2145<H4>Examples</H4>
2146
2147<UL><PRE>
2148Include filename
2149Include /foo/bar/filename
2150</PRE></UL>
2151
2152<H4>Description</H4>
2153
2154<P>The <CODE>Include</CODE> directive includes the named file in
2155the <CODE>cupsd.conf</CODE> file. If no leading path is
2156provided, the file is assumed to be relative to the
2157<A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory.</P>
2158
e75387bc 2159<!-- NEED 3in -->
2160<H3><A NAME="KeepAlive">KeepAlive</A></H3>
2161<HR>
e15022a6 2162
e75387bc 2163<H4>Examples</H4>
e15022a6 2164
e75387bc 2165<UL><PRE>
2166KeepAlive On
2167KeepAlive Off
2168</PRE></UL>
e15022a6 2169
e75387bc 2170<H4>Description</H4>
e15022a6 2171
e75387bc 2172<P>The <CODE>KeepAlive</CODE> directive controls whether or not to support
2173persistent HTTP connections. The default is <CODE>On</CODE>.
e15022a6 2174
e75387bc 2175<P>HTTP/1.1 clients automatically support persistent connections, while
2176HTTP/1.0 clients must specifically request them using the
2177<CODE>Keep-Alive</CODE> attribute in the <CODE>Connection:</CODE>
2178field of each request.
e15022a6 2179
e75387bc 2180<!-- NEED 3in -->
2181<H3><A NAME="KeepAliveTimeout">KeepAliveTimeout</A></H3>
2182<HR>
e15022a6 2183
e75387bc 2184<H4>Examples</H4>
e15022a6 2185
e75387bc 2186<UL><PRE>
2187KeepAliveTimeout 60
2188KeepAliveTimeout 30
2189</PRE></UL>
e15022a6 2190
e75387bc 2191<H4>Description</H4>
e15022a6 2192
e75387bc 2193<P>The <CODE>KeepAliveTimeout</CODE> directive controls how long a
2194persistent HTTP connection will remain open after the last request. The
2195default is 60 seconds.
e15022a6 2196
b1d503b0 2197<!-- NEED 3in -->
2198<H3><A NAME="Limit">Limit</A></H3>
2199<HR>
2200
2201<H4>Examples</H4>
2202
2203<UL><PRE>
2204&lt;Limit GET POST&gt;
2205...
2206&lt;/Limit&gt;
2207
2208&lt;Limit ALL&gt;
2209...
2210&lt;/Limit&gt;
2211</PRE></UL>
2212
2213<H4>Description</H4>
2214
2215<P>The <CODE>Limit</CODE> directive groups access control directives for
2216specific types of HTTP requests and must appear inside a
2217<A HREF="#Location"><CODE>Location</CODE></A> section. Access can be limited
2218for individual request types (<CODE>DELETE</CODE>, <CODE>GET</CODE>,
2219<CODE>HEAD</CODE>, <CODE>OPTIONS</CODE>, <CODE>POST</CODE>, <CODE>PUT</CODE>,
2220and <CODE>TRACE</CODE>) or for all request types (<CODE>ALL</CODE>). The
2221request type names are case-sensitive for compatibility with Apache.
2222
2223<!-- NEED 3in -->
2224<H3><A NAME="LimitExcept">LimitExcept</A></H3>
2225<HR>
2226
2227<H4>Examples</H4>
2228
2229<UL><PRE>
2230&lt;LimitExcept GET POST&gt;
2231...
2232&lt;/LimitExcept&gt;
2233</PRE></UL>
2234
2235<H4>Description</H4>
2236
2237<P>The <CODE>LimitExcept</CODE> directive groups access control directives for
2238specific types of HTTP requests and must appear inside a
2239<A HREF="#Location"><CODE>Location</CODE></A> section. Unlike the
2240<A HREF="#Limit"><CODE>Limit</CODE></A> directive, <CODE>LimitExcept</CODE>
2241restricts access for all requests <I>except</I> those listed on the
2242<CODE>LimitExcept</CODE> line.
2243
2244<!-- NEED 3in -->
2245<H3><A NAME="LimitRequestBody">LimitRequestBody</A></H3>
2246<HR>
2247
2248<H4>Examples</H4>
2249
2250<UL><PRE>
2251LimitRequestBody 10485760
2252LimitRequestBody 10m
2253LimitRequestBody 0
2254</PRE></UL>
2255
2256<H4>Description</H4>
2257
2258<P>The <CODE>LimitRequestBody</CODE> directive controls the maximum size of
2259print files, IPP requests, and HTML form data in HTTP POST requests. The
2260default limit is 0 which disables the limit check.
2261
2262<P>Also see the identical
2263<A HREF="#MaxRequestSize"><CODE>MaxRequestSize</CODE></A> directive.
2264
e75387bc 2265<!-- NEED 3in -->
2266<H3><A NAME="Listen">Listen</A></H3>
2267<HR>
2f89d155 2268
e75387bc 2269<H4>Examples</H4>
e15022a6 2270
e75387bc 2271<UL><PRE>
2272Listen 127.0.0.1:631
2273Listen 192.0.2.1:631
2274</PRE></UL>
e15022a6 2275
e75387bc 2276<H4>Description</H4>
e15022a6 2277
e75387bc 2278<P>The <CODE>Listen</CODE> directive specifies a network address and port
2279to listen for connections. Multiple <CODE>Listen</CODE> directives can be
2280provided to listen on multiple addresses.
e15022a6 2281
e75387bc 2282<P>The <CODE>Listen</CODE> directive is similar to the
2283<A HREF="#Port"><CODE>Port</CODE></A> directive but allows you to restrict
2284access to specific interfaces or networks.
e15022a6 2285
e75387bc 2286<!-- NEED 3in -->
2287<H3><A NAME="Location">Location</A></H3>
2288<HR>
2289
2290<H4>Examples</H4>
e15022a6 2291
2292<UL><PRE>
e75387bc 2293&lt;Location /&gt;
2294...
2295&lt;/Location&gt;
e15022a6 2296
e75387bc 2297&lt;Location /admin&gt;
2298...
2299&lt;/Location&gt;
2300
9cfa8573 2301&lt;Location /printers&gt;
2302...
2303&lt;/Location&gt;
2304
e75387bc 2305&lt;Location /printers/name&gt;
2306...
2307&lt;/Location&gt;
9cfa8573 2308
2309&lt;Location /classes&gt;
2310...
2311&lt;/Location&gt;
2312
2313&lt;Location /classes/name&gt;
2314...
2315&lt;/Location&gt;
e15022a6 2316</PRE></UL>
2317
e75387bc 2318<H4>Description</H4>
e15022a6 2319
e75387bc 2320<P>The <CODE>Location</CODE> directive specifies access control and
9cfa8573 2321authentication options for the specified HTTP resource or path.
2322The
2323<A HREF="#Allow"><CODE>Allow</CODE></A>,
2324<A HREF="#AuthClass"><CODE>AuthClass</CODE></A>,
2325<A HREF="#AuthGroupName"><CODE>AuthGroupName</CODE></A>,
2326<A HREF="#AuthType"><CODE>AuthType</CODE></A>,
2327<A HREF="#Deny"><CODE>Deny</CODE></A>,
2328<A HREF="#Encryption"><CODE>Encryption</CODE></A>,
2329<A HREF="#Limit"><CODE>Limit</CODE></A>,
2330<A HREF="#LimitExcept"><CODE>LimitExcept</CODE></A>,
2331<A HREF="#Order"><CODE>Order</CODE></A>,
2332<A HREF="#Require"><CODE>Require</CODE></A>, and
2333<A HREF="#Satisfy"><CODE>Satisfy</CODE></A>
2334directives may all appear inside a location.
2335
2336<CENTER><TABLE BORDER="1"><CAPTION>Locations on the Server.</CAPTION>
2337<TR><TH>Location</TH><TH>Description</TH></TR>
2338<TR><TD>/</TD><TD>The path for all get operations (get-printers, get-jobs, etc.)</TD></TR>
2339<TR><TD>/admin</TD><TD>The path for all administration operations (add-printer, delete-printer, start-printer, etc.)</TD></TR>
2340<TR><TD>/admin/conf</TD><TD>The path for access to the ESP Print Pro configuration files (cupsd.conf, client.conf, etc.)</TD></TR>
2341<TR><TD>/classes</TD><TD>The path for all classes</TD></TR>
2342<TR><TD>/classes/name</TD><TD>The resource for class <CODE>name</CODE></TD></TR>
2343<TR><TD>/jobs</TD><TD>The path for all jobs (hold-job, release-job, etc.)</TD></TR>
2344<TR><TD>/jobs/id</TD><TD>The resource for job <CODE>id</CODE></TD></TR>
2345<TR><TD>/printers</TD><TD>The path for all printers</TD></TR>
2346<TR><TD>/printers/name</TD><TD>The path for printer <CODE>name</CODE></TD></TR>
2347<TR><TD>/printers/name.ppd</TD><TD>The PPD file path for printer <CODE>name</CODE></TD></TR>
2348</TABLE></CENTER>
2349
2350<P>Note that more specific resources override the less specific ones.
2351So the directives inside the <CODE>/printers/name</CODE> location will override ones from <CODE>/printers</CODE>.
2352Directives inside <CODE>/printers</CODE> will override ones from <CODE>/</CODE>. &nbsp;
2353None of the directives are inherited.
2354More information can be found in section <A HREF="#PRINTING_SECURITY">"Printing System Security"</A>.
2355
2356<!-- NEED 3in -->
2357<H3><A NAME="LogFilePerm">LogFilePerm</A></H3>
2358<HR>
2359
2360<H4>Examples</H4>
2361
2362<UL><PRE>
2363LogFilePerm 0644
2364LogFilePerm 0600
2365</PRE></UL>
2366
2367<H4>Description</H4>
2368
2369<P>The <CODE>LogFilePerm</CODE> directive specifies the permissions
2370to use when writing configuration files. The default is 0644.
e15022a6 2371
e75387bc 2372<!-- NEED 3in -->
2373<H3><A NAME="LogLevel">LogLevel</A></H3>
2374<HR>
e15022a6 2375
e75387bc 2376<H4>Examples</H4>
e15022a6 2377
2378<UL><PRE>
e75387bc 2379LogLevel none
b1d503b0 2380LogLevel emerg
2381LogLevel alert
2382LogLevel crit
2383LogLevel error
e75387bc 2384LogLevel warn
b1d503b0 2385LogLevel notice
2386LogLevel info
2387LogLevel debug
2388LogLevel debug2
e15022a6 2389</PRE></UL>
2390
e75387bc 2391<H4>Description</H4>
e15022a6 2392
fd7cc15d 2393<P>The <CODE>LogLevel</CODE> directive specifies the level of logging
2394for the <A HREF="#ErrorLog"><CODE>ErrorLog</CODE></A> file. The
b1d503b0 2395following values are recognized (each level logs everything under the
2396preceding levels):
766ec9c5 2397
e75387bc 2398<UL>
766ec9c5 2399
b1d503b0 2400 <LI><CODE>none</CODE> - Log nothing.
2401
2402 <LI><CODE>emerg</CODE> - Log emergency conditions that prevent the
2403 server from running.
766ec9c5 2404
b1d503b0 2405 <LI><CODE>alert</CODE> - Log alerts that must be handled immediately.
2406
2407 <LI><CODE>crit</CODE> - Log critical errors that don't prevent
2408 the server from running.
2409
2410 <LI><CODE>error</CODE> - Log general errors.
766ec9c5 2411
e75387bc 2412 <LI><CODE>warn</CODE> - Log errors and warnings.
766ec9c5 2413
b1d503b0 2414 <LI><CODE>notice</CODE> - Log temporary error conditions.
766ec9c5 2415
b1d503b0 2416 <LI><CODE>info</CODE> - Log all requests and state changes (default).
2417
2418 <LI><CODE>debug</CODE> - Log basic debugging information.
2419
2420 <LI><CODE>debug2</CODE> - Log all debugging information.
766ec9c5 2421
e75387bc 2422</UL>
766ec9c5 2423
e75387bc 2424<!-- NEED 3in -->
2425<H3><A NAME="MaxClients">MaxClients</A></H3>
2426<HR>
766ec9c5 2427
e75387bc 2428<H4>Examples</H4>
766ec9c5 2429
e75387bc 2430<UL><PRE>
2431MaxClients 100
2432MaxClients 1024
2433</PRE></UL>
766ec9c5 2434
e75387bc 2435<H4>Description</H4>
766ec9c5 2436
e75387bc 2437<P>The <CODE>MaxClients</CODE> directive controls the maximum number of
2438simultaneous clients that will be allowed by the server. The default is
9cfa8573 2439100 clients.</P>
e75387bc 2440
fd7cc15d 2441<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
2442<TR>
2443 <TD>
2444 <B>NOTE:</B>
2445
2446 <P>Since each print job requires a file descriptor for the
2447 status pipe, the CUPS server internally limits the
2448 <CODE>MaxClients</CODE> value to 1/3 of the available file descriptors
2449 to avoid possible problems when printing large numbers of jobs.
2450 </TD>
2451</TR>
2452</TABLE></CENTER>
e75387bc 2453
2e9f3b68 2454<!-- NEED 3in -->
2455<H3><A NAME="MaxCopies">MaxCopies</A></H3>
2456<HR>
2457
2458<H4>Examples</H4>
2459
2460<UL><PRE>
2461MaxCopies 100
2462MaxCopies 65535
2463</PRE></UL>
2464
2465<H4>Description</H4>
2466
2467<P>The <CODE>MaxCopies</CODE> directive controls the maximum
2468number of copies that a user can print of a job. The default is
2469100 copies.</P>
2470
2471<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
2472<TR>
2473 <TD>
2474 <B>NOTE:</B>
2475
2476 <P>Most HP PCL laser printers internally limit the
2477 number of copies to 100.
2478
2479 </TD>
2480</TR>
2481</TABLE></CENTER>
2482
04d756fc 2483<!-- NEED 3in -->
2484<H3><A NAME="MaxJobs">MaxJobs</A></H3>
2485<HR>
2486
2487<H4>Examples</H4>
2488
2489<UL><PRE>
2490MaxJobs 100
2491MaxJobs 9999
2492MaxJobs 0
2493</PRE></UL>
2494
2495<H4>Description</H4>
2496
2497<P>The <CODE>MaxJobs</CODE> directive controls the maximum number of jobs
2498that are kept in memory. Once the number of jobs reaches the limit, the
2499oldest completed job is automatically purged from the system to make room
2500for the new one. If all of the known jobs are still pending or active then
2501the new job will be rejected.
2502
0e5b6226 2503<P>Setting the maximum to 0 disables this functionality. The default
2504setting is 0.
2505
2506<!-- NEED 3in -->
2507<H3><A NAME="MaxJobsPerPrinter">MaxJobsPerPrinter</A></H3>
2508<HR>
2509
2510<H4>Examples</H4>
2511
2512<UL><PRE>
2513MaxJobsPerPrinter 100
2514MaxJobsPerPrinter 9999
2515MaxJobsPerPrinter 0
2516</PRE></UL>
2517
2518<H4>Description</H4>
2519
2520<P>The <CODE>MaxJobsPerPrinter</CODE> directive controls the maximum number of active jobs
2521that are allowed for each printer or class. Once a printer or class reaches the limit, new jobs will be
2522rejected until one of the active jobs is completed, stopped, aborted, or cancelled.
2523
2524<P>Setting the maximum to 0 disables this functionality. The default
2525setting is 0.
2526
2527<!-- NEED 3in -->
2528<H3><A NAME="MaxJobsPerUser">MaxJobsPerUser</A></H3>
2529<HR>
2530
2531<H4>Examples</H4>
2532
2533<UL><PRE>
2534MaxJobsPerUser 100
2535MaxJobsPerUser 9999
2536MaxJobsPerUser 0
2537</PRE></UL>
2538
2539<H4>Description</H4>
2540
2541<P>The <CODE>MaxJobsPerUser</CODE> directive controls the maximum number of active jobs
2542that are allowed for each user. Once a user reaches the limit, new jobs will be
2543rejected until one of the active jobs is completed, stopped, aborted, or cancelled.
2544
2545<P>Setting the maximum to 0 disables this functionality. The default
04d756fc 2546setting is 0.
2547
e75387bc 2548<!-- NEED 3in -->
2549<H3><A NAME="MaxLogSize">MaxLogSize</A></H3>
2550<HR>
2551
2552<H4>Examples</H4>
766ec9c5 2553
2554<UL><PRE>
e75387bc 2555MaxLogSize 1048576
fd7cc15d 2556MaxLogSize 1m
e75387bc 2557MaxLogSize 0
766ec9c5 2558</PRE></UL>
2559
e75387bc 2560<H4>Description</H4>
766ec9c5 2561
e75387bc 2562<P>The <CODE>MaxLogSize</CODE> directive controls the maximum size of each
2563log file. Once a log file reaches or exceeds the maximum size it is closed
2564and renamed to <VAR>filename.O</VAR>. This allows you to rotate the logs
2565automatically. The default size is 1048576 bytes (1MB).
766ec9c5 2566
e75387bc 2567<P>Setting the maximum size to 0 disables log rotation.
2568
2569<!-- NEED 3in -->
2570<H3><A NAME="MaxRequestSize">MaxRequestSize</A></H3>
2571<HR>
2572
2573<H4>Examples</H4>
2574
2575<UL><PRE>
e75387bc 2576MaxRequestSize 10485760
fd7cc15d 2577MaxRequestSize 10m
2578MaxRequestSize 0
e75387bc 2579</PRE></UL>
2580
2581<H4>Description</H4>
2582
2583<P>The <CODE>MaxRequestSize</CODE> directive controls the maximum size of
2584print files, IPP requests, and HTML form data in HTTP POST requests. The
2585default limit is 0 which disables the limit check.
2586
b1d503b0 2587<P>Also see the identical
2588<A HREF="#LimitRequestBody"><CODE>LimitRequestBody</CODE></A> directive.
2589
e75387bc 2590<!-- NEED 3in -->
2591<H3><A NAME="Order">Order</A></H3>
2592<HR>
2593
2594<H4>Examples</H4>
2595
2596<UL><PRE>
2597Order Allow,Deny
2598Order Deny,Allow
2599</PRE></UL>
2600
2601<H4>Description</H4>
2602
2603<P>The <CODE>Order</CODE> directive defines the default access control.
2604The following values are supported:
2605
2606<UL>
2607
fd7cc15d 2608 <LI><CODE>Allow,Deny</CODE> - Allow requests from all
e75387bc 2609 systems <I>except</I> for those listed in a <CODE>Deny</CODE>
2610 directive.
2611
fd7cc15d 2612 <LI><CODE>Deny,Allow</CODE> - Allow requests only from
e75387bc 2613 those listed in an <CODE>Allow</CODE> directive.
2614
2615</UL>
2616
2617<P>The <CODE>Order</CODE> directive must appear inside a
2618<A HREF="#Location"><CODE>Location</CODE></A> directive.
2619
2620<!-- NEED 3in -->
2621<H3><A NAME="PageLog">PageLog</A></H3>
2622<HR>
2623
2624<H4>Examples</H4>
2625
2626<UL><PRE>
2627PageLog /var/log/cups/page_log
6380867c 2628PageLog /var/log/cups/page_log-%s
e75387bc 2629PageLog syslog
2630</PRE></UL>
2631
2632<H4>Description</H4>
2633
2634<P>The <CODE>PageLog</CODE> directive sets the name of the page log
2635file. If the filename is not absolute then it is assumed to be relative
2636to the <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
2637default page log file is <VAR>/var/log/cups/page_log</VAR>.
2638
6380867c 2639<P>The server name can be included in the filename by using
2640<CODE>%s</CODE> in the name.
2641
551d3a88 2642<P>The special name "syslog" can be used to send the page information
2643to the system log instead of a plain file.
2644
e75387bc 2645<!-- NEED 3in -->
2646<H3><A NAME="Port">Port</A></H3>
2647<HR>
2648
2649<H4>Examples</H4>
2650
2651<UL><PRE>
2652Port 631
2653Port 80
2654</PRE></UL>
2655
2656<H4>Description</H4>
2657
2658<P>The <CODE>Port</CODE> directive specifies a port to listen on.
2659Multiple <CODE>Port</CODE> lines can be specified to listen on multiple
2660ports. The default port is 631.
2661
e75387bc 2662<!-- NEED 3in -->
2663<H3><A NAME="PreserveJobHistory">PreserveJobHistory</A></H3>
2664<HR>
2665
2666<H4>Examples</H4>
2667
2668<UL><PRE>
2669PreserveJobHistory On
2670PreserveJobHistory Off
2671</PRE></UL>
2672
2673<H4>Description</H4>
2674
2675<P>The <CODE>PreserveJobHistory</CODE> directive controls whether
2676the history of completed, cancelled, or aborted print jobs is stored
2677on disk.
2678
2679<P>A value of <CODE>On</CODE> (the default) preserves job information
2680until the administrator purges it with the <CODE>cancel</CODE>
2681command.
2682
2683<P>A value of <CODE>Off</CODE> removes the job information as soon as
2684each job is completed, cancelled, or aborted.
2685
2686<!-- NEED 3in -->
2687<H3><A NAME="PreserveJobFiles">PreserveJobFiles</A></H3>
2688<HR>
2689
2690<H4>Examples</H4>
2691
2692<UL><PRE>
2693PreserveJobFiles On
2694PreserveJobFiles Off
2695</PRE></UL>
2696
2697<H4>Description</H4>
2698
2699<P>The <CODE>PreserveJobFiles</CODE> directive controls whether the
2700document files of completed, cancelled, or aborted print jobs are
2701stored on disk.
2702
2703<P>A value of <CODE>On</CODE> preserves job files until the
2704administrator purges them with the <CODE>cancel</CODE> command. Jobs
2705can be restarted (and reprinted) as desired until they are purged.
2706
2707<P>A value of <CODE>Off</CODE> (the default) removes the job files as
2708soon as each job is completed, cancelled, or aborted.
2709
2710<!-- NEED 3in -->
2711<H3><A NAME="Printcap">Printcap</A></H3>
2712<HR>
2713
2714<H4>Examples</H4>
2715
2716<UL><PRE>
2717Printcap
2718Printcap /etc/printcap
b1d503b0 2719Printcap /etc/printers.conf
e75387bc 2720</PRE></UL>
2721
2722<H4>Description</H4>
2723
2724<P>The <CODE>Printcap</CODE> directive controls whether or not a
86afeb1e 2725printcap file is automatically generated and updated with a list
2726of available printers. If specified with no value, then no
2727printcap file will be generated. The default is to generate a
2728file named <VAR>/etc/printcap</VAR>.
e75387bc 2729
2730<P>When a filename is specified (e.g. <VAR>/etc/printcap</VAR>), the
2731printcap file is written whenever a printer is added or removed. The
2732printcap file can then be used by applications that are hardcoded to
2733look at the printcap file for the available printers.
2734
b1d503b0 2735<!-- NEED 3in -->
9ae34eb7 2736<H3><A NAME="PrintcapFormat">PrintcapFormat</A></H3>
b1d503b0 2737<HR>
2738
2739<H4>Examples</H4>
2740
2741<UL><PRE>
2742PrintcapFormat BSD
2743PrintcapFormat Solaris
2744</PRE></UL>
2745
2746<H4>Description</H4>
2747
2748<P>The <CODE>PrintcapFormat</CODE> directive controls the output
2749format of the printcap file. The default is to generate a BSD
2750printcap file.
2751
9ae34eb7 2752<!-- NEED 3in -->
2753<H3><A NAME="PrintcapGUI">PrintcapGUI</A></H3>
2754<HR>
2755
2756<H4>Example</H4>
2757
2758<UL><PRE>
2759PrintcapGUI /usr/bin/glpoptions
2760</PRE></UL>
2761
2762<H4>Description</H4>
2763
2764<P>The <CODE>PrintcapGUI</CODE> directive sets the program to
2765use when displaying an option panel from an IRIX application
2766that uses the Impressario print API. The default program is the
2767ESP Print Pro "glpoptions" GUI.
2768
2769<P>The program must accept the <CODE>-d</CODE> option to specify
2770a printer and the <CODE>-o</CODE> option to specify one or more
2771options. After allowing the user to select/change options, the
2772program must then write the list of printing options without the
2773<CODE>-o</CODE> to the standard output.
2774
08ffbb44 2775<!-- NEED 3in -->
2776<H3><A NAME="RemoteRoot">RemoteRoot</A></H3>
2777<HR>
2778
2779<H4>Examples</H4>
2780
2781<UL><PRE>
2782RemoteRoot remroot
2783RemoteRoot root
2784</PRE></UL>
2785
2786<H4>Description</H4>
2787
2788<P>The <CODE>RemoteRoot</CODE> directive sets the username for
2789unauthenticated root requests from remote hosts. The default
2790username is <VAR>remroot</VAR>. Setting <CODE>RemoteRoot</CODE>
2791to <VAR>root</VAR> effectively disables this security mechanism.
2792
e75387bc 2793<!-- NEED 3in -->
2794<H3><A NAME="RequestRoot">RequestRoot</A></H3>
2795<HR>
2796
2797<H4>Examples</H4>
2798
2799<UL><PRE>
2800RequestRoot /var/spool/cups
2801RequestRoot /foo/bar/spool/cups
2802</PRE></UL>
2803
2804<H4>Description</H4>
2805
2806<P>The <CODE>RequestRoot</CODE> directive sets the directory for
2807incoming IPP requests and HTML forms. If an absolute path is not
2808provided then it is assumed to be relative to the
2809<A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
2810default request directory is <VAR>/var/spool/cups</VAR>.
2811
9cfa8573 2812<!-- NEED 4in -->
2813<H3><A NAME="Require">Require</A></H3>
2814<HR>
2815
2816<H4>Examples</H4>
2817
2818<UL><PRE>
2819Require group foo bar
2820Require user john mary
2821Require valid-user
2822</PRE></UL>
2823
2824<H4>Description</H4>
2825
2826<P>The <CODE>Require</CODE> directive specifies that
2827authentication is required for the resource. The
2828<CODE>group</CODE> keyword specifies that the authenticated user
2829must be a member of one or more of the named groups that follow.
2830
2831<P>The <CODE>user</CODE> keyboard specifies that the
2832authenticated user must be one of the named users that follow.
2833
2834<P>The <CODE>valid-user</CODE> keyword specifies that any
2835authenticated user may access the resource.
2836
2837<P>The default is to do no authentication. This directive must
2838appear inside a <A HREF="#Location"><CODE>Location</CODE></A>
2839directive.
2840
e75387bc 2841<!-- NEED 3in -->
2842<H3><A NAME="RIPCache">RIPCache</A></H3>
2843<HR>
2844
2845<H4>Examples</H4>
2846
2847<UL><PRE>
2848RIPCache 8m
2849RIPCache 1g
2850RIPCache 2048k
2851</PRE></UL>
2852
2853<H4>Description</H4>
2854
2855<P>The <CODE>RIPCache</CODE> directive sets the size of the memory
2856cache used by Raster Image Processor ("RIP") filters such as
2857<CODE>imagetoraster</CODE> and <CODE>pstoraster</CODE>. The size can
2858be suffixed with a "k" for kilobytes, "m" for megabytes, or
2859"g" for gigabytes. The default cache size is "8m", or 8 megabytes.
2860
9cfa8573 2861<!-- NEED 3in -->
2862<H3><A NAME="RootCertDuration">RootCertDuration</A></H3>
2863<HR>
2864
2865<H4>Examples</H4>
2866
2867<UL><PRE>
2868RootCertDuration 300
2869RootCertDuration 0
2870</PRE></UL>
2871
2872<H4>Description</H4>
2873
2874<P>The <CODE>RootCertDuration</CODE> directive controls the
2875interval between updates of the root authentication certificate.
2876The default is <CODE>300</CODE> seconds which updates the root
2877certificate approximately once every 5 minutes. Set the interval
2878to 0 to disable certificate updates entirely.
2879
2880
b1d503b0 2881<!-- NEED 3in -->
2882<H3><A NAME="RunAsUser">RunAsUser</A></H3>
2883<HR>
2884
2885<H4>Examples</H4>
2886
2887<UL><PRE>
2888RunAsUser Yes
2889RunAsUser No
2890</PRE></UL>
2891
2892<H4>Description</H4>
2893
2894<P>The <CODE>RunAsUser</CODE> directive controls whether the
2895scheduler runs as the unpriviledged user account (usually <CODE>lp</CODE>).
2896The default is <CODE>No</CODE> which leaves the scheduler running as
2897the <CODE>root</CODE> user.
2898
2899<P><B>Note:</B> Running as a non-priviledged user may prevent
2900LPD and locally connected printers from working due to
2901permission problems. The <CODE>lpd</CODE> backend will
2902automatically use a non-priviledged mode that is not 100%
2903compliant with RFC 1179. The <CODE>parallel</CODE>,
2904<CODE>serial</CODE>, and <CODE>usb</CODE> backends will need
2905write access to the corresponding device files.
2906
9cfa8573 2907<!-- NEED 3in -->
2908<H3><A NAME="Satisfy">Satisfy</A></H3>
2909<HR>
2910
2911<H4>Examples</H4>
2912
2913<UL><PRE>
2914Satisfy all
2915Satisfy any
2916</PRE></UL>
2917
2918<H4>Description</H4>
2919
2920<P>The <CODE>Satisfy</CODE> directive specifies whether all
2921conditions must be satisfied to allow access to the resource. If
2922set to <CODE>all</CODE>, then all authentication and access
2923control conditions must be satified to allow access.
2924
2925<P>Setting <CODE>Satisfy</CODE> to <CODE>any</CODE> allows a user to
2926gain access if the authentication or access control requirements are
2927satisfied. For example, you might require authentication for remote
2928access, but allow local access without authentication.
2929
2930<P>The default is <CODE>all</CODE>. This directive must appear
2931inside a <A HREF="#Location"><CODE>Location</CODE></A>
2932directive.
2933
e75387bc 2934<!-- NEED 3in -->
2935<H3><A NAME="ServerAdmin">ServerAdmin</A></H3>
2936<HR>
2937
2938<H4>Examples</H4>
2939
2940<UL><PRE>
2941ServerAdmin user@host
2942ServerAdmin root@foo.bar.com
2943</PRE></UL>
2944
2945<H4>Description</H4>
2946
2947<P>The <CODE>ServerAdmin</CODE> directive identifies the email address for the
2948administrator on the system. By default the administrator email address is
2949<CODE>root@server</CODE>, where <CODE>server</CODE> is the server name.
2950
2951<!-- NEED 3in -->
2952<H3><A NAME="ServerBin">ServerBin</A></H3>
2953<HR>
2954
2955<H4>Examples</H4>
2956
2957<UL><PRE>
2958ServerBin /usr/lib/cups
2959ServerBin /foo/bar/lib/cups
2960</PRE></UL>
2961
2962<H4>Description</H4>
2963
2964<P>The <CODE>ServerBin</CODE> directive sets the directory for
2965server-run executables. If an absolute path is not provided then it is
2966assumed to be relative to the
2967<A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
f3e79315 2968default executable directory is <VAR>/usr/lib/cups</VAR>.
e75387bc 2969
b1d503b0 2970<!-- NEED 3in -->
2971<H3><A NAME="ServerCertificate">ServerCertificate</A></H3>
2972<HR>
2973
2974<H4>Examples</H4>
2975
2976<UL><PRE>
2977ServerCertificate /etc/cups/ssl/server.crt
2978</PRE></UL>
2979
2980<H4>Description</H4>
2981
2982<P>The <CODE>ServerCertificate</CODE> directive specifies the
2983location of the SSL certificate file used by the server when
2984negotiating encrypted connections. The certificate must not be
2985encrypted (password protected) since the scheduler normally runs
2986in the background and will be unable to ask for a password.
2987The default certificate file is <VAR>/etc/cups/ssl/server.crt</VAR>.
2988
2989<!-- NEED 3in -->
2990<H3><A NAME="ServerKey">ServerKey</A></H3>
2991<HR>
2992
2993<H4>Examples</H4>
2994
2995<UL><PRE>
2996ServerKey /etc/cups/ssl/server.key
2997</PRE></UL>
2998
2999<H4>Description</H4>
3000
3001<P>The <CODE>ServerKey</CODE> directive specifies the location
3002of the SSL private key file used by the server when negotiating
3003encrypted connections. The default key file is
3004<VAR>/etc/cups/ssl/server.crt</VAR>.
3005
e75387bc 3006<!-- NEED 3in -->
3007<H3><A NAME="ServerName"></A>ServerName</H3>
3008<HR>
3009
3010<H4>Examples</H4>
3011
3012<UL><PRE>
3013ServerName foo.domain.com
3014ServerName myserver.domain.com
3015</PRE></UL>
3016
3017<H4>Description</H4>
3018
3019<P>The <CODE>ServerName</CODE> directive specifies the hostname that is
3020reported to clients. By default the server name is the hostname.
3021
3022<!-- NEED 3in -->
3023<H3><A NAME="ServerRoot">ServerRoot</A></H3>
3024<HR>
3025
3026<H4>Examples</H4>
3027
3028<UL><PRE>
3029ServerRoot /etc/cups
3030ServerRoot /foo/bar/cups
3031</PRE></UL>
3032
3033<H4>Description</H4>
3034
3035<P>The <CODE>ServerRoot</CODE> directive specifies the absolute path to
3036the server configuration and state files. It is also used to resolve
3037relative paths in the <VAR>cupsd.conf</VAR> file. The default server
3038directory is <VAR>/etc/cups</VAR>.
3039
b1d503b0 3040<!-- NEED 3in -->
3041<H3><A NAME="SSLListen">SSLListen</A></H3>
3042<HR>
3043
3044<H4>Examples</H4>
3045
3046<UL><PRE>
3047SSLListen 127.0.0.1:443
3048SSLListen 192.0.2.1:443
3049</PRE></UL>
3050
3051<H4>Description</H4>
3052
3053<P>The <CODE>SSLListen</CODE> directive specifies a network
3054address and port to listen for secure connections. Multiple
3055<CODE>SSLListen</CODE> directives can be provided to listen on
3056multiple addresses.
3057
3058<P>The <CODE>SSLListen</CODE> directive is similar to the
3059<A HREF="#SSLPort"><CODE>SSLPort</CODE></A> directive but allows
3060you to restrict access to specific interfaces or networks.
3061
3062<!-- NEED 3in -->
3063<H3><A NAME="SSLPort">SSLPort</A></H3>
3064<HR>
3065
3066<H4>Examples</H4>
3067
3068<UL><PRE>
3069SSLPort 443
3070</PRE></UL>
3071
3072<H4>Description</H4>
3073
3074<P>The <CODE>SSLPort</CODE> directive specifies a port to listen
3075on for secure connections. Multiple <CODE>SSLPort</CODE> lines
3076can be specified to listen on multiple ports.
3077
e75387bc 3078<!-- NEED 3in -->
3079<H3><A NAME="SystemGroup">SystemGroup</A></H3>
3080<HR>
3081
3082<H4>Examples</H4>
3083
3084<UL><PRE>
3085SystemGroup sys
3086SystemGroup system
3087SystemGroup root
3088</PRE></UL>
3089
3090<H4>Description</H4>
3091
3092<P>The <CODE>SystemGroup</CODE> directive specifies the system
3093administration group for <CODE>System</CODE> authentication. More
fd7cc15d 3094information can be found later in this chapter in
3095<A HREF="#PRINTING_SECURITY">"Printing System Security"</A>.
e75387bc 3096
3097<!-- NEED 3in -->
3098<H3><A NAME="TempDir">TempDir</A></H3>
3099<HR>
3100
3101<H4>Examples</H4>
3102
3103<UL><PRE>
3104TempDir /var/tmp
3105TempDir /foo/bar/tmp
3106</PRE></UL>
3107
3108<H4>Description</H4>
3109
3110<P>The <CODE>TempDir</CODE> directive specifies an absolute path for
3111the directory to use for temporary files. The default directory is
3112<VAR>/var/tmp</VAR>.
3113
3114<P>Temporary directories must be world-writable and should have the
3115"sticky" permission bit enabled so that other users cannot delete
3116filter temporary files. The following commands will create an
3117appropriate temporary directory called <VAR>/foo/bar/tmp</VAR>:
3118
3119<UL><PRE>
3120<B>mkdir /foo/bar/tmp ENTER</B>
3121<B>chmod a+rwxt /foo/bar/tmp ENTER</B>
3122</PRE></UL>
3123
3124<!-- NEED 3in -->
3125<H3><A NAME="Timeout">Timeout</A></H3>
3126<HR>
3127
3128<H4>Examples</H4>
3129
3130<UL><PRE>
3131Timeout 300
3132Timeout 90
3133</PRE></UL>
3134
3135<H4>Description</H4>
3136
3137<P>The <CODE>Timeout</CODE> directive controls the amount of time to
3138wait before an active HTTP or IPP request times out. The default
3139timeout is 300 seconds.
3140
3141<!-- NEED 3in -->
3142<H3><A NAME="User">User</A></H3>
3143<HR>
3144
3145<H4>Examples</H4>
3146
3147<UL><PRE>
3148User lp
3149User guest
3150</PRE></UL>
3151
3152<H4>Description</H4>
3153
3154<P>The <CODE>User</CODE> directive specifies the UNIX user that
3155filter and CGI programs run as. The default user is <CODE>lp</CODE>.
3156
fd7cc15d 3157<!-- NEW PAGE -->
3158<H2><A NAME="PRINTING_SECURITY">Printing System Security</A></H2>
e75387bc 3159
551d3a88 3160<P>CUPS provides support for address, certificate, and password (Basic
3161and Digest) based authentication and access control. Certificate and
3162password authentication provide ways to limit access to individual
3163people or groups.
e75387bc 3164
3165<P>Address based access control allows you to limit access to specific
3166systems, networks, or domains. While this does not provide authentication,
3167it does allow you to limit the potential users of your system efficiently.
3168
3169<P>CUPS maintains a list of locations that have access control and/or
3170authentication enabled. Locations are specified using the
3171<A HREF="#Location"><CODE>Location</CODE></A> directive:
3172
3173<UL><PRE>
3174&lt;Location /resource&gt;
3175<A HREF="#AuthClass">AuthClass</A> ...
3176<A HREF="#AuthGroupName">AuthGroupName</A> ...
3177<A HREF="#AuthType">AuthType</A> ...
3178
3179<A HREF="#Order">Order</A> ...
3180<A HREF="#Allow">Allow</A> from ...
3181<A HREF="#Deny">Deny</A> from ...
3182&lt;/Location&gt;
3183</PRE></UL>
3184
3185<P>Locations generally follow the directory structure of the
3186<A HREF="#DocumentRoot"><CODE>DocumentRoot</CODE></A> directory, however
3187CUPS does have several virtual locations for administration, classes, jobs,
3188and printers:
3189
3190<CENTER><TABLE BORDER="1">
3191<TR>
3192 <TH>Location</TH>
3193 <TH>Description</TH>
3194</TR>
3195<TR>
3196 <TD>/admin</TD>
3197 <TD>The path for all administration operations.</TD>
3198</TR>
3199<TR>
3200 <TD>/classes</TD>
3201 <TD>The path for all classes.</TD>
3202</TR>
3203<TR>
3204 <TD>/classes/name</TD>
3205 <TD>The resource for class <CODE>name</CODE>.</TD>
3206</TR>
3207<TR>
3208 <TD>/jobs</TD>
3209 <TD>The path for all jobs.</TD>
3210</TR>
3211<TR>
3212 <TD>/jobs/id</TD>
3213 <TD>The resource for job <CODE>id</CODE>.</TD>
3214</TR>
3215<TR>
3216 <TD>/printers</TD>
3217 <TD>The path for all printers.</TD>
3218</TR>
3219<TR>
3220 <TD>/printers/name</TD>
3221 <TD>The path for printer <CODE>name</CODE>.</TD>
3222</TR>
3223<TR>
3224 <TD>/printers/name.ppd</TD>
3225 <TD>The PPD file path for printer <CODE>name</CODE>.</TD>
3226</TR>
3227</TABLE></CENTER>
3228
fd7cc15d 3229<H3><A NAME="CERTIFICATES">Authentication Using Certificates</A></H3>
e75387bc 3230
3231<P>CUPS supports a local certificate-based authentication scheme that
3232can be used in place of <CODE>Basic</CODE> or <CODE>Digest</CODE>
3233authentication by clients connecting through the <CODE>localhost</CODE>
3234interface. Certificate authentication is not supported or allowed from
3235clients on any other interface.
3236
3237<P>Certificates are 128-bit random numbers that refer to an internal
3238authentication record in the server. A client connecting via the
3239<CODE>localhost</CODE> interface sends a request with an
3240authorization header of:
3241
3242<UL><PRE>
3243Authorization: Local 0123456789ABCDEF0123456789ABCDEF
3244</PRE></UL>
3245
3246<P>The server then looks up the local certificate and authenticates
3247using the username associated with it.
3248
3249<P>Certificates are generated by the server automatically and stored in
3250the <VAR>/etc/cups/certs</VAR> directory using the process ID of the
3251CGI program started by the server. Certificate files are only readable
3252by the <A HREF="#User"><CODE>User</CODE></A> and
3253<A HREF="#Group"><CODE>Group</CODE></A> defined in the
3254<VAR>cupsd.conf</VAR> file. When the CGI program ends the certificate
3255is removed and invalidated automatically.
3256
3257<P>The special file <VAR>/etc/cups/certs/0</VAR> defines the <I>root
3258certificate</I> which can be used by any client running as the super-user
3259or another user that is part of the group defined by the
3260<A HREF="#SystemGroup"><CODE>SystemGroup</CODE></A> directive. The
3261root certificate is automatically regenerated every 5 minutes.
3262
fd7cc15d 3263<H3>Using Basic Authentication</H3>
e75387bc 3264
3265<P>Basic authentication uses UNIX users and passwords to authenticate
3266access to resources such as printers and classes, and to limit access
9cfa8573 3267to administrative functions.</P>
e75387bc 3268
fd7cc15d 3269<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
3270<TR>
3271 <TD>
3272 <B>NOTE:</B>
e75387bc 3273
3274 <P>Basic authentication sends the username and password Base64
3275 encoded from the client to the server, so it offers no
3276 protection against eavesdropping. This means that a malicious
3277 user can monitor network packets and discover valid users and
3278 passwords that could result in a serious compromise in network
3279 security. Use Basic authentication with extreme care.
fd7cc15d 3280 </TD>
3281</TR>
3282</TABLE></CENTER>
e75387bc 3283
3284<P>The CUPS implementation of Basic authentication does not allow access
3285through user accounts without a password. If you try to authenticate
3286using an account without a password, your access will be immediately
3287blocked.
3288
3289<P>Once a valid username and password is authenticated by CUPS, any
9cfa8573 3290additional group membership requirements are checked.</P>
e75387bc 3291
fd7cc15d 3292<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
3293<TR>
3294 <TD>
3295 <B>NOTE:</B>
e75387bc 3296
3297 <P>The root user is considered by CUPS to be a member of every
3298 group.
fd7cc15d 3299 </TD>
3300</TR>
3301</TABLE></CENTER>
e75387bc 3302
fd7cc15d 3303<!-- NEED 1in -->
e75387bc 3304<P>Use the <CODE>AuthType</CODE> directive to enable Basic authentication:
3305
3306<UL><PRE>
3307AuthType Basic
3308</PRE></UL>
3309
551d3a88 3310<!-- NEED 7in -->
fd7cc15d 3311<H3>Using Digest Authentication</H3>
e75387bc 3312
3313<P>Digest authentication uses users and passwords defined in the
3314<VAR>/etc/cups/passwd.md5</VAR> file to authenticate access to
3315resources such as printers and classes, and to limit access to
9cfa8573 3316administrative functions.</P>
e75387bc 3317
fd7cc15d 3318<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
3319<TR>
3320 <TD>
3321 <B>NOTE:</B>
e75387bc 3322
3323 <P>Unlike Basic authentication, Digest passes the MD5 sum
3324 (basically a complicated checksum) of the username and password
3325 instead of the strings themselves. Also, Digest authentication
3326 does not use the UNIX password file, so if an attacker does
3327 discover the original password it is less likely to result in a
3328 serious security problem so long as you use a different UNIX
3329 password than the corresponding Digest password.
3330
3331 <P>The current CUPS implementation of Digest authentication
3332 uses the client's hostname or IP address for the "nonce" value.
3333 The nonce value is an additional string added to the username
3334 and password to make guessing the password more difficult. The
3335 server checks that the nonce value matches the client's hostname
3336 or address and rejects the MD5 sum if it doesn't. Future versions
3337 of CUPS will support Digest "session" authentication which adds
3338 the request data to the MD5 sum, providing even better
3339 authentication and security.
3340
3341 <P>Digest authentication does not guarantee that an attacker
3342 cannot gain unauthorized access, but it is safer than Basic
3343 authentication and should be used in place of Basic
3344 authentication whenever possible. <B>Support for Digest
3345 authentication in web browsers is not yet universally
3346 available.</B>
fd7cc15d 3347 </TD>
3348</TR>
3349</TABLE></CENTER>
e75387bc 3350
fd7cc15d 3351<!-- NEED 2in -->
e75387bc 3352<P>The <CODE>lppasswd(1)</CODE> command is used to add, change, or
3353remove accounts from the <VAR>passwd.md5</VAR> file. To add a
3354user to the default system group, type:
3355
3356<UL><PRE>
3357<B>lppasswd -a user ENTER</B>
3358Password: <B>(password) ENTER</B> [password is not echoed]
3359Password again: <B>(password) ENTER</B> [password is not echoed]
3360</PRE></UL>
3361
fd7cc15d 3362<!-- NEED 2in -->
e75387bc 3363<P>Once added, a user can change his/her password by typing:
3364
3365<UL><PRE>
3366<B>lppasswd ENTER</B>
3367Old password: <B>(password) ENTER</B> [password is not echoed]
3368Password: <B>(password) ENTER</B> [password is not echoed]
3369Password again: <B>(password) ENTER</B> [password is not echoed]
3370</PRE></UL>
3371
fd7cc15d 3372<!-- NEED 1in -->
e75387bc 3373<P>To remove a user from the password file, type:
3374
3375<UL><PRE>
3376<B>lppasswd -x user ENTER</B>
3377</PRE></UL>
3378
3379<P>Once a valid username and password is authenticated by CUPS, any
9cfa8573 3380additional group membership requirements are checked.</P>
e75387bc 3381
fd7cc15d 3382<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
3383<TR>
3384 <TD>
3385 <B>NOTE:</B>
e75387bc 3386
3387 <P>The root user is considered by CUPS to be a member of every
3388 group.
fd7cc15d 3389 </TD>
3390</TR>
3391</TABLE></CENTER>
e75387bc 3392
3393<P>Use the <CODE>AuthType</CODE> directive to enable Digest authentication:
3394
3395<UL><PRE>
3396AuthType Digest
3397</PRE></UL>
3398
fd7cc15d 3399<H3>System and Group Authentication</H3>
e75387bc 3400
3401<P>The <A HREF="#AuthClass"><CODE>AuthClass</CODE></A> directive controls
3402the level of authentication to perform. <CODE>System</CODE> and
3403<CODE>Group</CODE> authentication extend the normal user-based authentication
3404to require membership in a UNIX group. For <CODE>System</CODE> authentication
3405each user must belong to the <CODE>sys</CODE>, <CODE>system</CODE>, or
3406<CODE>root</CODE> group; the actual group depends on the operating system.
3407
3408<P>For <CODE>Group</CODE> authentication each user must belong to the
3409group named by the <A HREF="#AuthGroupName"><CODE>AuthGroupName</CODE></A>
3410directive:
3411
3412<UL><PRE>
3413&lt;Location /path&gt;
3414AuthType Digest
3415AuthClass Group
3416AuthGroupName mygroup
3417&lt;/Location&gt;
3418</PRE></UL>
3419
3420<P>The named group must be a valid UNIX user group, usually defined in the
3421<VAR>/etc/group</VAR> or <VAR>/etc/netgroup</VAR> files. Additionally, when
3422using Digest authentication you need to create user accounts with the named
3423group:
3424
3425<UL><PRE>
3426<B>lppasswd -g mygroup -a user ENTER</B>
3427Password: <B>(password) ENTER</B> [password is not echoed]
3428Password again: <B>(password) ENTER</B> [password is not echoed]
3429</PRE></UL>
3430
fd7cc15d 3431<!-- NEW PAGE -->
3432<H2><A NAME="PRINTER_ACCOUNTING">Printer Accounting</A></H2>
e75387bc 3433
9cfa8573 3434<P>CUPS maintains a log of all accesses, errors, and
d0a31f54 3435pages that are printed. The log files are normally stored in the
3436<VAR>/var/log/cups</VAR> directory. You can change this by
3437editing the <VAR>/etc/cups/cupsd.conf</VAR> configuration file.
e75387bc 3438
fd7cc15d 3439<H3>The access_log File</H3>
e75387bc 3440
3441<P>The <VAR>access_log</VAR> file lists each HTTP resource that is accessed
3442by a web browser or CUPS/IPP client. Each line is in the so-called "Common
3443Log Format" used by many web servers and web reporting tools:
3444
3445<UL><PRE>
3446host group user date-time \"method resource version\" status bytes
3447
3448127.0.0.1 - - [20/May/1999:19:20:29 +0000] "POST /admin/ HTTP/1.1" 401 0
3449127.0.0.1 - mike [20/May/1999:19:20:31 +0000] "POST /admin/ HTTP/1.1" 200 0
3450</PRE></UL>
3451
3452<P>The <I>host</I> field will normally only be an IP address unless you
3453have enabled the <A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A>
3454directive in the <VAR>cupsd.conf</VAR> file.
3455
3456<P>The <I>group</I> field always contains "-" in CUPS.
3457
3458<P>The <I>user</I> field is the authenticated username of the requesting user.
3459If no username and password is supplied for the request then this field
3460contains "-".
3461
551d3a88 3462<P>The <I>date-time</I> field is the date and time of the request in local time
3463and is in the format:
e75387bc 3464
3465<UL><PRE>
551d3a88 3466[DD/MON/YYYY:HH:MM:SS +ZZZZ]
e75387bc 3467</PRE></UL>
3468
551d3a88 3469<P>where <I>ZZZZ</I> is the timezone offset in hours and minutes from Greenwich
3470Mean Time (a.k.a. GMT a.k.a. ZULU.)
3471
e75387bc 3472<P>The <I>method</I> field is the HTTP method used ("GET", "PUT", "POST", etc.)
3473
3474<P>The <I>resource</I> field is the filename of the requested resource.
3475
3476<P>The <I>version</I> field is the HTTP specification version used by the
3477client. For CUPS clients this will always be "HTTP/1.1".
3478
3479<P>The <I>status</I> field contains the HTTP result status of the
3480request. Usually it is "200", but other HTTP status codes are possible.
3481For example, 401 is the "unauthorized access" status in the example
3482above.
3483
3484<P>The <I>bytes</I> field contains the number of bytes in the request.
3485For POST requests the <I>bytes</I> field contains the number of bytes
551d3a88 3486that was received from the client.
e75387bc 3487
fd7cc15d 3488<H3>The error_log File</H3>
e75387bc 3489
3490<P>The <VAR>error_log</VAR> file lists messages from the scheduler (errors,
3491warnings, etc.):
3492
3493<UL><PRE>
3494level date-time message
3495
3496I [20/May/1999:19:18:28 +0000] Job 1 queued on 'DeskJet' by 'mike'.
3497I [20/May/1999:19:21:02 +0000] Job 2 queued on 'DeskJet' by 'mike'.
3498I [20/May/1999:19:22:24 +0000] Job 2 was cancelled by 'mike'.
3499</PRE></UL>
3500
3501<P>The <I>level</I> field contains the type of message:
3502
3503<UL>
3504
3505 <LI><CODE>E</CODE> - An error occurred.
3506
3507 <LI><CODE>W</CODE> - The server was unable to perform some action.
3508
3509 <LI><CODE>I</CODE> - Informational message.
3510
3511 <LI><CODE>D</CODE> - Debugging message.
3512
3513</UL>
3514
3515<P>The <I>date-time</I> field contains the date and time of when the page
3516started printing. The format of this field is identical to the <I>data-time</I>
3517field in the <VAR>access_log</VAR> file.
3518
3519<P>The <I>message</I> fields contains a free-form textual message.
3520
fd7cc15d 3521<H3>The page_log File</H3>
e75387bc 3522
3523<P>The <VAR>page_log</VAR> file lists each page that is sent to a printer.
3524Each line contains the following information:
3525
3526<UL><PRE>
3527printer user job-id date-time page-number num-copies job-billing
3528
3529DeskJet root 2 [20/May/1999:19:21:05 +0000] 1 0 acme-123
3530</PRE></UL>
3531
3532<P>The <I>printer</I> field contains the name of the printer that
3533printed the page. If you send a job to a printer class, this field will
3534contain the name of the printer that was assigned the job.
3535
3536<P>The <I>user</I> field contains the name of the user (the IPP
3537<CODE>requesting-user-name</CODE> attribute) that submitted this file for
3538printing.
3539
3540<P>The <I>job-id</I> field contains the job number of the page being printed.
3541Job numbers are reset to 1 whenever the CUPS server is started, so don't depend
3542on this number being unique!
3543
3544<P>The <I>date-time</I> field contains the date and time of when the page
3545started printing. The format of this field is identical to the <I>data-time</I>
3546field in the <VAR>access_log</VAR> file.
3547
3548<P>The <I>page-number</I> and <I>num-pages</I> fields contain the page number
3549and number of copies being printed of that page. For printer that can not
3550produce copies on their own, the <I>num-pages</I> field will always be 1.
3551
3552<P>The <I>job-billing</I> field contains a copy of the
3553<CODE>job-billing</CODE> attribute provided with the IPP
fd7cc15d 3554<CODE>create-job</CODE> or <CODE>print-job</CODE> requests or "-" if none
3555was provided.
e75387bc 3556
fd7cc15d 3557<!-- NEW PAGE -->
3558<H2><A NAME="FILE_TYPING_FILTERING">File Typing and Filtering</A></H2>
e75387bc 3559
3560<P>CUPS provides a MIME-based file typing and filtering mechanism to
3561convert files to a printable format for each printer. On startup the
3562CUPS server reads MIME database files from the <VAR>/etc/cups</VAR>
3563directory (or a directory specified by the
3564<A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directive) to build
3565a file type and conversion database in memory. These database files are
3566plain ASCII text and can be edited with your favorite text editor.
3567
3568<P>The <VAR>mime.types</VAR> and <VAR>mime.convs</VAR> files define the
3569standard file types and filters that are available on the system.
3570
3571<H3>mime.types</H3>
3572
3573<P>The <VAR>mime.types</VAR> file defines the known file types. Each line
3574of the file starts with the MIME type and may be followed by one or
3575more file type recognition rules. For example, the
3576<CODE>text/html</CODE> file type is defined as:
3577
3578<UL><PRE>
3579text/html html htm \
3580 printable(0,1024) + \
3581 (string(0,"&lt;HTML&gt;") string(0,"&lt;!DOCTYPE"))
3582</PRE></UL>
3583
3584<P>The first two rules say that any file with an extension of
3585<VAR>.html</VAR> or <VAR>.htm</VAR> is a HTML file. The third rule
3586says that any file whose first 1024 characters are printable text and
3587starts with the strings <CODE>&lt;HTML&gt;</CODE> or
3588<CODE>&lt;!DOCTYPE</CODE> is a HTML file as well.
3589
3590<P>The first two rules deal solely with the name of the file being
3591typed. This is useful when the original filename is known, however for
3592print files the server doesn't have a filename to work with. The third
3593rule takes care of this possibility and automatically figures out the
3594file type based upon the contents of the file instead.
3595
3596<P>The available tests are:
3597
3598<UL>
3599
3600 <LI><CODE>( expr )</CODE> - Parenthesis for expression grouping
3601
3602 <LI><CODE>+</CODE> - Logical AND
3603
3604 <LI><CODE>,</CODE> or whitespace - Logical OR
3605
3606 <LI><CODE>!</CODE> - Logical NOT
3607
3608 <LI><CODE>match("pattern")</CODE> - Pattern match on filename
3609
3610 <LI><CODE>extension</CODE> - Pattern match on "*.extension"
3611
3612 <LI><CODE>ascii(offset,length)</CODE> - True if bytes are valid
3613 printable ASCII (CR, NL, TAB, BS, 32-126)
3614
3615 <LI><CODE>printable(offset,length)</CODE> - True if bytes are
3616 printable 8-bit chars (CR, NL, TAB, BS, 32-126, 160-254)
3617
3618 <LI><CODE>string(offset,"string")</CODE> - True if bytes are
3619 identical to string
3620
3621 <LI><CODE>contains(offset,range,"string")</CODE> - True if the
3622 range of bytes contains the string
3623
3624 <LI><CODE>char(offset,value)</CODE> - True if byte is identical
3625
3626 <LI><CODE>short(offset,value)</CODE> - True if 16-bit integer
3627 is identical (network or "big-endian" byte order)
3628
3629 <LI><CODE>int(offset,value)</CODE> - True if 32-bit integer is
3630 identical (network or "big-endian" byte order)
3631
3632 <LI><CODE>locale("string")</CODE> - True if current locale
3633 matches string
3634
3635</UL>
3636
3637<P>All numeric values can be in decimal (123), octal (0123), or hexadecimal
fd7cc15d 3638(0x123) as desired.
3639
3640<!-- NEED 2.5in -->
3641<P>Strings can be in quotes, all by themselves, as a string
e75387bc 3642of hexadecimal values, or some combination:
766ec9c5 3643
3644<UL><PRE>
e75387bc 3645"string"
3646'string'
3647string
3648&lt;737472696e67&gt;
3649&lt;7374&gt;ring
766ec9c5 3650</PRE></UL>
3651
e75387bc 3652<P>As shown in the <CODE>text/html</CODE> example, rules can continue on
3653multiple lines using the backslash (\) character. A more complex example is
3654the <CODE>image/jpeg</CODE> rules:
766ec9c5 3655
3656<UL><PRE>
e75387bc 3657image/jpeg jpeg jpg jpe string(0,&lt;FFD8FF&gt;) &amp;&amp;\
3658 (char(3,0xe0) char(3,0xe1) char(3,0xe2) char(3,0xe3)\
3659 char(3,0xe4) char(3,0xe5) char(3,0xe6) char(3,0xe7)\
3660 char(3,0xe8) char(3,0xe9) char(3,0xea) char(3,0xeb)\
3661 char(3,0xec) char(3,0xed) char(3,0xee) char(3,0xef))
766ec9c5 3662</PRE></UL>
3663
e75387bc 3664<P>This rule states that any file with an extension of
3665<VAR>.jpeg</VAR>, <VAR>.jpg</VAR>, or <VAR>.jpe</VAR> is a JPEG file.
3666In addition, any file starting with the hexadecimal string
3667<CODE>&lt;FFD8FF&gt;</CODE> (JPEG Start-Of-Image) followed by a
3668character between and including <CODE>0xe0</CODE> and <CODE>0xef</CODE>
3669(JPEG APPn markers) is also a JPEG file.
e15022a6 3670
9cfa8573 3671<H3>mime.convs</H3>
e15022a6 3672
e75387bc 3673<P>The <VAR>mime.convs</VAR> file defines all of the filter programs that
3674are known to the system. Each line consists of:
e15022a6 3675
3676<UL><PRE>
e75387bc 3677source destination cost program
e15022a6 3678
e75387bc 3679text/plain application/postscript 50 texttops
3680application/vnd.cups-postscript application/vnd.cups-raster 50 pstoraster
3681image/* application/vnd.cups-postscript 50 imagetops
3682image/* application/vnd.cups-raster 50 imagetoraster
e15022a6 3683</PRE></UL>
3684
e75387bc 3685<P>The <I>source</I> field is a MIME type, optionally using a wildcard for
3686the super-type or sub-type (e.g. "text/plain", "image/*", "*/postscript").
e15022a6 3687
e75387bc 3688<P>The <I>destination</I> field is a MIME type defined in the
3689<VAR>mime.types</VAR> file.
e15022a6 3690
e75387bc 3691<P>The <I>cost</I> field defines a relative cost for the filtering
3692operation from 1 to 100. The cost is used to choose between two
3693different sets of filters when converting a file. For example, to convert
3694from <CODE>image/jpeg</CODE> to <CODE>application/vnd.cups-raster</CODE>,
3695you could use the <CODE>imagetops</CODE> and <CODE>pstoraster</CODE>
3696filters for a total cost of 100, or the <CODE>imagetoraster</CODE> filter
3697for a total cost of 50.
e15022a6 3698
e75387bc 3699<P>The <I>program</I> field defines the filter program to run; the
3700special program "-" can be used to make two file types equivalent. The
3701program must accept the standard filter arguments and environment
3702variables described in the CUPS Interface Design Description and CUPS
3703Software Programmers Manual:
e15022a6 3704
3705<UL><PRE>
e75387bc 3706program job user title options [filename]
e15022a6 3707</PRE></UL>
3708
e75387bc 3709<P>If specified, the <I>filename</I> argument defines a file to read
3710when filtering, otherwise the filter must read from the standard input.
3711All filtered output must go to the standard output.
e15022a6 3712
fd7cc15d 3713<!-- NEED 4in -->
3714<H3>Adding Filetypes and Filters</H3>
e15022a6 3715
e75387bc 3716<P>Adding a new file type or filter is fairly straight-forward. Rather
3717than adding the new type and filter to the <VAR>mime.types</VAR> and
3718<VAR>mime.convs</VAR> files which are overwritten when you upgrade to a
3719new version of CUPS, you simple need to create new files with
3720<VAR>.types</VAR> and <VAR>.convs</VAR> extensions in the
3721<VAR>/etc/cups</VAR> directory. We recommend that you use the product
3722or format name, e.g.:
e15022a6 3723
3724<UL><PRE>
e75387bc 3725myproduct.types
3726myproduct.convs
e15022a6 3727</PRE></UL>
3728
e75387bc 3729<P>If you are providing a filter for a common file format or printer,
3730add the company or author name:
e15022a6 3731
e75387bc 3732<UL><PRE>
3733acme-msword.types
3734acme.msword.convs
3735</PRE></UL>
e15022a6 3736
e75387bc 3737<P>This will help to prevent name collisions if you install many
3738different file types and filters.
e15022a6 3739
e75387bc 3740<P>Once you choose the names for these files, create them using your
3741favorite text editor as described earlier in this chapter. Once you
3742have created the files, restart the <CODE>cupsd</CODE> process as
551d3a88 3743described earlier in <A HREF="#RESTARTING">"Restarting the CUPS Server"</A>.
e15022a6 3744
fd7cc15d 3745<H3>Printer Drivers and PPD Files</H3>
e15022a6 3746
e75387bc 3747<P>Most CUPS printer drivers utilize one or more printer-specific filters
3748and a PPD file for each printer model. Printer driver filters are registered
3749via the PPD file using <CODE>cupsFilter</CODE> attributes:
e15022a6 3750
3751<UL><PRE>
e75387bc 3752*cupsFilter: "application/vnd.cups-raster 0 rastertohp"
e15022a6 3753</PRE></UL>
ba8a42d9 3754
e75387bc 3755<P>The filter is specified using the source file type only; the destination
3756file type is assumed to be <CODE>printer/name</CODE> - suitable for sending
3757to the printer.
ba8a42d9 3758
fd7cc15d 3759<H3>Writing Your Own Filter or Printer Driver</H3>
ba8a42d9 3760
e75387bc 3761<P>CUPS supports an unlimited number of file formats and filters, and can
3762handle any printer. If you'd like to write a filter or printer driver for
3763your favorite file format or printer, consult the CUPS Software Programmers
3764Manual for step-by-step instructions.
17bd46bd 3765
2f89d155 3766
fd7cc15d 3767<H1 ALIGN="RIGHT"><A NAME="PRINTING_OTHER">7 - Printing with Other Systems</A></H1>
3768
3769<P>This chapter describes how to print from client systems that use the
3770LPD, Mac OS, or Windows printing protocols.
3771
3772<H2>The Basics</H2>
3773
3774<P>CUPS is based on the IPP protocol, so any system that supports IPP
3775can send jobs to and receive jobs from CUPS automatically. However, not
3776all systems support IPP yet. This chapter will show you how to connect
3777these systems to your CUPS server, either to accept jobs from your
3778server for printing, or to send jobs to your server.
3779
3780<H2>Printing from LPD Clients</H2>
3781
3782<P>CUPS supports limited functionality for LPD-based clients. With LPD you can
3783print files to specific printers, list the queue status, and so forth. However,
3784the automatic client configuration and printer options are not supported by
3785the LPD protocol, so you must manually configure each client for the printers
3786it needs to access.
3787
9cfa8573 3788<P>The <CODE>cups-lpd(8)</CODE> program provides support for LPD
3789clients and can be used from either the <CODE>inetd(8)</CODE> or
3790<CODE>xinetd(8)</CODE> programs. Add the following line to the
3791<VAR>/etc/inetd.conf</VAR> file to enable LPD support on your
3792server through the <CODE>inetd</CODE> program:
fd7cc15d 3793
3794<UL><PRE>
3795printer stream tcp nowait lp /usr/lib/cups/daemon/cups-lpd cups-lpd
3796</PRE></UL>
3797
3798<P>The path to the <CODE>cups-lpd</CODE> may vary depending on your
3799installation.
3800
9cfa8573 3801<P>Once you have added this line, send the <CODE>inetd</CODE>
3802process a <CODE>HUP</CODE> signal or reboot the system:
fd7cc15d 3803
3804<UL><PRE>
3805<B>killall -HUP inetd ENTER</B> [IRIX and some versions of Linux]
551d3a88 3806<B>kill -HUP <I>pid</I> ENTER [Others]</B>
3807<B>reboot ENTER [For all systems if the HUP signal fails]</B>
fd7cc15d 3808</PRE></UL>
3809
9cfa8573 3810<P>If you are using the <CODE>xinetd</CODE> program, create a
3811file named <VAR>/etc/xinetd.d/printer</VAR> containing the
3812following lines:
3813
3814<UL><PRE>
3815service printer
3816{
3817 socket_type = stream
3818 protocol = tcp
3819 wait = no
3820 user = lp
3821 server = /usr/lib/cups/daemon/cups-lpd
3822}
3823</PRE></UL>
3824
3825<P>The <CODE>xinetd</CODE> program automatically reads the new
3826configuration file and enables LPD printing support.
3827
3828<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
3829<TR>
3830 <TD><B>Warning:</B>
3831
3832 <P><CODE>cups-lpd</CODE> currently does not perform any
3833 access control based on the settings in
3834 <VAR>cupsd.conf</VAR> or in the <VAR>hosts.allow</VAR>
3835 or <VAR>hosts.deny</VAR> files used by TCP wrappers.
3836 Therefore, running <CODE>cups-lpd</CODE> on your server
3837 will allow any computer on your network (and perhaps the
3838 entire Internet) to print to your server.
3839
3840 <P>While <CODE>xinetd</CODE> has built-in access control
3841 support, you should use the TCP wrappers package with
3842 <CODE>inetd</CODE> to limit access to only those
3843 computers that should be able to print through your
3844 server.
3845
3846 </TD>
3847</TR>
3848</TABLE></CENTER>
3849
fd7cc15d 3850<H2>Printing to LPD Servers</H2>
3851
3852<P>CUPS provides the <CODE>lpd</CODE> backend for printing to LPD-based
3853servers and printers. Use a device URI of <CODE>lpd://server/name</CODE>
3854to print to a printer on an LPD server, where <CODE>server</CODE>
3855is the hostname or IP address of the server and <CODE>name</CODE> is
3856the queue name.
3857
3858<P>Microsoft Windows NT provides an LPD service under the name "TCP/IP
3859Printing Services". To enable LPD printing on NT, open the "Services"
3860control panel, select the "TCP/IP Printing Services" service, and click
3861on the "Start" button. Any shared printer will then be available via
3862the LPD protocol.
3863
3864<H2>Printing from Mac OS Clients</H2>
3865
3866<P>CUPS does not provide Mac OS support directly. However, there are several
3867free and commercial software packages that do.
3868
3869<H3>Columbia Appletalk Package (CAP)</H3>
3870
551d3a88 3871<P>Because the CAP LaserWriter server (<CODE>lwsrv(8)</CODE>) does
fd7cc15d 3872not support specification of PPD files, we do not recommend that you
3873use CAP with CUPS. However, you can run the <CODE>lpsrv</CODE> program
3874for limited printing with the command:
3875
3876<UL><PRE>
3877lwsrv -n "<I>Name</I>" -p <I>printer</I> -a /usr/lib/adicts -f /usr/lib/LW+Fonts
3878</PRE></UL>
3879
3880<P>where <CODE>Name</CODE> is the name you want to use when sharing the
3881printer, and <CODE>printer</CODE> is the name of the CUPS print queue.
3882
3883<!-- NEED 3in -->
3884<H3>XINET KA/Spool</H3>
3885
3886<P>To use your system as a print server for Mac OS clients,
551d3a88 3887configure each printer using a <CODE>papserver(8)</CODE> in the
fd7cc15d 3888<VAR>/usr/adm/appletalk/services</VAR> file, specifying the
3889corresponding PPD file in the <VAR>/etc/cups/ppd</VAR> directory for
3890each printer. For a printer named <CODE>MyPrinter</CODE> the entry
3891would look like:
3892
3893<UL><PRE>
3894/usr/etc/appletalk/papserver -I -L -P /etc/cups/ppd/MyPrinter.ppd \
3895"Printer Description" MyPrinter
3896</PRE></UL>
3897
3898<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
3899<TR>
3900 <TD>
3901 <B>NOTE:</B>
3902
3903 <P>Enter the text above on a single line without the backslash (\)
3904 character.
3905 </TD>
3906</TR>
3907</TABLE></CENTER>
3908
3909<H3>NetATalk</H3>
3910
3911<P>To use your system as a print server for Mac OS clients,
3912configure each printer in the <VAR>papd.conf</VAR> file, specifying the
3913corresponding PPD file in the <VAR>/etc/cups/ppd</VAR> directory for
3914each printer. For a printer named <CODE>MyPrinter</CODE> the entry
3915would look like:
3916
3917<UL><PRE>
3918Printer Description:MyPrinter@MyServer:\
3919 :pr=|/usr/bin/lp -d MyPrinter:\
3920 :op=daemon:\
6795c5a9 3921 :pd=/etc/cups/ppd/MyPrinter.ppd:
fd7cc15d 3922</PRE></UL>
3923
3924<!-- NEED 2in -->
3925
3926<H2>Printing to Mac OS Servers</H2>
3927
3928<P>CUPS currently does not provide a backend to communicate with a Mac OS
3929server. However, you can write and install a short shell script
3930in the <VAR>/usr/lib/cups/backend</VAR> directory that sends a print file
3931using the appropriate command. The following is a short script that will
3932run the <CODE>papif</CODE> command provided with CAP.
3933
3934<P>After copying this script to <VAR>/usr/lib/cups/backend/cap</VAR>,
3935specify a device URI of <CODE>cap://server/printer</CODE> to use this
3936backend with a print queue.
3937
3938<!-- NEED 8in -->
3939<UL>
3940<PRE>
3941<I>"/usr/lib/cups/backend/cap"</I>
3942#!/bin/sh
3943#
3944# Usage: cap job user title copies options [filename]
3945#
3946
3947# No arguments means show available devices...
3948
3949if test ${#argv} = 0; then
3950 echo "network cap \"Unknown\" \"Mac OS Printer via CAP\""
3951 exit 0
3952fi
3953
3954# Collect arguments...
3955
3956user=$2
3957copies=$4
3958
3959if test ${#argv} = 5; then
3960 # Get print file from stdin; copies have already been handled...
3961 file=/var/tmp/$$.prn
3962 copies=1
3963 cat &gt; $file
3964else
3965 # Print file is on command-line...
3966 file=$6
3967fi
3968
3969# Create a dummy cap.printers file for this printer based
3970# upon a device URI of "cap://server/printer"...
3971
3972echo $PRINTER/$DEVICE_URI | \
3973 awk -F/ '{print $1 "=" $5 ":LaserWriter@" $4}' &gt; /var/tmp/$$.cap
3974
3975CAPPRINTERS=/var/tmp/$$.cap; export CAPPRINTERS
3976
3977# Send the file to the printer, once for each copy. This assumes that you
3978# have properly initialized the cap.printers file...
3979
3980while [ $copies -gt 0 ]; do
3981 papif -n $user &lt; $file
3982
3983 copies=`expr $copies - 1`
3984done
3985
3986# Remove any temporary files...
3987if test ${#argv} = 5; then
3988 /bin/rm -f $file
3989fi
3990
3991/bin/rm -f /var/tmp/$$.cap
3992
3993exit 0
3994</PRE></UL>
3995
3996<!-- NEED 2in -->
3997<H2>Printing from Windows Clients</H2>
3998
3999<P>While CUPS does not provide Windows support directly, the free
4000SAMBA software package does. SAMBA version 2.0.6 is the first release
4001of SAMBA that supports CUPS. You can download SAMBA from:
4002
4003<UL><PRE>
4004<A HREF="http://www.samba.org">http://www.samba.org</A>
4005</PRE></UL>
4006
4007<P>To configure SAMBA for CUPS, edit the <VAR>smb.conf</VAR> file and
4008replace the existing printing commands and options with the line:
4009
4010<UL><PRE>
4011printing = cups
9ae34eb7 4012printcap name = cups
fd7cc15d 4013</PRE></UL>
4014
4015<P>That's all there is to it! Remote users will now be able to browse and
4016print to printers on your system.
4017
9ae34eb7 4018<H3>Exporting Printer Drivers</H3>
4019
4020<P>You can optionally export printer drivers from your CUPS
4021server using the <CODE>cupsaddsmb</CODE> command and the SAMBA
40222.2.0 or higher software.
4023
4024<P>Before you can export the printers you must download the
4025current Adobe PostScript printer drivers from the Adobe web
4026site (<A HREF="http://www.adobe.com/">http://www.adobe.com/</A>).
4027Use the free <CODE>unzip</CODE> software to extract the files
4028from the self-extracting ZIP file containing the drivers; you
4029will need the following files:
4030
4031<UL><PRE>
4032ADFONTS.MFM
4033ADOBEPS4.DRV
4034ADOBEPS4.HLP
4035ADOBEPS5.DLL
4036ADOBEPSU.DLL
4037ADOBEPSU.HLP
4038DEFPRTR2.PPD
4039ICONLIB.DLL
4040PSMON.DLL
4041</PRE></UL>
4042
4043<P>Copy these files to the <VAR>/usr/share/cups/drivers</VAR>
4044directory - you may need to rename some of the files so the
4045filenames are all UPPERCASE.
4046
4047<P>Next, add a <CODE>print$</CODE> share for the printer
4048drivers to your <VAR>smb.conf</VAR> file:
4049
4050<UL><PRE>
4051[print$]
4052 comment = Printer Drivers
4053 path = /etc/samba/drivers
4054 browseable = yes
4055 guest ok = no
4056 read only = yes
4057 write list = root
4058</PRE></UL>
4059
4060<P>The directory for your printer drivers can be anywhere on the
4061system; just make sure it is writable by the users specified by
4062the <CODE>write list</CODE> directive. Also, make sure that you
4063have SAMBA passwords defined for each user in the <CODE>write
4064list</CODE> using the <CODE>smbpasswd(1)</CODE> command.
4065Otherwise you will not be able to authenticate
4066
4067<P>Finally, run the <CODE>cupsaddsmb</CODE> command to export
4068the printer drivers for one or more queues:
4069
4070<UL><PRE>
9cfa8573 4071<B>cupsaddsmb -U root printer1 ... printerN <I>ENTER</I></B>
9ae34eb7 4072</PRE></UL>
4073
4074<P>Running <CODE>cupsaddsmb</CODE> with the <CODE>-a</CODE> option
4075will export all printers:
4076
4077<UL><PRE>
9cfa8573 4078<B>cupsaddsmb -U root -a <I>ENTER</I></B>
9ae34eb7 4079</PRE></UL>
4080
fd7cc15d 4081<H2>Printing to Windows Servers</H2>
4082
4083<P>CUPS can print to Windows servers in one of two ways. The first way uses
4084the LPD protocol on the CUPS system and the "TCP/IP Printing Services" on
4085the Windows system. You can find out more about this configuration in the
4086<A HREF="#LPD">LPD</A> section earlier in this chapter.
4087
4088<P>The second way is through the Microsoft Server Message Block ("SMB")
4089protocol. Support for this protocol is provided with the free SAMBA
4090software package. You can download SAMBA from:
4091
4092<UL><PRE>
4093<A HREF="http://www.samba.org">http://www.samba.org</A>
4094</PRE></UL>
4095
4096<P>To configure CUPS for SAMBA, run the following command:
4097
4098<UL><PRE>
4099<B>ln -s `which smbspool` /usr/lib/cups/backend/smb ENTER</B>
4100</PRE></UL>
4101
4102<P>The <CODE>smbspool(1)</CODE> program is provided with SAMBA starting
4103with SAMBA 2.0.6. Once you have made the link you can configure your
4104printers with one of the following device URIs:
4105
4106<UL><PRE>
4107smb://workgroup/server/sharename
4108smb://server/sharename
4109smb://user:pass@workgroup/server/sharename
4110smb://user:pass@server/sharename
4111</PRE></UL>
4112
4113<P>The <CODE>workgroup</CODE> name need only be specified if your
4114system is using a different workgroup. The <CODE>user:pass</CODE>
4115strings are required when printing to Windows NT servers or to shares
4116with passwords enabled under Windows 95 and 98.
4117
4118
766ec9c5 4119<H1 ALIGN="RIGHT"><A NAME="LICENSE">A - Software License Agreement</A></H1>
2f89d155 4120
766ec9c5 4121<EMBED SRC="../LICENSE.html">
2f89d155 4122
2f89d155 4123
766ec9c5 4124<H1 ALIGN="RIGHT"><A NAME="COMMON_NETWORK">B - Common Network Settings</A></H1>
2f89d155 4125
766ec9c5 4126<P>This appendix covers many of the popular TCP/IP network interfaces
4127and printer servers available on the market today.
17bd46bd 4128
766ec9c5 4129<H2>Configuring a Network Interface</H2>
2f89d155 4130
766ec9c5 4131<P>When you first install a network printer or print server on your
4132LAN, you need to set the Internet Protocol ("IP") address. On most
4133higher-end "workgroup" printers, you can set the address through the
4134printer control panel. However, in most cases you will want to assign
4135the addresses remotely from your workstation. This makes administration
4136a bit easier and avoids assigning duplicate addresses accidentally.
2f89d155 4137
766ec9c5 4138<P>To setup your printer or print server for remote address assignment,
4139you'll need the Ethernet Media Access Control ("MAC") address, also
4140sometimes called a node address, and the IP address you want to use for
4141the device. The Ethernet MAC address can often be found on the printer
4142test page or bottom of the print server.
2f89d155 4143
fd7cc15d 4144<!-- NEED 3in -->
766ec9c5 4145<H3>Configuring the IP Address Using ARP</H3>
17bd46bd 4146
766ec9c5 4147<P>The easiest way to set the IP address of a network device is to use
551d3a88 4148the <CODE>arp(8)</CODE> command. The <CODE>arp</CODE> sends an Address
766ec9c5 4149Resolution Protocol ("ARP") packet to the specified Ethernet MAC address,
4150setting the network device's IP address:
17bd46bd 4151
766ec9c5 4152<UL><PRE>
4153<B>arp -s ip-address ethernet-address ENTER</B>
4154<B>arp -s host.domain.com 08:00:69:00:12:34 ENTER</B>
4155<B>arp -s 192.0.2.2 08:00:69:00:12:34 ENTER</B>
4156</PRE></UL>
17bd46bd 4157
766ec9c5 4158<H3>Configuring the IP Address Using RARP</H3>
17bd46bd 4159
766ec9c5 4160<P>The most flexible way to remotely assign IP addresses under UNIX
4161is through the Reverse Address Resolution Protocol ("RARP"). RARP
4162allows a network device to request an IP address using its Ethernet
4163MAC address, and one or more RARP servers on the network will
4164respond with an ARP packet with the IP address the device can use.
17bd46bd 4165
766ec9c5 4166<P>RARP should be used when you have to manage many printers or print
4167servers, or when you have a network device that does not remember its
4168IP address after a power cycle. If you just have a single printer or
4169print server, the <CODE>arp</CODE> command is the way to go.
4170
4171<P>Some UNIX operating systems use a program called
551d3a88 4172<CODE>rarpd(8)</CODE> to manage RARP. Others, like Linux, support this
766ec9c5 4173protocol in the kernel. For systems that provide the <CODE>rarpd</CODE>
4174program you will need to start it before RARP lookups will work:
17bd46bd 4175
4176<UL><PRE>
766ec9c5 4177<B>rarpd ENTER</B>
17bd46bd 4178</PRE></UL>
4179
766ec9c5 4180<P>Under IRIX you can enable this functionality by default using:
17bd46bd 4181
766ec9c5 4182<UL><PRE>
4183<B>chkconfig rarpd on ENTER</B>
4184</PRE></UL>
17bd46bd 4185
766ec9c5 4186<P>Both the <CODE>rarpd</CODE> program and kernel RARP support read a
4187list of Ethernet and IP addresses from the file <VAR>/etc/ethers</VAR>.
4188Each line contains the Ethernet address (colon delimited) followed by
4189an IP address or hostname like:
17bd46bd 4190
4191<UL><PRE>
766ec9c5 419208:00:69:00:12:34 myprinter.mydomain.com
419308:00:69:00:12:34 192.0.2.2
17bd46bd 4194</PRE></UL>
4195
766ec9c5 4196<P>Add a line to this file and cycle the power on the printer or print
4197server to set its address.
4198
fd7cc15d 4199<!-- NEED 2in -->
766ec9c5 4200<H3>Configuring the IP Address Using BOOTP</H3>
4201
4202<P>The BOOTP protocol is used when you need to provide additional information
4203such as the location of a configuration file to the network interface. Using
551d3a88 4204the standard <CODE>bootpd(8)</CODE> program supplied with UNIX you simply need to
766ec9c5 4205add a line to the <VAR>/etc/bootptab</VAR> file; for IRIX:
17bd46bd 4206
4207<UL><PRE>
766ec9c5 4208myprinter 08:00:69:00:12:34 192.0.2.2 <VAR>myprinter.boot</VAR>
17bd46bd 4209</PRE></UL>
4210
fd7cc15d 4211<!-- NEED 1in -->
766ec9c5 4212<P>Newer versions of <CODE>bootpd</CODE> use a different format:
4213
4214<UL><PRE>
4215myprinter:ha=080069001234:ip=192.0.2.2:<VAR>t144=myprinter.boot</VAR>
4216</PRE></UL>
17bd46bd 4217
766ec9c5 4218<P>The <VAR>myprinter.boot</VAR> file resides in the <VAR>/usr/local/boot</VAR>
4219directory by default. If you do not need to provide a boot file you may leave
9cfa8573 4220the last part of the line blank.</P>
2f89d155 4221
fd7cc15d 4222<!-- NEED 2in -->
4223<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
4224<TR>
4225 <TD>
4226 <B>NOTE:</B>
e75387bc 4227
4228 <P>Some versions of UNIX do not enable the BOOTP service by
4229 default. The <VAR>/etc/inetd.conf</VAR> usually contains a
4230 line for the BOOTP service that can be uncommented if
4231 needed.
fd7cc15d 4232 </TD>
4233</TR>
4234</TABLE></CENTER>
e75387bc 4235
766ec9c5 4236<H2>Verifying the Printer Connection</H2>
2f89d155 4237
766ec9c5 4238<P>To test that the IP address has been successfully assigned and that the
4239printer is properly connected to your LAN, type:
2f89d155 4240
766ec9c5 4241<UL><PRE>
4242<B>ping ip-address ENTER</B>
4243</PRE></UL>
2f89d155 4244
766ec9c5 4245<P>If the connection is working properly you will see something like:
2f89d155 4246
766ec9c5 4247<UL><PRE>
4248<B>ping myprinter ENTER</B>
4249PING myprinter (192.0.2.2): 56 data bytes
425064 bytes from 192.0.2.2: icmp_seq=0 ttl=15 time=5 ms
425164 bytes from 192.0.2.2: icmp_seq=1 ttl=15 time=3 ms
425264 bytes from 192.0.2.2: icmp_seq=2 ttl=15 time=3 ms
425364 bytes from 192.0.2.2: icmp_seq=3 ttl=15 time=3 ms
4254</PRE></UL>
4255
4256<P>If not, verify that the printer or print server is connected to the
4257LAN, it is powered on, the LAN cabling is good, and the IP address is
4258set correctly. You can usually see the current IP address and network
4259status by printing a configuration or test page on the device.
4260
fd7cc15d 4261<!-- NEED 4in -->
766ec9c5 4262<H2>Common Network Interface Settings</H2>
4263
4264<P>Once you have set the IP address you can access the printer or print
4265server using the <CODE>ipp</CODE>, <CODE>lpd</CODE>, or
4266<CODE>socket</CODE> backends. The following is a list of common network
4267interfaces and printer servers and the settings you should use with
4268CUPS:
4269
4270<CENTER><TABLE BORDER="1">
4271<TR VALIGN="TOP" ALIGN="LEFT">
4272 <TH>Model/Manufacturer</TH>
4273 <TH>Device URI(s)</TH>
4274</TR>
4275<TR ALIGN="LEFT" VALIGN="TOP">
4276 <TD>Apple LaserWriter</TD>
4277 <TD>lpd://<I>address</I>/PASSTHRU</TD>
4278</TR>
fd7cc15d 4279<!-- NEED 1in -->
766ec9c5 4280<TR ALIGN="LEFT" VALIGN="TOP">
4281 <TD>Axis w/o IPP<BR>
4282 <A HREF="#AXIS">(see directions)</A></TD>
4283 <TD>socket://<I>address</I>:9100<BR>
4284 socket://<I>address</I>:9101<BR>
4285 socket://<I>address</I>:9102</TD>
4286</TR>
fd7cc15d 4287<!-- NEED 1in -->
766ec9c5 4288<TR ALIGN="LEFT" VALIGN="TOP">
4289 <TD>Axis w/IPP</TD>
4290 <TD>ipp://<I>address</I>/LPT1<BR>
4291 ipp://<I>address</I>/LPT2<BR>
4292 ipp://<I>address</I>/COM1</TD>
4293</TR>
fd7cc15d 4294<!-- NEED 1in -->
766ec9c5 4295<TR ALIGN="LEFT" VALIGN="TOP">
4296 <TD>Castelle LANpress<SUP>TM</SUP></TD>
4297 <TD>lpd://<I>address</I>/pr1<BR>
4298 lpd://<I>address</I>/pr2<BR>
4299 lpd://<I>address</I>/pr3</TD>
4300</TR>
fd7cc15d 4301<!-- NEED 1in -->
766ec9c5 4302<TR ALIGN="LEFT" VALIGN="TOP">
4303 <TD>DPI NETPrint</TD>
4304 <TD>lpd://<I>address</I>/pr1<BR>
4305 lpd://<I>address</I>/pr2<BR>
4306 lpd://<I>address</I>/pr3</TD>
4307</TR>
4308<TR ALIGN="LEFT" VALIGN="TOP">
551d3a88 4309 <TD>EFI&reg; Fiery&reg; RIP</TD>
766ec9c5 4310 <TD>lpd://<I>address</I>/print</TD>
4311</TR>
4312<TR ALIGN="LEFT" VALIGN="TOP">
4313 <TD>EPSON&reg; Multiprotocol Ethernet Interface Board</TD>
4314 <TD>socket://<I>address</I></TD>
4315</TR>
fd7cc15d 4316<!-- NEED 1in -->
766ec9c5 4317<TR ALIGN="LEFT" VALIGN="TOP">
4318 <TD>Extended System ExtendNET</TD>
4319 <TD>lpd://<I>address</I>/pr1<BR>
4320 lpd://<I>address</I>/pr2<BR>
4321 lpd://<I>address</I>/pr3</TD>
4322</TR>
fd7cc15d 4323<!-- NEED 1in -->
766ec9c5 4324<TR ALIGN="LEFT" VALIGN="TOP">
4325 <TD>Hewlett Packard JetDirect w/o IPP</TD>
4326 <TD>socket://<I>address</I>:9100<BR>
4327 socket://<I>address</I>:9101<BR>
4328 socket://<I>address</I>:9102</TD>
4329</TR>
fd7cc15d 4330<!-- NEED 1in -->
766ec9c5 4331<TR ALIGN="LEFT" VALIGN="TOP">
4332 <TD>Hewlett Packard JetDirect w/IPP</TD>
4333 <TD>ipp://<I>address</I>/ipp<BR>
4334 ipp://<I>address</I>/ipp/port1<BR>
4335 ipp://<I>address</I>/ipp/port2<BR>
4336 ipp://<I>address</I>/ipp/port3</TD>
4337</TR>
fd7cc15d 4338<!-- NEED 1in -->
766ec9c5 4339<TR ALIGN="LEFT" VALIGN="TOP">
4340