doc/sam.shtml

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