sam.shtml   [plain text]


<HTML>
<HEAD>
	<META NAME="COPYRIGHT" CONTENT="Copyright 1997-2005, All Rights Reserved">
	<META NAME="DOCNUMBER" CONTENT="CUPS-SAM-1.1.23">
	<META NAME="Author" CONTENT="Easy Software Products">
	<TITLE>CUPS Software Administrators Manual</TITLE>
</HEAD>
<BODY>

<H1 ALIGN="RIGHT">Preface</H1>

<P>This software administrators manual provides printer administration
information for the Common UNIX Printing System<SUP>TM</SUP>
("CUPS<SUP>TM</SUP>"), version 1.1.23.

<EMBED SRC="system-overview.shtml">

<!-- NEED 3in -->
<H2>Document Overview</H2>

<P>This software administrators manual is organized into the following sections:</P>

<UL>
	<LI><A HREF="#OVERVIEW">1 - Printing System Overview</A>
	<LI><A HREF="#BUILDING_INSTALLING">2 - Building and Installing CUPS</A>
	<LI><A HREF="#MANAGING_PRINTERS">3 - Managing Printers</A>
	<LI><A HREF="#PRINTER_CLASSES">4 - Printer Classes</A>
	<LI><A HREF="#CLIENT_SETUP">5 - Client Setup</A>
	<LI><A HREF="#PRINTING_MANAGEMENT">6 - Printing System Management</A>
	<LI><A HREF="#PRINTING_OTHER">7 - Printing with Other Systems</A>
	<LI><A HREF="#LICENSE">A - Software License Agreement</A>
	<LI><A HREF="#COMMON_NETWORK">B - Common Network Settings</A>
	<LI><A HREF="#PRINTER_DRIVERS">C - Printer Drivers</A>
	<LI><A HREF="#FILES">D - List of Files</A>
	<LI><A HREF="#FAQ">E - Troubleshooting Common Problems</A>
</UL>

<H2>Notation Conventions</H2>

<P>Various font and syntax conventions are used in this guide. Examples and
their meanings and uses are explained below:

<CENTER><TABLE WIDTH="80%">
<TR>
	<TH>Example</TH>
	<TD>&nbsp;&nbsp;&nbsp;</TD>
	<TH>Description</TH>
</TR>
<TR><TD>&nbsp;</TD></TR>
<TR VALIGN="TOP">
	<TD><CODE>lpstat</CODE><BR>
	<CODE>lpstat(1)</CODE></TD>

	<TD>&nbsp;&nbsp;&nbsp;</TD>

	<TD>The names of commands; the first mention of a command or
	function in a chapter is followed by a manual page section
	number.</TD>
</TR>
<TR><TD>&nbsp;</TD></TR>
<TR VALIGN="TOP">
	<TD><VAR>/var</VAR><BR>
	<VAR>/usr/share/cups/data/testprint.ps</VAR></TD>

	<TD>&nbsp;&nbsp;&nbsp;</TD>

	<TD>File and directory names.</TD>
</TR>
<TR><TD>&nbsp;</TD></TR>
<TR VALIGN="TOP">
	<TD NOWRAP><TT>Request ID is Printer-123</TT></TD>

	<TD>&nbsp;&nbsp;&nbsp;</TD>

	<TD>Screen output.</TD>
</TR>
<TR><TD>&nbsp;</TD></TR>
<TR VALIGN="TOP">
	<TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD>

	<TD>&nbsp;&nbsp;&nbsp;</TD>

	<TD>Literal user input; special keys like <KBD>ENTER</KBD> are
	in ALL CAPS.</TD>
</TR>
<TR><TD>&nbsp;</TD></TR>
<TR VALIGN="TOP">
	<TD>12.3</TD>

	<TD>&nbsp;&nbsp;&nbsp;</TD>

	<TD>Numbers in the text are written using the period (.) to indicate
	the decimal point.</TD>
</TR>
</TABLE></CENTER>

<!-- NEED 3in -->
<H2>Abbreviations</H2>

The following abbreviations are used throughout this manual:

<UL>
<DL>

	<DT>kb
	<DD>Kilobytes, or 1024 bytes<BR>&nbsp;

	<DT>Mb
	<DD>Megabytes, or 1048576 bytes<BR>&nbsp;

	<DT>Gb
	<DD>Gigabytes, or 1073741824 bytes<BR>&nbsp;

</DL>
</UL>

<H2>Other References</H2>

<UL>
<DL>

	<DT>CUPS Software Programmers Manual

	<DD>A programmer guide for interfacing with and/or extending the CUPS
	software.<BR>&nbsp;

	<DT>CUPS Software Users Manual

	<DD>An end-user guide for using the CUPS software.<BR>&nbsp;

</DL>
</UL>


<EMBED SRC="printing-overview.shtml">


<H1 ALIGN="RIGHT"><A NAME="BUILDING_INSTALLING">2 - Building and Installing CUPS</A></H1>

<P>This chapter shows how to build and install the Common UNIX Printing System.
If you are installing a binary distribution from the CUPS web site, proceed to
the section titled, <A HREF="#BINARY">Installing a Binary Distribution</A>.

<H2>Installing a Source Distribution</H2>

<P>This section describes how to compile and install CUPS on your system
from the source code.

<H3><A NAME="REQUIREMENTS">Requirements</A></H3>

<P>You'll need ANSI-compliant C and C++ compilers to build CUPS on your
system. As its name implies, CUPS is designed to run on the UNIX
operating system, however the CUPS interface library and most of the
filters and backends supplied with CUPS should also compile and run
under Microsoft Windows.

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

<UL><PRE>
<A HREF="ftp://ftp.easysw.com/pub/libraries">ftp://ftp.easysw.com/pub/libraries</A>
</PRE></UL>

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

<UL><PRE>
<A HREF="ftp://ftp.gnu.org/pub/groff">ftp://ftp.gnu.org/pub/groff</A>
</PRE></UL>

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

<UL><PRE>
<A HREF="http://www.easysw.com/htmldoc">http://www.easysw.com/htmldoc</A>
</PRE></UL>

<P>Finally, you'll need a <CODE>make</CODE> program that
understands the <CODE>include</CODE> directive - FreeBSD,
NetBSD, and OpenBSD developers should use the <CODE>gmake</CODE>
program.

<H3><A NAME="COMPILING">Compiling CUPS</A></H3>

<P>CUPS uses GNU autoconf to configure the makefiles and source code
for your system. Type the following command to configure CUPS for your
system:

<UL><PRE>
<B>./configure ENTER</B>
</PRE></UL>

<P>The default installation will put the CUPS software in the
<VAR>/etc</VAR>, <VAR>/usr</VAR>, and <VAR>/var</VAR> directories on
your system, which will overwrite any existing printing commands on
your system. Use the <CODE>--prefix</CODE> option to install the CUPS
software in another location:

<UL><PRE>
<B>./configure --prefix=/some/directory ENTER</B>
</PRE></UL>

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

<UL><PRE>
<B>setenv CFLAGS "-I/some/directory" ENTER</B>
<B>setenv CXXFLAGS "-I/some/directory" ENTER</B>
<B>setenv LDFLAGS "-L/some/directory" ENTER</B>
<B>setenv DSOFLAGS "-L/some/directory" ENTER</B>
<B>./configure ... ENTER</B>
</PRE></UL>

<P>or:

<UL><PRE>
<B>CFLAGS="-I/some/directory"; export CFLAGS ENTER</B>
<B>CXXFLAGS="-I/some/directory"; export CXXFLAGS ENTER</B>
<B>LDFLAGS="-L/some/directory"; export LDFLAGS ENTER</B>
<B>DSOFLAGS="-L/some/directory"; export DSOFLAGS ENTER</B>
<B>./configure ... ENTER</B>
</PRE></UL>

<P>To enable support for encryption, you'll also want to add the
"--enable-ssl" option:

<UL><PRE>
./configure --enable-ssl
</PRE></UL>

<P>SSL and TLS support require the OpenSSL library, available at:

<UL><PRE>
<A HREF="http://www.openssl.org">http://www.openssl.org</A>
</PRE></UL>

<P>If the OpenSSL headers and libraries are not installed in the
standard directories, use the <CODE>--with-openssl-includes</CODE>
and <CODE>--with-openssl-libs</CODE> options:</P>

<UL><PRE>
./configure --enable-ssl \
    --with-openssl-includes=/foo/bar/include \
    --with-openssl-libs=/foo/bar/lib
</PRE></UL>

<P>Once you have configured things, just type:

<UL><PRE>
<B>make ENTER</B>
</PRE></UL>

<P>to build the software.

<!-- NEED 4in -->
<H3><A NAME="INSTALLING">Installing the Software</A></H3>

<P>Use the "install" target to install the software:

<UL><PRE>
<B>make install ENTER</B>
</PRE></UL>

<CENTER><TABLE WIDTH="80%" BORDER="1" BGCOLOR="#cccccc" CELLPADDING="5">
<TR>
	<TD>
	<B>WARNING:</B>
	
	<P>Installing CUPS will overwrite your existing printing
	system. If you experience difficulties with the CUPS software
	and need to go back to your old printing system, you will need
	to reinstall the old printing system from your operating system CDs.
	</TD>
</TR>
</TABLE></CENTER>

<H3><A NAME="RUNNING">Running the Software</A></H3>

<P>Once you have installed the software you can start the CUPS server by
typing:

<UL><PRE>
<B>/usr/sbin/cupsd ENTER</B>
</PRE></UL>

<!-- NEED 4in -->
<H2><A NAME="BINARY">Installing a Binary Distribution</A></H2>

<P>CUPS comes in a variety of binary distribution formats. Easy
Software Products provides binaries in TAR format with installation and
removal scripts ("portable" distributions), and in RPM and DPKG formats
for Red Hat and Debian-based distributions.  Portable distributions are
available for all platforms, while the RPM and DPKG distributions are
only available for Linux.

<CENTER><TABLE WIDTH="80%" BORDER="1" BGCOLOR="#cccccc" CELLPADDING="5">
<TR>
	<TD>
	<B>WARNING:</B>
	
	<P>Installing CUPS will overwrite your existing printing
	system. If you experience difficulties with the CUPS software
	and need to go back to your old printing system, you will need
	to remove the CUPS software with the provided script and/or
	reinstall the old printing system from your operating system CDs.
	</TD>
</TR>
</TABLE></CENTER>


<H3><A NAME="PORTABLE-BINARY">Installing a Portable Distribution</A></H3>

<P>To install the CUPS software from a portable distribution you will
need to be logged in as root; doing an <CODE>su</CODE> is good enough.
Once you are the root user, run the installation script with:

<UL><PRE>
<B>./cups.install ENTER</B>
</PRE></UL>

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

<!-- NEED 2in -->
<H3><A NAME="RPM-BINARY">Installing an RPM Distribution</A></H3>

<P>To install the CUPS software from an RPM distribution you will need
to be logged in as root; doing an <CODE>su</CODE> is good enough. Once
you are the root user, run RPM with:

<UL><PRE>
<B>rpm -e lpr</B>
<B>rpm -i cups-1.1-linux-M.m.n-intel.rpm ENTER</B>
</PRE></UL>

<P>After a short delay the CUPS software will be
installed and the scheduler will be started automatically.

<H3><A NAME="DPKG-BINARY">Installing an Debian Distribution</A></H3>

<P>To install the CUPS software from a Debian distribution you will
need to be logged in as root; doing an <CODE>su</CODE> is good enough.
Once you are the root user, run dpkg with:

<UL><PRE>
<B>dpkg -i cups-1.1-linux-M.m.n-intel.deb ENTER</B>
</PRE></UL>

<P>After a short delay the CUPS software will be installed and the
scheduler will be started automatically.


<H1 ALIGN="RIGHT"><A NAME="MANAGING_PRINTERS">3 - Managing Printers</A></H1>

<P>This chapter describes how to add your first printer and how to
manage your printers.

<H2>The Basics</H2>

<P>Each printer queue has a name associated with it; the printer name
must start with any printable character except " ", "/", and "@".  
It can contain up to 127 letters, numbers, and the underscore (_). 
Case is not significant, e.g. "PRINTER", "Printer",
and "printer" are considered to be the same name.

<P>Printer queues also have a device associated with them. The device can be
a parallel port, a network interface, and so forth. Devices within CUPS use
Uniform Resource Identifiers ("URIs") which are a more general form of
Uniform Resource Locators ("URLs") that are used in your web browser. For
example, the first parallel port in Linux usually uses a device URI of
<CODE>parallel:/dev/lp1</CODE>.

<!-- NEED 2.5in -->
<P>You can see a complete list of supported devices by running the
<CODE>lpinfo(8)</CODE> command:

<UL><PRE>
<B>lpinfo -v ENTER</B>
network socket
network http
network ipp
network lpd
direct parallel:/dev/lp1
serial serial:/dev/ttyS1?baud=115200
serial serial:/dev/ttyS2?baud=115200
direct usb:/dev/usb/lp0
network smb
</PRE></UL>

<P>The <CODE>-v</CODE> option specifies that you want a list of available
devices. The first word in each line is the type of device (direct, file,
network, or serial) and is followed by the device URI or method name for
that device. File devices have device URIs of the form
<CODE>file:/directory/filename</CODE> while network devices use the more
familiar <CODE>method://server</CODE> or <CODE>method://server/path</CODE>
format.

<P>Finally, printer queues usually have a PostScript Printer Description
("PPD") file associated with them. PPD files describe the capabilities of
each printer, the page sizes supported, etc., and are used for PostScript
and non-PostScript printers. CUPS includes PPD files for HP LaserJet, HP
DeskJet, EPSON 9-pin, EPSON 24-pin, and EPSON Stylus printers.

<H2>Adding Your First Printer</H2>

<P>CUPS provides two methods for adding printers: a command-line
program called <CODE>lpadmin(8)</CODE> and a Web interface. The
<CODE>lpadmin</CODE> command allows you to perform most printer
administration tasks from the command-line and is located in
<VAR>/usr/sbin</VAR>. The Web interface is located at:

<UL><PRE>
<A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
</PRE></UL>

<P>and steps you through printer configuration. If you don't like
command-line interfaces, try the <A HREF="#ADD_WEB">Web interface</A> instead.

<H3>Adding Your First Printer from the Command-Line</H3>

<P>Run the <CODE>lpadmin</CODE> command with the <CODE>-p</CODE> option to add a
printer to CUPS:

<UL><PRE>
<B>/usr/sbin/lpadmin -p <I>printer</I> -E -v <I>device</I> -m <I>ppd</I> ENTER</B>
</PRE></UL>

<P>For a HP DeskJet printer connected to the parallel port this would look
like:

<UL><PRE>
<B>/usr/sbin/lpadmin -p DeskJet -E -v parallel:/dev/lp1 -m deskjet.ppd ENTER</B>
</PRE></UL>

<P>Similarly, a HP LaserJet printer using a JetDirect network interface at
IP address 11.22.33.44 would be added with the command:

<UL><PRE>
<B>/usr/sbin/lpadmin -p LaserJet -E -v socket://11.22.33.44 -m laserjet.ppd ENTER</B>
</PRE></UL>

<P>As you can see, <CODE>deskjet.ppd</CODE> and <CODE>laserjet.ppd</CODE> are
the PPD files for the HP DeskJet and HP LaserJet drivers included with CUPS.
You'll find a complete list of PPD files and the printers they will work with
in <A HREF="#PRINTER_DRIVERS">Appendix C, "Printer Drivers"</A>.


<P>For a dot matrix printer connected to the serial port, this might look like:

<UL><PRE>
<B>/usr/sbin/lpadmin -p DotMatrix -E -m epson9.ppd \
    -v serial:/dev/ttyS0?baud=9600+size=8+parity=none+flow=soft <I>ENTER</I></B>
</PRE></UL>

<P>Here you specify the serial port (e.g. S0,S1, d0, d1), baud rate 
(e.g. 9600, 19200, 38400, 115200, etc.), number of bits, parity, and flow control.
If you do not need flow control, delete the "+flow=soft" portion.


<H3><A NAME="ADD_WEB">Adding Your First Printer from the Web</A></H3>

<P>The CUPS web server provides a user-friendly "wizard" interface for
adding your printers. Rather than figuring out which device URI and PPD file
to use, you can instead click on the appropriate listings and fill in some
simple information. Enter the following URL in your web browser to begin:

<UL><PRE>
<A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
</PRE></UL>

<P>Click on the <VAR>Add Printer</VAR> button to add a printer.

<H2>Managing Printers from the Command-Line</H2>

<P>The <CODE>lpadmin</CODE> command enables you to perform most printer
administration tasks from the command-line. You'll find <CODE>lpadmin</CODE>
in the <VAR>/usr/sbin</VAR> directory.

<H3>Adding and Modifying Printers</H3>

<P>Run the <CODE>lpadmin</CODE> command with the <CODE>-p</CODE> option
to add or modify a printer:

<UL><PRE>
<B>/usr/sbin/lpadmin -p <I>printer</I> <I>options</I> ENTER</B>
</PRE></UL>

<P>The <I>options</I> arguments can be any of the following:

<UL>
<DL>

	<DT>-c <I>class</I>

	<DD>Adds the named printer to printer class <VAR>class</VAR>.
	If the class does not exist then it is created.

	<DT>-i <I>interface</I>

	<DD>Copies the named <VAR>interface</VAR> script to the printer.
	Interface scripts are used by System V printer drivers. Since
	all filtering is disabled when using an interface script, scripts
	generally should not be used unless there is no other driver for
	a printer.

	<DT>-m <I>model</I>

        <DD>Specifies a standard printer driver which is usually a PPD
        file. PPD's are usually stored under the <VAR>/usr/share/cups/model/</VAR>
        directory structure.  A list of all available models can be displayed 
        using the <CODE>lpinfo</CODE> command with the <CODE>-m</CODE> option. 
        A list of printer drivers included with CUPS can be found in
	<A HREF="#PRINTER_DRIVERS">Appendix C, "Printer Drivers"</A>.

	<DT>-r <I>class</I>

	<DD>Removes the named printer from printer class <VAR>class</VAR>.
	If the resulting class becomes empty then it is removed.

	<DT>-v <I>device-uri</I>

	<DD>Sets the device for communicating with the printer. If a
	job is currently printing on the named printer then the job
	will be restarted and sent to the new device.

	<DT>-D <I>info</I>

	<DD>Provides a textual description of the printer, e.g.
	"John's Personal Printer".

	<DT>-E

	<DD>Enables the printer and accepts job. This option is
	equivalent to running the <CODE>enable(1)</CODE> and
	<CODE>accept(8)</CODE> commands on the printer.

	<DT>-L <I>location</I>

	<DD>Provides a textual location for the printer, e.g.
	"Computer Lab 5".

	<DT>-P <I>ppd-file</I>

	<DD>Specifies a local PPD file for the printer driver.

</DL>
</UL>

<H3>Deleting Printers</H3>

<P>Run the <CODE>lpadmin</CODE> command with the <CODE>-x</CODE> option
to delete a printer:

<UL><PRE>
<B>/usr/sbin/lpadmin -x <I>printer</I> ENTER</B>
</PRE></UL>

<H3>Setting the Default Printer</H3>

<P>Run the <CODE>lpadmin</CODE> command with the <CODE>-d</CODE> option
to set a default printer:

<UL><PRE>
<B>/usr/sbin/lpadmin -d <I>printer</I> ENTER</B>
</PRE></UL>

<P>The default printer can be overridden by the user using the
<CODE>lpoptions(1)</CODE> command.

<H3>Starting and Stopping Printers</H3>

<P>The <CODE>enable</CODE> and <CODE>disable</CODE> commands start and stop
printer queues, respectively:

<UL><PRE>
<B>/usr/bin/enable <I>printer</I> ENTER</B>
<B>/usr/bin/disable <I>printer</I> ENTER</B>
</PRE></UL>

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

<H3>Accepting and Rejecting Print Jobs</H3>

<P>The <CODE>accept</CODE> and <CODE>reject</CODE> commands accept and reject
print jobs for the named printer, respectively:

<UL><PRE>
<B>/usr/sbin/accept <I>printer</I> ENTER</B>
<B>/usr/sbin/reject <I>printer</I> ENTER</B>
</PRE></UL>

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

<H3>Setting Quotas on a Printer</H3>

<P>CUPS supports page and size-based quotas for each printer.
The quotas are tracked individually for each user, but a single set of
limits applies to all users for a partiuclar printer. For example, you
can limit every user to 5 pages per day on an expensive printer, but
you cannot limit every user except Johnny.</P>

<P>The <I>job-k-limit</I>, <I>job-page-limit</I>, and <I>job-quota-peiod</I>
options determine whether and how quotas are enforced for a printer.
The <I>job-quota-period</I> option determines the time interval for
quota tracking. The interval is expressed in seconds, so a day is
86,400, a week is 604,800 and a month is 2,592,000 seconds. The
<I>job-k-limit</I> option specifies the job size limit in killobytes. The 
<I>job-page-limit</I> option specifies the number of pages limit.</P>

<P>For quotas to be enforced, the period and at least one of the limits
must be set to a non-zero value. The following options will enable
quotas:</P>

<UL>
<PRE>
<B>/usr/sbin/lpadmin -p <I>printer</I> -o job-quota-period=604800 \
    -o job-k-limit=1024 <I>ENTER</I></B>
<B>/usr/sbin/lpadmin -p <I>printer</I> -o job-quota-period=604800 \
    -o job-page-limit=100 <I>ENTER</I></B>
</PRE>
</UL>

<P>Or, you can combine all three options on the same line.</P>

<H3>Restricting User Access to a Printer</H3>

<P>The <CODE>-u</CODE> option of the <CODE>lpadmin</CODE> command controls which users can
print to a printer. The default configuration allows all users to print
to a printer:</P>

<UL>
<PRE>
<B>/usr/sbin/lpadmin -p <I>printer</I> -u allow:all <I>ENTER</I></B>
</PRE>
</UL>

<P>CUPS supports allow and deny lists so that you can specify a
list of users who are allowed to print or not allowed to print. Along
with your list of users, you can specify whether they are allowed or
not allowed to use the printer:</P>

<UL>
<PRE>
<B>/usr/sbin/lpadmin -p <I>printer</I> -u allow:peter,paul,mary <I>ENTER</I></B>
</PRE>
</UL>

<P>This command allows peter, paul, and mary to print to the named
printer, but all other users cannot print. The command:</P>

<UL>
<PRE>
<B>/usr/sbin/lpadmin -p <I>printer</I> -u deny:peter,paul,mary <I>ENTER</I></B>
</PRE>
</UL>

<P>has the opposite effect. All users except peter, paul, and mary will
be able to print to the named printer.</P>

<P>You can control access by UNIX groups as well by placing an
"@" character before each group name. The command:</P>

<UL>
<PRE>
<B>/usr/sbin/lpadmin -p <I>printer</I> -u allow:peter,paul,mary,@printgods <I>ENTER</I></B>
</PRE>
</UL>

<P>allows the users peter, paul, and mary to print, as well as
any user in the printgods group to print.

<CENTER>
<TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
<TR>
	<TD><B>NOTE:</B>

	<P>The <I>allow</I> and <I>deny</I> options are not cummulative. That
	is, you must provide the complete list of users to allow or deny each
	time.</P>

	<P>Also, CUPS only maintains one list of users - the list can
	allow or deny users from printing. If you specify an allow list and
	then specify a deny list, the deny list will replace the allow list -
	only one list is active at any time.</P>

	</TD>
</TR>
</TABLE>
</CENTER>

<H2>Managing Printers from the Web</H2>

<P>The Web interface is located at:

<UL><PRE>
<A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
</PRE></UL>

<P>From there you can perform all printer management tasks with a few
simple mouse clicks.


<H1 ALIGN="RIGHT"><A NAME="PRINTER_CLASSES">4 - Printer Classes</A></H1>

<P>This chapter describes what printer classes are and how to manage them.

<H2>The Basics</H2>

<P>CUPS provides collections of printers called <I>printer classes</I>. Jobs
sent to a class are forwarded to the first available printer in the class.
Classes can themselves be members of other classes, so it is possible for
you to define very large, distributed printer classes for high-availability
printing.

<P>CUPS also supports <I>implicit classes</I>. Implicit classes work just
like printer classes, but they are created automatically based upon the
available printers and classes on the network. This allows you to setup
multiple print servers with identical printer configurations and have the
client machines send their print jobs to the first available server. If
one or more servers go down, the jobs are automatically redirected to the
servers that are running, providing fail-safe printing.

<H2>Managing Printer Classes from the Command-Line</H2>

<P>Run the <CODE>lpadmin</CODE> command with the <CODE>-p</CODE> and <CODE>-c</CODE> options
to add a printer to a class:

<UL><PRE>
<B>/usr/sbin/lpadmin -p <I>printer</I> -c <I>class</I> ENTER</B>
</PRE></UL>

<P>The <I>class</I> is created automatically if it doesn't exist. To remove a
printer from a class use the <CODE>-r</CODE> option:

<UL><PRE>
<B>/usr/sbin/lpadmin -p <I>printer</I> -r <I>class</I> ENTER</B>
</PRE></UL>

<P>To remove the entire class just use the <CODE>-x</CODE> option:

<UL><PRE>
<B>/usr/sbin/lpadmin -x <I>class</I> ENTER</B>
</PRE></UL>

<H2>Managing Printer Classes from the Web Interface</H2>

<P>The Web interface is located at:

<UL><PRE>
<A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
</PRE></UL>

<P>The <VAR>Add Class</VAR> and <VAR>Modify Class</VAR> interfaces provide a
list of available printers; click on the printers of interest to add them to
the class.

<H2>Implicit Classes</H2>

<P>A noted earlier, implicit classes are created automatically from the
available network printers and classes. To disable this functionality,
set the <A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
directive to <CODE>Off</CODE> in the <CODE>cupsd.conf</CODE> file. You
will find more information on doing this in
<A HREF="#PRINTING_MANAGEMENT">Chapter 6, "Printing System
Management"</A>.


<H1 ALIGN="RIGHT"><A NAME="CLIENT_SETUP">5 - Client Setup</A></H1>

<P>This chapter discusses several ways to configure CUPS clients for
printing.

<H2>The Basics</H2>

<P>A client is any machine that sends print jobs to another machine for
final printing. Clients can also be servers if they communicate directly with
any printers of their own.

<P>CUPS supports several methods of configuring client machines:

<UL>
	<LI><A HREF="#CLIENT_MANUAL">Manual configuration of print queues.</A>
	<LI><A HREF="#CLIENT_SERVER">Specifying a single server for printing.</A>
	<LI><A HREF="#CLIENT_AUTO">Automatic configuration of print queues.</A>
	<LI><A HREF="#CLIENT_POLL">Specifying multiple servers for printing.</A>
	<LI><A HREF="#CLIENT_RELAY">Relaying printers to other clients.</A>
</UL>

<H3><A NAME="CLIENT_MANUAL">Manual Configuration of Print Queues</A></H3>

<P>The most tedious method of configuring client machines is to configure
each remote queue by hand using the <CODE>lpadmin</CODE> command:

<UL><PRE>
<B>lpadmin -p <I>printer</I> -E -v ipp://<I>server</I>/printers/<I>printer</I> ENTER</B>
</PRE></UL>

<P>The <CODE>printer</CODE> name is the name of the printer on the server
machine. The <CODE>server</CODE> name is the hostname or IP address of the
server machine. Repeat the <CODE>lpadmin</CODE> command for each remote
printer you wish to use.</P>

<CENTER>
<TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
	<TR>
	<TD><B> NOTE:</B>
	<P>Manual configuration of print queues is not recommended for large
	numbers of client machines because of the administration nightmare it
	creates. For busy networks, consider subnetting groups of clients and
	polling and relaying printer information instead.</P>
	</TD>
	</TR>
</TABLE>
</CENTER>

<H3><A NAME="CLIENT_SERVER">Specifying a Single Server for Printing</A></H3>

<P>CUPS can be configured to run without a local spooler and send all
jobs to a single server. However, if that server goes down then all
printing will be disabled. Use this configuration only as absolutely needed.

<P>The default server is normally "localhost". To override the default
server create a file named <VAR>/etc/cups/client.conf</VAR> and add
a line reading:

<UL><PRE>
ServerName <I>server</I>
</PRE></UL>

<P>to the file. The <VAR>server</VAR> name can be the hostname or IP address
of the default server.

<P>The default server can also be customized on a per-user basis. To set a
user-specific server create a file named <VAR>~/.cupsrc</VAR> and add a line
reading:

<UL><PRE>
ServerName <I>server</I>
</PRE></UL>

<P>to the file. The <VAR>server</VAR> name can be the hostname or IP
address of the default server.

<H3><A NAME="CLIENT_AUTO">Automatic Configuration of Print Queues</A></H3>

<P>CUPS supports automatic client configuration of printers on the same
subnet. To configure printers on the same subnet, <I>do nothing</I>.
Each client should see the available printers within 30 seconds
automatically. The printer and class lists are updated automatically as
printers and servers are added or removed.

<P>If you want to see printers on other subnets as well, use the
<A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A> 
directive as described next.</P>

<CENTER>
<TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
	<TR>
	<TD><B> NOTE:</B>
	<P>The<A HREF="#BrowseAddress"> <CODE>BrowseAddress</CODE></A> directive
	enables broadcast traffic from your server. The default configuration
	braodcasts printer information every 30 seconds. Although this printer
	information does not use much bandwidth, typically about 80 bytes per
	printer, it can add up with large numbers of servers and printers.</P>
	<P>Use the <A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A> 
	and <A HREF="#BrowseTimeout"><CODE>BrowseTimeout</CODE></A> directives to tune
	the amount of data that is added to your network load. In addition,
	subnets can be used to minimize the amount of traffic that is carried
	by the &quot;backbone&quot; of your large network.</P>
	</TD>
	</TR>
</TABLE>
</CENTER>

<H3><A NAME="CLIENT_POLL">Specifying Multiple Servers for Printing</A></H3>

<P>If you have CUPS servers on different subnets, then you should configure
CUPS to poll those servers. Polling provides the benefits of automatic
configuration without significant configuration on the clients, and multiple
clients on the same subnet can share the same configuration information.

<P>Polling is enabled by specifying one or more 
<A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A> 
directives in the <VAR>/etc/cups/cupsd.conf</VAR> file. 
For information on making these changes, see 
<A HREF="#PRINTING_MANAGEMENT">Chapter 6, "Printing System Management"</A>.

<P>Multiple <A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A> lines can
be used to poll multiple CUPS servers. To limit the amount of
polling you do from client machines, you can have only one of the
clients do the polling and relay that information to the others on the
same subnet (described next).</P>

<H3><A NAME="CLIENT_RELAY">Relaying Printers to Other Clients</A></H3>

<P>When you have clients and servers spread across multiple subnets, the
polling method is inefficient. CUPS provides a 
<A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A> directive that enables a 
single client to relay (broadcast) the polled printer information to the local subnet.</P>

<P>For example, Server A and Server B are on subnet 1 and subnet 2,
while the clients are on subnet 3.
To provide printers to all of the clients in subnet 3,
client C will be configured with the following directives in <VAR>/etc/cups/cupsd.conf</VAR>:</P>

<UL><PRE>
# Poll the two servers
<B>
BrowsePoll ServerA
BrowsePoll ServerB
</B>

# Relay the printers to the local subnet
<B>
BrowseRelay 127.0.0.1 192.168.3.255
</B></PRE></UL>

<P>The <A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A> line specifies a source address and mask.
Any browse packets coming from a matching address wil be sent to the given broadcast address.
In this case, we want the packets from the local machine (127.0.0.1) relayed to the other clients.</P>

<P>As printers are found using polling, 
they are relayed from client C to the rest of the clients through a broadcast on subnet 3.
The rest of the clients can use the standard <VAR>cupsd.conf</VAR> configuration.</P>

<P>The <A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A> directive can also be used to relay
browsing packets from one network interface to another.
For example, if client C in the previous example had network interfaces attaches to both
subnet 1 and subnet 2, it could use the <A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A> directive exclusively:

<UL><PRE>
# Relay the printers from subnet 1 and 2 to subnet 3
<B>
BrowseRelay 192.168.1 192.168.3.255
BrowseRelay 192.168.2 192.168.3.255
</B></PRE></UL>

<!-- NEED 3in -->
<H2>Load Balancing and Failsafe Operation</H2>

<P>When using server polling or broadcasting, CUPS clients can
automatically merge identical printers on multiple servers into a
single <I>implicit class</I> queue. Clients assume that printers with
the same name on multiple servers are in fact the same printer or type
of printer being served by multiple machines.</P>

<P>If you have two printers, LaserJet@ServerA and
LaserJet@ServerB, a third implicit class called <I>LaserJet</I>
will be created automatically on the client that refers to both
printers. If the client also has a local printer with the name
LaserJet and the <A
HREF="#ImplicitAnyClasses"><CODE>ImplicitAnyClasses</CODE></A>
directive is enabled, then an implicit class named
<I>AnyLaserJet</I> will be created instead. Otherwise, the local
printer will prevent the creation of an implicit class, since
CUPS will assume that the local printer will always be more
available than a remote one.</P>

<P>The client will alternate between servers and automatically stop
sending jobs to a server if it goes down, providing a load-balancing
effect and fail-safe operation with automatic switchover.</P>

<CENTER><TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
	<TR>
	<TD><B> NOTE:</B>
	<P>Note that implicit classes (<A
	HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>) 
	are enabled and implicit "any" classes (<A
	HREF="#ImplicitAnyClasses"><CODE>ImplicitAnyClasses</CODE></A>)
	are disabled by default.</P>
	</TD>
	</TR>
</TABLE></CENTER>

<H1 ALIGN="RIGHT"><A NAME="PRINTING_MANAGEMENT">6 - Printing System Management</A></H1>

<P>This chapter shows how you can configure the CUPS server.

<H2>The Basics</H2>

<P>Several text files are used to configure CUPS. All of the server
configuration files are located in the <VAR>/etc/cups</VAR> directory:

<UL>
<DL>

	<!-- NEED 1in -->
	<DT>classes.conf

	<DD>This file contains information on each printer class.
	Normally you manipulate this file using the
	<CODE>lpadmin</CODE> command or the Web interface.<BR>&nbsp;

	<!-- NEED 1in -->
	<DT>client.conf

	<DD>This file provides the default server name for client
	machines. See <A HREF="#CLIENT_SETUP">Chapter 5, "Client
	Setup"</A> for more information.<BR>&nbsp;

	<!-- NEED 1in -->
	<DT>cupsd.conf

	<DD>This file controls how the CUPS server
	(<VAR>/usr/sbin/cupsd</VAR>) operates and is normally edited by
	hand.<BR>&nbsp;

	<!-- NEED 1in -->
	<DT>mime.convs

	<DD>This file contains a list of standard file conversion filters
	and their costs. You normally do not edit this file.<BR>&nbsp;

	<!-- NEED 1in -->
	<DT>mime.types

	<DD>This file contains a list of standard file formats and how to
	recognize them. You normally do not edit this file.<BR>&nbsp;

	<!-- NEED 1in -->
	<DT>printers.conf

	<DD>This file contains information on each printer. Normally
	you manipulate this file using the <CODE>lpadmin</CODE> command
	or the Web Interface.<BR>&nbsp;

</DL>
</UL>

<H2><A NAME="RESTARTING">Restarting the CUPS Server</A></H2>

<P>Once you have made a change to a configuration file you need to
restart the CUPS server by sending it a <CODE>HUP</CODE> signal or using the
supplied initialization script. The CUPS distributions install the
script in the <VAR>init.d</VAR> directory with the name
<VAR>cups</VAR>. The location varies based upon the operating system:

<UL><PRE>
<B>/etc/software/init.d/cups restart ENTER</B>
<B>/etc/rc.d/init.d/cups restart ENTER</B>
<B>/etc/init.d/cups restart ENTER</B>
<B>/sbin/init.d/cups restart ENTER</B>
</PRE></UL>

<H2>Changing the Server Configuration</H2>

<P>The <VAR>/etc/cups/cupsd.conf</VAR> file contains configuration
<I>directives</I> that control how the server functions. Each directive
is listed on a line by itself followed by its value. Comments are
introduced using the number sign ("#") character at the beginning of a
line. Since the server configuration file consists of plain text, you
can use your favorite text editor to make changes to it.

<!-- NEED 4in -->
<H2>Server Directives</H2>

<P>The <VAR>cupsd.conf</VAR> file contains many directives that
determine how the server operates:

<UL>
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD VALIGN="TOP">

	<LI><A HREF="#AccessLog"><CODE>AccessLog</CODE></A>
	<LI><A HREF="#Allow"><CODE>Allow</CODE></A>
	<LI><A HREF="#AuthClass"><CODE>AuthClass</CODE></A>
	<LI><A HREF="#AuthGroupName"><CODE>AuthGroupName</CODE></A>
	<LI><A HREF="#AuthType"><CODE>AuthType</CODE></A>
	<LI><A HREF="#AutoPurgeJobs"><CODE>AutoPurgeJobs</CODE></A>
	<LI><A HREF="#BrowseAddress"><CODE>BrowseAddress</CODE></A>
	<LI><A HREF="#BrowseAllow"><CODE>BrowseAllow</CODE></A>
	<LI><A HREF="#BrowseDeny"><CODE>BrowseDeny</CODE></A>
	<LI><A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A>
	<LI><A HREF="#BrowseOrder"><CODE>BrowseOrder</CODE></A>
	<LI><A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A>
	<LI><A HREF="#BrowsePort"><CODE>BrowsePort</CODE></A>
	<LI><A HREF="#BrowseProtocols"><CODE>BrowseProtocols</CODE></A>
	<LI><A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A>
	<LI><A HREF="#BrowseShortNames"><CODE>BrowseShortNames</CODE></A>
	<LI><A HREF="#BrowseTimeout"><CODE>BrowseTimeout</CODE></A>
	<LI><A HREF="#Browsing"><CODE>Browsing</CODE></A>
	<LI><A HREF="#Classification"><CODE>Classification</CODE></A>
	<LI><A HREF="#ClassifyOverride"><CODE>ClassifyOverride</CODE></A>
	<LI><A HREF="#ConfigFilePerm"><CODE>ConfigFilePerm</CODE></A>
	<LI><A HREF="#DataDir"><CODE>DataDir</CODE></A>
	<LI><A HREF="#DefaultCharset"><CODE>DefaultCharset</CODE></A>
	<LI><A HREF="#DefaultLanguage"><CODE>DefaultLanguage</CODE></A>
	<LI><A HREF="#Deny"><CODE>Deny</CODE></A>
	<LI><A HREF="#DocumentRoot"><CODE>DocumentRoot</CODE></A>
	<LI><A HREF="#Encryption"><CODE>Encryption</CODE></A>
	<LI><A HREF="#ErrorLog"><CODE>ErrorLog</CODE></A>
	<LI><A HREF="#FaxRetryInterval"><CODE>FaxRetryInterval</CODE></A>

</TD>
<TD VALIGN="TOP">
&nbsp;&nbsp;&nbsp;
</TD>
<TD VALIGN="TOP">

	<LI><A HREF="#FaxRetryLimit"><CODE>FaxRetryLimit</CODE></A>
	<LI><A HREF="#FileDevice"><CODE>FileDevice</CODE></A>
	<LI><A HREF="#FilterLimit"><CODE>FilterLimit</CODE></A>
	<LI><A HREF="#FilterNice"><CODE>FilterNice</CODE></A>
	<LI><A HREF="#FontPath"><CODE>FontPath</CODE></A>
	<LI><A HREF="#Group"><CODE>Group</CODE></A>
	<LI><A HREF="#HideImplicitMembers"><CODE>HideImplicitMembers</CODE></A>
	<LI><A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A>
	<LI><A HREF="#ImplicitAnyClasses"><CODE>ImplicitAnyClasses</CODE></A>
	<LI><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
	<LI><A HREF="#Include"><CODE>Include</CODE></A>
	<LI><A HREF="#KeepAliveTimeout"><CODE>KeepAliveTimeout</CODE></A>
	<LI><A HREF="#KeepAlive"><CODE>KeepAlive</CODE></A>
	<LI><A HREF="#Limit"><CODE>Limit</CODE></A>
	<LI><A HREF="#LimitExcept"><CODE>LimitExcept</CODE></A>
	<LI><A HREF="#LimitRequestBody"><CODE>LimitRequestBody</CODE></A>
	<LI><A HREF="#Listen"><CODE>Listen</CODE></A>
	<LI><A HREF="#Location"><CODE>Location</CODE></A>
	<LI><A HREF="#LogFilePerm"><CODE>LogFilePerm</CODE></A>
	<LI><A HREF="#LogLevel"><CODE>LogLevel</CODE></A>
	<LI><A HREF="#MaxClients"><CODE>MaxClients</CODE></A>
	<LI><A HREF="#MaxClientsPerHost"><CODE>MaxClientsPerHost</CODE></A>
	<LI><A HREF="#MaxCopies"><CODE>MaxCopies</CODE></A>
	<LI><A HREF="#MaxJobs"><CODE>MaxJobs</CODE></A>
	<LI><A HREF="#MaxJobsPerPrinter"><CODE>MaxJobsPerPrinter</CODE></A>
	<LI><A HREF="#MaxJobsPerUser"><CODE>MaxJobsPerUser</CODE></A>
	<LI><A HREF="#MaxLogSize"><CODE>MaxLogSize</CODE></A>
	<LI><A HREF="#MaxRequestSize"><CODE>MaxRequestSize</CODE></A>
	<LI><A HREF="#Order"><CODE>Order</CODE></A>

</TD>
<TD VALIGN="TOP">
&nbsp;&nbsp;&nbsp;
</TD>
<TD VALIGN="TOP">

	<LI><A HREF="#PageLog"><CODE>PageLog</CODE></A>
	<LI><A HREF="#Port"><CODE>Port</CODE></A>
	<LI><A HREF="#PreserveJobFiles"><CODE>PreserveJobFiles</CODE></A>
	<LI><A HREF="#PreserveJobHistory"><CODE>PreserveJobHistory</CODE></A>
	<LI><A HREF="#Printcap"><CODE>Printcap</CODE></A>
	<LI><A HREF="#PrintcapFormat"><CODE>PrintcapFormat</CODE></A>
	<LI><A HREF="#PrintcapGUI"><CODE>PrintcapGUI</CODE></A>
	<LI><A HREF="#ReloadTimeout"><CODE>ReloadTimeout</CODE></A>
	<LI><A HREF="#RemoteRoot"><CODE>RemoteRoot</CODE></A>
	<LI><A HREF="#RequestRoot"><CODE>RequestRoot</CODE></A>
	<LI><A HREF="#Require"><CODE>Require</CODE></A>
	<LI><A HREF="#RIPCache"><CODE>RIPCache</CODE></A>
	<LI><A HREF="#RootCertDuration"><CODE>RootCertDuration</CODE></A>
	<LI><A HREF="#RunAsUser"><CODE>RunAsUser</CODE></A>
	<LI><A HREF="#Satisfy"><CODE>Satisfy</CODE></A>
	<LI><A HREF="#ServerAdmin"><CODE>ServerAdmin</CODE></A>
	<LI><A HREF="#ServerBin"><CODE>ServerBin</CODE></A>
	<LI><A HREF="#ServerCertificate"><CODE>ServerCertificate</CODE></A>
	<LI><A HREF="#ServerKey"><CODE>ServerKey</CODE></A>
	<LI><A HREF="#ServerName"><CODE>ServerName</CODE></A>
	<LI><A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A>
	<LI><A HREF="#ServerTokens"><CODE>ServerTokens</CODE></A>
	<LI><A HREF="#SSLListen"><CODE>SSLListen</CODE></A>
	<LI><A HREF="#SSLPort"><CODE>SSLPort</CODE></A>
	<LI><A HREF="#SystemGroup"><CODE>SystemGroup</CODE></A>
	<LI><A HREF="#TempDir"><CODE>TempDir</CODE></A>
	<LI><A HREF="#Timeout"><CODE>Timeout</CODE></A>
	<LI><A HREF="#User"><CODE>User</CODE></A>

</TD>
</TR>
</TABLE>
</UL>

<!-- NEED 3in -->
<H3><A NAME="AccessLog">AccessLog</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
AccessLog /var/log/cups/access_log
AccessLog /var/log/cups/access_log-%s
AccessLog syslog
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>AccessLog</CODE> directive sets the name of the access log
file. If the filename is not absolute then it is assumed to be relative
to the <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
access log file is stored in "common log format" and can be used by any
web access reporting tool to generate a report on CUPS server activity.

<P>The server name can be included in the filename by using
<CODE>%s</CODE> in the name.

<P>The special name "syslog" can be used to send the access information
to the system log instead of a plain file.

<P>The default access log file is <VAR>/var/log/cups/access_log</VAR>.

<!-- NEED 6in -->
<H3><A NAME="Allow">Allow</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Allow from All
Allow from None
Allow from *.domain.com
Allow from .domain.com
Allow from host.domain.com
Allow from nnn.*
Allow from nnn.nnn.*
Allow from nnn.nnn.nnn.*
Allow from nnn.nnn.nnn.nnn
Allow from nnn.nnn.nnn.nnn/mm
Allow from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
Allow from @LOCAL
Allow from @IF(name)
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Allow</CODE> directive specifies a hostname, IP address,
or network that is allowed access to the server.  <CODE>Allow</CODE>
directives are cummulative, so multiple <CODE>Allow</CODE> directives
can be used to allow access for multiple hosts or networks.  The
<CODE>/mm</CODE> notation specifies a CIDR netmask:

<CENTER><TABLE BORDER="1">
<TR>
	<TH WIDTH="10%">mm</TH>
	<TH WIDTH="20%">netmask</TH>
	<TH WIDTH="10%">mm</TH>
	<TH WIDTH="20%">netmask</TH>
</TR>
<TR>
	<TD ALIGN="CENTER">0</TD>
	<TD ALIGN="CENTER">0.0.0.0</TD>
	<TD ALIGN="CENTER">8</TD>
	<TD ALIGN="CENTER">255.0.0.0</TD>
</TR>
<TR>
	<TD ALIGN="CENTER">1</TD>
	<TD ALIGN="CENTER">128.0.0.0</TD>
	<TD ALIGN="CENTER">16</TD>
	<TD ALIGN="CENTER">255.255.0.0</TD>
</TR>
<TR>
	<TD ALIGN="CENTER">2</TD>
	<TD ALIGN="CENTER">192.0.0.0</TD>
	<TD ALIGN="CENTER">24</TD>
	<TD ALIGN="CENTER">255.255.255.0</TD>
</TR>
<TR>
	<TD ALIGN="CENTER">...</TD>
	<TD ALIGN="CENTER">...</TD>
	<TD ALIGN="CENTER">32</TD>
	<TD ALIGN="CENTER">255.255.255.255</TD>
</TR>
</TABLE></CENTER>

<P>The <CODE>@LOCAL</CODE> name will allow access from all local
network interfaces, but not remote point-to-point interfaces. The
<CODE>@IF(name)</CODE> name will allow access from the named
interface.

<P>The <CODE>Allow</CODE> directive must appear inside a
<A HREF="#Location"><CODE>Location</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="AuthClass">AuthClass</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
AuthClass Anonymous
AuthClass User
AuthClass System
AuthClass Group
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>AuthClass</CODE> directive defines what level of authentication
is required:

<UL>

	<LI><CODE>Anonymous</CODE> - No authentication should be performed
	(default.)

	<LI><CODE>User</CODE> - A valid username and password is required.

	<LI><CODE>System</CODE> - A valid username and password is
	required, and the username must belong to the "sys" group; this
	can be changed using the
	<A HREF="#SystemGroup"><CODE>SystemGroup</CODE></A> directive.

	<LI><CODE>Group</CODE> - A valid username and password is
	required, and the username must belong to the group named by
	the <CODE>AuthGroupName</CODE> directive.

</UL>

<P>The <CODE>AuthClass</CODE> directive must appear inside a
<A HREF="#Location"><CODE>Location</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="AuthGroupName">AuthGroupName</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
AuthGroupName mygroup
AuthGroupName lp
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>AuthGroupName</CODE> directive sets the group to use for
<CODE>Group</CODE> authentication.

<P>The <CODE>AuthGroupName</CODE> directive must appear inside a
<A HREF="#Location"><CODE>Location</CODE></A> directive.

<!-- NEED 4in -->
<H3><A NAME="AuthType">AuthType</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
AuthType None
AuthType Basic
AuthType Digest
AuthType BasicDigest
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>AuthType</CODE> directive defines the type of authentication to
perform:

<UL>

	<LI><CODE>None</CODE> - No authentication should be performed
	(default.)

	<LI><CODE>Basic</CODE> - Basic authentication should be
	performed using the UNIX password and group files.

	<LI><CODE>Digest</CODE> - Digest authentication should be
	performed using the <VAR>/etc/cups/passwd.md5</VAR> file.

	<LI><CODE>BasicDigest</CODE> - Basic authentication should be
	performed using the <VAR>/etc/cups/passwd.md5</VAR> file.

</UL>

<P>When using <CODE>Basic</CODE>, <CODE>Digest</CODE>, or
<CODE>BasicDigest</CODE> authentication, clients connecting
through the <CODE>localhost</CODE> interface can also
authenticate using <A HREF="#CERTIFICATES">certificates</A>.

<P>The <CODE>AuthType</CODE> directive must appear inside a
<A HREF="#Location"><CODE>Location</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="AutoPurgeJobs">AutoPurgeJobs</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
AutoPurgeJobs Yes
AutoPurgeJobs No
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>AutoPurgeJobs</CODE> directive specifies whether or not to purge
completed jobs once they are no longer required for quotas. This option has
no effect if quotas are not enabled. The default setting is <CODE>No</CODE>.

<!-- NEED 5in -->
<H3><A NAME="BrowseAddress">BrowseAddress</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
BrowseAddress 255.255.255.255:631
BrowseAddress 192.0.2.255:631
BrowseAddress host.domain.com:631
BrowseAddress @LOCAL
BrowseAddress @IF(name)
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>BrowseAddress</CODE> directive specifies an address to
send browsing information to. Multiple <CODE>BrowseAddress</CODE>
directives can be specified to send browsing information to different
networks or systems.

<P>The <CODE>@LOCAL</CODE> name will broadcast printer
information to all local interfaces. The <CODE>@IF(name)</CODE>
name will broadcast to the named interface.

<P>No browse addresses are set by default.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
	<TD>
	<B>NOTE:</B>

	<P>If you are using HP-UX 10.20 and a subnet that is not 24,
	16, or 8 bits, printer browsing (and in fact all broadcast
	reception) will not work. This problem appears to be fixed in
	HP-UX 11.0.
	</TD>
</TR>
</TABLE></CENTER>

<!-- NEED 4in -->
<H3><A NAME="BrowseAllow">BrowseAllow</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
BrowseAllow from all
BrowseAllow from none
BrowseAllow from 192.0.2
BrowseAllow from 192.0.2.0/24
BrowseAllow from 192.0.2.0/255.255.255.0
BrowseAllow from *.domain.com
BrowseAllow from @LOCAL
BrowseAllow from @IF(name)
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>BrowseAllow</CODE> directive specifies a system or network
to accept browse packets from. The default is to accept browse packets
from all hosts.

<P>Host and domain name matching require that you enable the
<A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A> directive.

<P>IP address matching supports exact matches, partial addresses that
match networks using netmasks of 255.0.0.0, 255.255.0.0, and 255.255.255.0,
or network addresses using the specified netmask or bit count.

<P>The <CODE>@LOCAL</CODE> name will allow browse data from all
local network interfaces, but not remote point-to-point
interfaces. The <CODE>@IF(name)</CODE> name will allow browse
data from the named interface.


<!-- NEED 4in -->
<H3><A NAME="BrowseDeny">BrowseDeny</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
BrowseDeny from all
BrowseDeny from none
BrowseDeny from 192.0.2
BrowseDeny from 192.0.2.0/24
BrowseDeny from 192.0.2.0/255.255.255.0
BrowseDeny from *.domain.com
BrowseDeny from @LOCAL
BrowseDeny from @IF(name)
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>BrowseDeny</CODE> directive specifies a system or network
to reject browse packets from. The default is to deny browse packets
from no hosts.

<P>Host and domain name matching require that you enable the
<A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A> directive.

<P>IP address matching supports exact matches, partial addresses that
match networks using netmasks of 255.0.0.0, 255.255.0.0, and 255.255.255.0,
or network addresses using the specified netmask or bit count.

<P>The <CODE>@LOCAL</CODE> name will block browse data from all
local network interfaces, but not remote point-to-point
interfaces. The <CODE>@IF(name)</CODE> name will block browse
data from the named interface.


<!-- NEED 3in -->
<H3><A NAME="BrowseInterval">BrowseInterval</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
BrowseInterval 0
BrowseInterval 30
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>BrowseInterval</CODE> directive specifies the maximum amount of
time between browsing updates. Specifying a value of 0 seconds disables
outgoing browse updates but allows a server to receive printer information
from other hosts.

<P>The <CODE>BrowseInterval</CODE> value should always be less than the
<A HREF="#BrowseTimeout"><CODE>BrowseTimeout</CODE></A> value. Otherwise
printers and classes will disappear from client systems between updates.


<!-- NEED 3in -->
<H3><A NAME="BrowseOrder">BrowseOrder</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
BrowseOrder allow,deny
BrowseOrder deny,allow
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>BrowseOrder</CODE> directive specifies the order of allow/deny
processing. The default order is <CODE>deny,allow</CODE>:

<UL>

	<LI><CODE>allow,deny</CODE> - Browse packets are accepted unless
	specifically denied.

	<LI><CODE>deny,allow</CODE> - Browse packets are rejected unless
	specifically allowed.

</UL>

<!-- NEED 3in -->
<H3><A NAME="BrowsePoll">BrowsePoll</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
BrowsePoll 192.0.2.2:631
BrowsePoll host.domain.com:631
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>BrowsePoll</CODE> directive polls a server for available
printers once every
<A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A> seconds.
Multiple <CODE>BrowsePoll</CODE> directives can be specified to poll
multiple servers.

<P>If <CODE>BrowseInterval</CODE> is set to 0 then the server is polled
once every 30 seconds.

<!-- NEED 3in -->
<H3><A NAME="BrowsePort">BrowsePort</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
BrowsePort 631
BrowsePort 9999
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>BrowsePort</CODE> directive specifies the UDP port number
used for browse packets. The default port number is 631.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
	<TD>
	<B>NOTE:</B>

	<P>You must set the <CODE>BrowsePort</CODE> to the same value
	on all of the systems that you want to see.
	</TD>
</TR>
</TABLE></CENTER>

<!-- NEED 3in -->
<H3><A NAME="BrowseProtocols">BrowseProtocols</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
BrowseProtocols CUPS
BrowseProtocols SLP
BrowseProtocols CUPS SLP
BrowseProtocols all
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>BrowseProtocols</CODE> directive specifies the protocols to
use when collecting and distributing shared printers on the local network.
The default protocol is <CODE>CUPS</CODE>, which is a broadcast-based
protocol.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
	<TD>
	<B>NOTE:</B>

	<P>When using the <CODE>SLP</CODE> protocol, you must have at least
	one Directory Agent (DA) server on your network. Otherwise the
	CUPS scheduler (<CODE>cupsd</CODE>) will not respond to client
	requests for several seconds while polling the network.
	</TD>
</TR>
</TABLE></CENTER>

<!-- NEED 4in -->
<H3><A NAME="BrowseRelay">BrowseRelay</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
BrowseRelay 193.0.2.1 192.0.2.255
BrowseRelay 193.0.2.0/255.255.255.0 192.0.2.255
BrowseRelay 193.0.2.0/24 192.0.2.255
BrowseRelay *.domain.com 192.0.2.255
BrowseRelay host.domain.com 192.0.2.255
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>BrowseRelay</CODE> directive specifies source and destination
addresses for relaying browsing information from one host or network to
another. Multiple <CODE>BrowseRelay</CODE> directives can be specified
as needed.

<P><CODE>BrowseRelay</CODE> is typically used on systems that bridge
multiple subnets using one or more network interfaces. It can also be
used to relay printer information from polled servers with the line:

<UL><PRE>
BrowseRelay 127.0.0.1 255.255.255.255
</PRE></UL>

<P>This effectively provides access to printers on a WAN for all clients
on the LAN(s).

<!-- NEED 3in -->
<H3><A NAME="BrowseShortNames">BrowseShortNames</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
BrowseShortNames Yes
BrowseShortNames No
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>BrowseShortNames</CODE> directive specifies whether or not
short names are used for remote printers when possible. Short names are
just the remote printer name, without the server ("printer"). If more than
one remote printer is detected with the same name, the printers will have
long names ("printer@server1", "printer@server2".)

<P>The default value for this option is <CODE>Yes</CODE>.

<!-- NEED 3in -->
<H3><A NAME="BrowseTimeout">BrowseTimeout</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
BrowseTimeout 300
BrowseTimeout 60
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>BrowseTimeout</CODE> directive sets the timeout for
printer or class information that is received in browse packets. Once a
printer or class times out it is removed from the list of available
destinations.

<P>The <CODE>BrowseTimeout</CODE> value should always be greater than the
<A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A> value. Otherwise
printers and classes will disappear from client systems between updates.

<!-- NEED 4in -->
<H3><A NAME="Browsing">Browsing</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Browsing On
Browsing Off
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Browsing</CODE> directive controls whether or not network printer
browsing is enabled. The default setting is <CODE>On</CODE>.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
	<TD>
	<B>NOTE:</B>

	<P>If you are using HP-UX 10.20 and a subnet that is not 24,
	16, or 8 bits, printer browsing (and in fact all broadcast
	reception) will not work. This problem appears to be fixed in
	HP-UX 11.0.
	</TD>
</TR>
</TABLE></CENTER>

<!-- NEED 3in -->
<H3><A NAME="Classification">Classification</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Classification
Classification classified
Classification confidential
Classification secret
Classification topsecret
Classification unclassified
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Classification</CODE> directive sets the classification level
on the server. When this option is set, at least one of the banner pages
is forced to the classification level, and the classification is placed
on each page of output. The default is no classification level.

<!-- NEED 3in -->
<H3><A NAME="ClassifyOverride">ClassifyOverride</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ClassifyOverride Yes
ClassifyOverride No
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ClassifyOverride</CODE> directive specifies whether users
can override the default classification level on the server. When the
server classification is set, users can change the classification using
the <CODE>job-sheets</CODE> option and can choose to only print one
security banner before or after the job. If the <CODE>job-sheets</CODE>
option is set to <CODE>none</CODE> then the server default classification
is used.

<P>The default is to not allow classification overrides.

<!-- NEED 3in -->
<H3><A NAME="ConfigFilePerm">ConfigFilePerm</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ConfigFilePerm 0644
ConfigFilePerm 0600
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ConfigFilePerm</CODE> directive specifies the permissions
to use when writing configuration files. The default is 0600.

<!-- NEED 3in -->
<H3><A NAME="DataDir">DataDir</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
DataDir /usr/share/cups
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>DataDir</CODE> directive sets the directory to use for data
files.

<!-- NEED 3in -->
<H3><A NAME="DefaultCharset">DefaultCharset</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
DefaultCharset utf-8
DefaultCharset iso-8859-1
DefaultCharset windows-1251
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>DefaultCharset</CODE> directive sets the default character set
to use for client connections. The default character set is
<CODE>utf-8</CODE> but is overridden by the character set for the language
specified by the client or the <CODE>DefaultLanguage</CODE> directive.

<!-- NEED 3in -->
<H3><A NAME="DefaultLanguage">DefaultLanguage</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
DefaultLanguage de
DefaultLanguage en
DefaultLanguage es
DefaultLanguage fr
DefaultLanguage it
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>DefaultLanguage</CODE> directive specifies the default language
to use for client connections. Setting the default language also sets the
default character set if a language localization file exists for it.  The
default language is "en" for English.

<!-- NEED 5in -->
<H3><A NAME="Deny">Deny</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Deny from All
Deny from None
Deny from *.domain.com
Deny from .domain.com
Deny from host.domain.com
Deny from nnn.*
Deny from nnn.nnn.*
Deny from nnn.nnn.nnn.*
Deny from nnn.nnn.nnn.nnn
Deny from nnn.nnn.nnn.nnn/mm
Deny from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
Deny from @LOCAL
Deny from @IF(name)
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Deny</CODE> directive specifies a hostname, IP address, or
network that is allowed access to the server. <CODE>Deny</CODE>
directives are cummulative, so multiple <CODE>Deny</CODE> directives
can be used to allow access for multiple hosts or networks. The
<CODE>/mm</CODE> notation specifies a CIDR netmask:

<CENTER><TABLE BORDER="1">
<TR>
	<TH WIDTH="10%">mm</TH>
	<TH WIDTH="20%">netmask</TH>
	<TH WIDTH="10%">mm</TH>
	<TH WIDTH="20%">netmask</TH>
</TR>
<TR>
	<TD ALIGN="CENTER">0</TD>
	<TD ALIGN="CENTER">0.0.0.0</TD>
	<TD ALIGN="CENTER">8</TD>
	<TD ALIGN="CENTER">255.0.0.0</TD>
</TR>
<TR>
	<TD ALIGN="CENTER">1</TD>
	<TD ALIGN="CENTER">128.0.0.0</TD>
	<TD ALIGN="CENTER">16</TD>
	<TD ALIGN="CENTER">255.255.0.0</TD>
</TR>
<TR>
	<TD ALIGN="CENTER">2</TD>
	<TD ALIGN="CENTER">192.0.0.0</TD>
	<TD ALIGN="CENTER">24</TD>
	<TD ALIGN="CENTER">255.255.255.0</TD>
</TR>
<TR>
	<TD ALIGN="CENTER">...</TD>
	<TD ALIGN="CENTER">...</TD>
	<TD ALIGN="CENTER">32</TD>
	<TD ALIGN="CENTER">255.255.255.255</TD>
</TR>
</TABLE></CENTER>

<P>The <CODE>@LOCAL</CODE> name will deny access from all local
network interfaces, but not remote point-to-point interfaces. The
<CODE>@IF(name)</CODE> name will deny access from the named
interface.

<P>The <CODE>Deny</CODE> directive must appear inside a
<A HREF="#Location"><CODE>Location</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="DocumentRoot">DocumentRoot</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
DocumentRoot /usr/share/doc/cups
DocumentRoot /foo/bar/doc/cups
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>DocumentRoot</CODE> directive specifies the location of
web content for the HTTP server in CUPS. If an absolute path is not
specified then it is assumed to be relative to the
<A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
default directory is <VAR>/usr/share/doc/cups</VAR>.

<P>Documents are first looked up in a sub-directory for the primary
language requested by the client (e.g. <VAR>/usr/share/doc/cups/fr/...</VAR>)
and then directly under the <CODE>DocumentRoot</CODE> directory
(e.g. <VAR>/usr/share/doc/cups/...</VAR>), so it is possible to localize
the web content by providing subdirectories for each language needed.

<!-- NEED 3in -->
<H3><A NAME="Encryption">Encryption</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Encryption Never
Encryption IfRequested
Encryption Required
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Encryption</CODE> directive must appear instead a
<A HREF="#Location"><CODE>Location</CODE></A>
section and specifies the encryption settings for that location.
The default setting is <CODE>IfRequested</CODE> for all locations.

<!-- NEED 3in -->
<H3><A NAME="ErrorLog">ErrorLog</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ErrorLog /var/log/cups/error_log
ErrorLog /var/log/cups/error_log-%s
ErrorLog syslog
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ErrorLog</CODE> directive sets the name of the error log
file. If the filename is not absolute then it is assumed to be relative
to the <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
default error log file is <VAR>/var/log/cups/error_log</VAR>.

<P>The server name can be included in the filename by using
<CODE>%s</CODE> in the name.

<P>The special name "syslog" can be used to send the error information
to the system log instead of a plain file.


<!-- NEED 2in -->
<H3><A NAME="FaxRetryInterval">FaxRetryInterval</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
FaxRetryInterval 300
FaxRetryInterval 30
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>FaxRetryInterval</CODE> directive determines how
often fax print jobs are retried when the backend is unable to
send the fax. The value is the number of seconds between tries.

<P>The default setting is <CODE>300</CODE> seconds.


<!-- NEED 2in -->
<H3><A NAME="FaxRetryLimit">FaxRetryLimit</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
FaxRetryLimit 5
FaxRetryLimit 100
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>FaxRetryLimit</CODE> directive determines how many
times a fax job is retried before it is canceled.

<P>The default setting is <CODE>5</CODE>.


<!-- NEED 3in -->
<H3><A NAME="FileDevice">FileDevice</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
FileDevice Yes
FileDevice No
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>FileDevice</CODE> directive determines whether the
scheduler allows new printers to be added using device URIs of the
form <CODE>file:/filename</CODE>. File devices are most often used
to test new printer drivers and do no support raw file printing.

<P>The default setting is <CODE>No</CODE>.

<CENTER><TABLE WIDTH="80%" BGCOLOR="#cccccc" CELLPADDING="5" BORDER="1">
<TR>
	<TD>

	<B>Note:</B>

	<P>File devices are managed by the scheduler. Since the
	scheduler normally runs as the root user, file devices
	can be used to overwrite system files and potentially
	gain unauthorized access to the system. If you must
	create printers using file devices, we recommend that
	you set the <CODE>FileDevice</CODE> directive to
	<CODE>Yes</CODE> for only as long as you need to add the
	printers to the system, and then reset the directive to
	<CODE>No</CODE>.

	</TD>
</TR>
</TABLE></CENTER>


<!-- NEED 3in -->
<H3><A NAME="FilterLimit">FilterLimit</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
FilterLimit 0
FilterLimit 200
FilterLimit 1000
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>FilterLimit</CODE> directive sets the maximum cost
of all running job filters. It can be used to limit the number
of filter programs that are run on a server to minimize disk,
memory, and CPU resource problems. A limit of 0 disables filter
limiting.

<P>An average print to a non-PostScript printer needs a filter
limit of about 200. A PostScript printer needs about half that
(100). Setting the limit below these thresholds will effectively
limit the scheduler to printing a single job at any time.

<P>The default limit is 0.

<!-- NEED 3in -->
<H3><A NAME="FilterNice">FilterNice</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
FilterNice 0
FilterNice 39
FilterNice -10
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>FilterNice</CODE> directive sets the scheduling
priority of job filters. Values larger than 0 give filters a
lower priority while values smaller than 0 give filters a higher
priority. The <CODE>FilterNice</CODE> value does not affect the
priority of job backends.

<P>The default priority is 0.

<!-- NEED 3in -->
<H3><A NAME="FontPath">FontPath</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
FontPath /foo/bar/fonts
FontPath /usr/share/cups/fonts:/foo/bar/fonts
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>FontPath</CODE> directive specifies the font path to use when
searching for fonts. The default font path is
<CODE>/usr/share/cups/fonts</CODE>.

<!-- NEED 3in -->
<H3><A NAME="Group">Group</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Group sys
Group system
Group root
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Group</CODE> directive specifies the UNIX group that
filter and CGI programs run as. The default group is <CODE>sys</CODE>,
<CODE>system</CODE>, or <CODE>root</CODE> depending on the operating
system.

<!-- NEED 3in -->
<H3><A NAME="HideImplicitMembers">HideImplicitMembers</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
HideImplicitMembers Yes
HideImplicitMembers No
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>HideImplicitMembers</CODE> directive controls
whether the individual printers in an implicit class are shown
to the user. The default is <CODE>No</CODE>.</P>

<P><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
must be enabled for this directive to have any effect.</P>

<!-- NEED 3in -->
<H3><A NAME="HostNameLookups">HostNameLookups</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
HostNameLookups On
HostNameLookups Off
HostNameLookups Double
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>HostNameLookups</CODE> directive controls whether
or not CUPS looks up the hostname for connecting clients. The
<CODE>Double</CODE> setting causes CUPS to verify that the
hostname resolved from the address matches one of the addresses
returned for that hostname. <CODE>Double</CODE> lookups also
prevent clients with unregistered addresses from connecting
to your server.

The default is <CODE>Off</CODE> to avoid the potential server
performance problems with hostname lookups. Set this option to
<CODE>On</CODE> or <CODE>Double</CODE> only if absolutely
required.

<!-- NEED 3in -->
<H3><A NAME="ImplicitAnyClasses">ImplicitAnyClasses</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ImplicitAnyClasses On
ImplicitAnyClasses Off
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ImplicitAnyClasses</CODE> directive controls
whether implicit classes for local and remote printers are
created with the name <CODE>AnyPrinter</CODE>. The default
setting is <CODE>Off</CODE>.</P>

<P><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
must be enabled for this directive to have any effect.</P>

<!-- NEED 3in -->
<H3><A NAME="ImplicitClasses">ImplicitClasses</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ImplicitClasses On
ImplicitClasses Off
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ImplicitClasses</CODE> directive controls whether implicit
classes are created based upon the available network printers and classes.
The default setting is <CODE>On</CODE> but is automatically turned
<CODE>Off</CODE> if <A HREF="#Browsing"><CODE>Browsing</CODE></A> is
turned <CODE>Off</CODE>.

<!-- NEED 3in -->
<H3><A NAME="Include">Include</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Include filename
Include /foo/bar/filename
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Include</CODE> directive includes the named file in
the <CODE>cupsd.conf</CODE> file. If no leading path is
provided, the file is assumed to be relative to the
<A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory.</P>

<!-- NEED 3in -->
<H3><A NAME="KeepAlive">KeepAlive</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
KeepAlive On
KeepAlive Off
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>KeepAlive</CODE> directive controls whether or not to support
persistent HTTP connections. The default is <CODE>On</CODE>.

<P>HTTP/1.1 clients automatically support persistent connections, while
HTTP/1.0 clients must specifically request them using the
<CODE>Keep-Alive</CODE> attribute in the <CODE>Connection:</CODE>
field of each request.

<!-- NEED 3in -->
<H3><A NAME="KeepAliveTimeout">KeepAliveTimeout</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
KeepAliveTimeout 60
KeepAliveTimeout 30
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>KeepAliveTimeout</CODE> directive controls how long a
persistent HTTP connection will remain open after the last request. The
default is 60 seconds.

<!-- NEED 3in -->
<H3><A NAME="Limit">Limit</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
&lt;Limit GET POST&gt;
...
&lt;/Limit&gt;

&lt;Limit ALL&gt;
...
&lt;/Limit&gt;
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Limit</CODE> directive groups access control directives for
specific types of HTTP requests and must appear inside a
<A HREF="#Location"><CODE>Location</CODE></A> section. Access can be limited
for individual request types (<CODE>DELETE</CODE>, <CODE>GET</CODE>,
<CODE>HEAD</CODE>, <CODE>OPTIONS</CODE>, <CODE>POST</CODE>, <CODE>PUT</CODE>,
and <CODE>TRACE</CODE>) or for all request types (<CODE>ALL</CODE>). The
request type names are case-sensitive for compatibility with Apache.

<!-- NEED 3in -->
<H3><A NAME="LimitExcept">LimitExcept</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
&lt;LimitExcept GET POST&gt;
...
&lt;/LimitExcept&gt;
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>LimitExcept</CODE> directive groups access control directives for
specific types of HTTP requests and must appear inside a
<A HREF="#Location"><CODE>Location</CODE></A> section. Unlike the
<A HREF="#Limit"><CODE>Limit</CODE></A> directive, <CODE>LimitExcept</CODE>
restricts access for all requests <I>except</I> those listed on the
<CODE>LimitExcept</CODE> line.

<!-- NEED 3in -->
<H3><A NAME="LimitRequestBody">LimitRequestBody</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
LimitRequestBody 10485760
LimitRequestBody 10m
LimitRequestBody 0
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>LimitRequestBody</CODE> directive controls the maximum size of
print files, IPP requests, and HTML form data in HTTP POST requests. The
default limit is 0 which disables the limit check.

<P>Also see the identical
<A HREF="#MaxRequestSize"><CODE>MaxRequestSize</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="Listen">Listen</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Listen 127.0.0.1:631
Listen 192.0.2.1:631
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Listen</CODE> directive specifies a network address and port
to listen for connections. Multiple <CODE>Listen</CODE> directives can be
provided to listen on multiple addresses.

<P>The <CODE>Listen</CODE> directive is similar to the
<A HREF="#Port"><CODE>Port</CODE></A> directive but allows you to restrict
access to specific interfaces or networks.

<!-- NEED 3in -->
<H3><A NAME="Location">Location</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
&lt;Location /&gt;
...
&lt;/Location&gt;

&lt;Location /admin&gt;
...
&lt;/Location&gt;

&lt;Location /printers&gt;
...
&lt;/Location&gt;

&lt;Location /printers/name&gt;
...
&lt;/Location&gt;

&lt;Location /classes&gt;
...
&lt;/Location&gt;

&lt;Location /classes/name&gt;
...
&lt;/Location&gt;
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Location</CODE> directive specifies access control and
authentication options for the specified HTTP resource or path. 
The 
<A HREF="#Allow"><CODE>Allow</CODE></A>,
<A HREF="#AuthClass"><CODE>AuthClass</CODE></A>,
<A HREF="#AuthGroupName"><CODE>AuthGroupName</CODE></A>,
<A HREF="#AuthType"><CODE>AuthType</CODE></A>,
<A HREF="#Deny"><CODE>Deny</CODE></A>,
<A HREF="#Encryption"><CODE>Encryption</CODE></A>,
<A HREF="#Limit"><CODE>Limit</CODE></A>,
<A HREF="#LimitExcept"><CODE>LimitExcept</CODE></A>,
<A HREF="#Order"><CODE>Order</CODE></A>,
<A HREF="#Require"><CODE>Require</CODE></A>, and
<A HREF="#Satisfy"><CODE>Satisfy</CODE></A>
directives may all appear inside a location.

<CENTER><TABLE BORDER="1"><CAPTION>Locations on the Server.</CAPTION>
<TR><TH>Location</TH><TH>Description</TH></TR>
<TR><TD>/</TD><TD>The path for all get operations (get-printers, get-jobs, etc.)</TD></TR>
<TR><TD>/admin</TD><TD>The path for all administration operations (add-printer, delete-printer, start-printer, etc.)</TD></TR>
<TR><TD>/admin/conf</TD><TD>The path for access to the CUPS configuration files (cupsd.conf, client.conf, etc.)</TD></TR>
<TR><TD>/classes</TD><TD>The path for all classes</TD></TR>
<TR><TD>/classes/name</TD><TD>The resource for class <CODE>name</CODE></TD></TR>
<TR><TD>/jobs</TD><TD>The path for all jobs (hold-job, release-job, etc.)</TD></TR>
<TR><TD>/jobs/id</TD><TD>The resource for job <CODE>id</CODE></TD></TR>
<TR><TD>/printers</TD><TD>The path for all printers</TD></TR>
<TR><TD>/printers/name</TD><TD>The path for printer <CODE>name</CODE></TD></TR>
<TR><TD>/printers/name.ppd</TD><TD>The PPD file path for printer <CODE>name</CODE></TD></TR>
</TABLE></CENTER>

<P>Note that more specific resources override the less specific ones.
So the directives inside the <CODE>/printers/name</CODE> location will override ones from <CODE>/printers</CODE>.
Directives inside <CODE>/printers</CODE> will override ones from <CODE>/</CODE>. &nbsp;
None of the directives are inherited.
More information can be found in section <A HREF="#PRINTING_SECURITY">"Printing System Security"</A>.

<!-- NEED 3in -->
<H3><A NAME="LogFilePerm">LogFilePerm</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
LogFilePerm 0644
LogFilePerm 0600
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>LogFilePerm</CODE> directive specifies the permissions
to use when writing configuration files. The default is 0644.

<!-- NEED 3in -->
<H3><A NAME="LogLevel">LogLevel</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
LogLevel none
LogLevel emerg
LogLevel alert
LogLevel crit
LogLevel error
LogLevel warn
LogLevel notice
LogLevel info
LogLevel debug
LogLevel debug2
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>LogLevel</CODE> directive specifies the level of logging
for the <A HREF="#ErrorLog"><CODE>ErrorLog</CODE></A> file. The
following values are recognized (each level logs everything under the
preceding levels):

<UL>

	<LI><CODE>none</CODE> - Log nothing.

	<LI><CODE>emerg</CODE> - Log emergency conditions that prevent the
	server from running.

	<LI><CODE>alert</CODE> - Log alerts that must be handled immediately.

	<LI><CODE>crit</CODE> - Log critical errors that don't prevent
	the server from running.

	<LI><CODE>error</CODE> - Log general errors.

	<LI><CODE>warn</CODE> - Log errors and warnings.

	<LI><CODE>notice</CODE> - Log temporary error conditions.

	<LI><CODE>info</CODE> - Log all requests and state changes (default).

	<LI><CODE>debug</CODE> - Log basic debugging information.

	<LI><CODE>debug2</CODE> - Log all debugging information.

</UL>

<!-- NEED 3in -->
<H3><A NAME="MaxClients">MaxClients</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
MaxClients 100
MaxClients 1024
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>MaxClients</CODE> directive controls the maximum number of
simultaneous clients that will be allowed by the server. The default is
100 clients.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
	<TD>
	<B>NOTE:</B>

	<P>Since each print job requires a file descriptor for the
	status pipe, the CUPS server internally limits the
	<CODE>MaxClients</CODE> value to 1/3 of the available file descriptors
	to avoid possible problems when printing large numbers of jobs.
	</TD>
</TR>
</TABLE></CENTER>


<!-- NEED 3in -->
<H3><A NAME="MaxClientsPerHost">MaxClientsPerHost</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
MaxClientsPerHost 0
MaxClientsPerHost 10
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>MaxClientsPerHost</CODE> directive controls the
maximum number of simultaneous clients that will be allowed from
a single host by the server. The default is the
<CODE>MaxClients</CODE> value. A value of 0 uses the automatic
setting based on the <CODE>MaxClients</CODE> value.</P>

<P>This directive provides a small measure of protection against
Denial of Service attacks from a single host.


<!-- NEED 3in -->
<H3><A NAME="MaxCopies">MaxCopies</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
MaxCopies 100
MaxCopies 65535
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>MaxCopies</CODE> directive controls the maximum
number of copies that a user can print of a job. The default is
100 copies.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
	<TD>
	<B>NOTE:</B>

	<P>Most HP PCL laser printers internally limit the
	number of copies to 100.

	</TD>
</TR>
</TABLE></CENTER>

<!-- NEED 3in -->
<H3><A NAME="MaxJobs">MaxJobs</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
MaxJobs 100
MaxJobs 9999
MaxJobs 0
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>MaxJobs</CODE> directive controls the maximum number of jobs
that are kept in memory. Once the number of jobs reaches the limit, the
oldest completed job is automatically purged from the system to make room
for the new one. If all of the known jobs are still pending or active then
the new job will be rejected.

<P>Setting the maximum to 0 disables this functionality. The default
setting is 500.

<!-- NEED 3in -->
<H3><A NAME="MaxJobsPerPrinter">MaxJobsPerPrinter</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
MaxJobsPerPrinter 100
MaxJobsPerPrinter 9999
MaxJobsPerPrinter 0
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>MaxJobsPerPrinter</CODE> directive controls the maximum number of active jobs
that are allowed for each printer or class. Once a printer or class reaches the limit, new jobs will be
rejected until one of the active jobs is completed, stopped, aborted, or cancelled.

<P>Setting the maximum to 0 disables this functionality. The default
setting is 0.

<!-- NEED 3in -->
<H3><A NAME="MaxJobsPerUser">MaxJobsPerUser</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
MaxJobsPerUser 100
MaxJobsPerUser 9999
MaxJobsPerUser 0
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>MaxJobsPerUser</CODE> directive controls the maximum number of active jobs
that are allowed for each user. Once a user reaches the limit, new jobs will be
rejected until one of the active jobs is completed, stopped, aborted, or cancelled.

<P>Setting the maximum to 0 disables this functionality. The default
setting is 0.

<!-- NEED 3in -->
<H3><A NAME="MaxLogSize">MaxLogSize</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
MaxLogSize 1048576
MaxLogSize 1m
MaxLogSize 0
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>MaxLogSize</CODE> directive controls the maximum size of each
log file. Once a log file reaches or exceeds the maximum size it is closed
and renamed to <VAR>filename.O</VAR>. This allows you to rotate the logs
automatically. The default size is 1048576 bytes (1MB).

<P>Setting the maximum size to 0 disables log rotation.

<!-- NEED 3in -->
<H3><A NAME="MaxRequestSize">MaxRequestSize</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
MaxRequestSize 10485760
MaxRequestSize 10m
MaxRequestSize 0
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>MaxRequestSize</CODE> directive controls the maximum size of
print files, IPP requests, and HTML form data in HTTP POST requests. The
default limit is 0 which disables the limit check.

<P>Also see the identical
<A HREF="#LimitRequestBody"><CODE>LimitRequestBody</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="Order">Order</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Order Allow,Deny
Order Deny,Allow
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Order</CODE> directive defines the default access control.
The following values are supported:

<UL>

	<LI><CODE>Allow,Deny</CODE> - Allow requests from all
	systems <I>except</I> for those listed in a <CODE>Deny</CODE>
	directive.

	<LI><CODE>Deny,Allow</CODE> - Allow requests only from
	those listed in an <CODE>Allow</CODE> directive.

</UL>

<P>The <CODE>Order</CODE> directive must appear inside a
<A HREF="#Location"><CODE>Location</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="PageLog">PageLog</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
PageLog /var/log/cups/page_log
PageLog /var/log/cups/page_log-%s
PageLog syslog
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>PageLog</CODE> directive sets the name of the page log
file. If the filename is not absolute then it is assumed to be relative
to the <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
default page log file is <VAR>/var/log/cups/page_log</VAR>.

<P>The server name can be included in the filename by using
<CODE>%s</CODE> in the name.

<P>The special name "syslog" can be used to send the page information
to the system log instead of a plain file.

<!-- NEED 3in -->
<H3><A NAME="Port">Port</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Port 631
Port 80
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Port</CODE> directive specifies a port to listen
on. Multiple <CODE>Port</CODE> lines can be specified to listen
on multiple ports. The <CODE>Port</CODE> directive is equivalent
to "<CODE>Listen *:nnn</CODE>". The default port is 631.

<!-- NEED 3in -->
<H3><A NAME="PreserveJobFiles">PreserveJobFiles</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
PreserveJobFiles On
PreserveJobFiles Off
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>PreserveJobFiles</CODE> directive controls whether the
document files of completed, cancelled, or aborted print jobs are
stored on disk.

<P>A value of <CODE>On</CODE> preserves job files until the
administrator purges them with the <CODE>cancel</CODE> command. Jobs
can be restarted (and reprinted) as desired until they are purged.

<P>A value of <CODE>Off</CODE> (the default) removes the job files as
soon as each job is completed, cancelled, or aborted.

<!-- NEED 3in -->
<H3><A NAME="PreserveJobHistory">PreserveJobHistory</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
PreserveJobHistory On
PreserveJobHistory Off
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>PreserveJobHistory</CODE> directive controls whether
the history of completed, cancelled, or aborted print jobs is stored
on disk.

<P>A value of <CODE>On</CODE> (the default) preserves job information
until the administrator purges it with the <CODE>cancel</CODE>
command.

<P>A value of <CODE>Off</CODE> removes the job information as soon as
each job is completed, cancelled, or aborted.

<!-- NEED 3in -->
<H3><A NAME="Printcap">Printcap</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Printcap
Printcap /etc/printcap
Printcap /etc/printers.conf
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Printcap</CODE> directive controls whether or not a
printcap file is automatically generated and updated with a list
of available printers. If specified with no value, then no
printcap file will be generated. The default is to generate a
file named <VAR>/etc/printcap</VAR>.

<P>When a filename is specified (e.g. <VAR>/etc/printcap</VAR>), the
printcap file is written whenever a printer is added or removed. The
printcap file can then be used by applications that are hardcoded to
look at the printcap file for the available printers.

<!-- NEED 3in -->
<H3><A NAME="PrintcapFormat">PrintcapFormat</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
PrintcapFormat BSD
PrintcapFormat Solaris
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>PrintcapFormat</CODE> directive controls the output
format of the printcap file. The default is to generate a BSD
printcap file.

<!-- NEED 3in -->
<H3><A NAME="PrintcapGUI">PrintcapGUI</A></H3>
<HR>

<H4>Example</H4>

<UL><PRE>
PrintcapGUI /usr/bin/glpoptions
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>PrintcapGUI</CODE> directive sets the program to
use when displaying an option panel from an IRIX application
that uses the Impressario print API. The default program is the
ESP Print Pro "glpoptions" GUI.

<P>The program must accept the <CODE>-d</CODE> option to specify
a printer and the <CODE>-o</CODE> option to specify one or more
options. After allowing the user to select/change options, the
program must then write the list of printing options without the
<CODE>-o</CODE> to the standard output.

<!-- NEED 3in -->
<H3><A NAME="ReloadTimeout">ReloadTimeout</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ReloadTimeout 60
ReloadTimeout 3600
ReloadTimeout 0
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ReloadTimeout</CODE> directive sets how long the
scheduler waits for jobs to complete before reloading the server
configuration. The default timeout is 60 seconds.

<!-- NEED 3in -->
<H3><A NAME="RemoteRoot">RemoteRoot</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
RemoteRoot remroot
RemoteRoot root
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>RemoteRoot</CODE> directive sets the username for
unauthenticated root requests from remote hosts. The default
username is <VAR>remroot</VAR>. Setting <CODE>RemoteRoot</CODE>
to <VAR>root</VAR> effectively disables this security mechanism.

<!-- NEED 3in -->
<H3><A NAME="RequestRoot">RequestRoot</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
RequestRoot /var/spool/cups
RequestRoot /foo/bar/spool/cups
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>RequestRoot</CODE> directive sets the directory for
incoming IPP requests and HTML forms. If an absolute path is not
provided then it is assumed to be relative to the
<A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
default request directory is <VAR>/var/spool/cups</VAR>.

<!-- NEED 4in -->
<H3><A NAME="Require">Require</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Require group foo bar
Require user john mary
Require valid-user
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Require</CODE> directive specifies that
authentication is required for the resource. The
<CODE>group</CODE> keyword specifies that the authenticated user
must be a member of one or more of the named groups that follow.

<P>The <CODE>user</CODE> keyword specifies that the
authenticated user must be one of the named users that follow.

<P>The <CODE>valid-user</CODE> keyword specifies that any
authenticated user may access the resource.

<P>The default is to do no authentication. This directive must
appear inside a <A HREF="#Location"><CODE>Location</CODE></A>
directive.

<!-- NEED 3in -->
<H3><A NAME="RIPCache">RIPCache</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
RIPCache 8m
RIPCache 1g
RIPCache 2048k
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>RIPCache</CODE> directive sets the size of the memory
cache used by Raster Image Processor ("RIP") filters such as
<CODE>imagetoraster</CODE> and <CODE>pstoraster</CODE>. The size can
be suffixed with a "k" for kilobytes, "m" for megabytes, or
"g" for gigabytes. The default cache size is "8m", or 8 megabytes.

<!-- NEED 3in -->
<H3><A NAME="RootCertDuration">RootCertDuration</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
RootCertDuration 300
RootCertDuration 0
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>RootCertDuration</CODE> directive controls the
interval between updates of the root authentication certificate.
The default is <CODE>300</CODE> seconds which updates the root
certificate approximately once every 5 minutes. Set the interval
to 0 to disable certificate updates entirely.


<!-- NEED 3in -->
<H3><A NAME="RunAsUser">RunAsUser</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
RunAsUser Yes
RunAsUser No
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>RunAsUser</CODE> directive controls whether the
scheduler runs as the unpriviledged user account (usually <CODE>lp</CODE>).
The default is <CODE>No</CODE> which leaves the scheduler running as
the <CODE>root</CODE> user.

<P><B>Note:</B> Running as a non-priviledged user may prevent
LPD and locally connected printers from working due to
permission problems. The <CODE>lpd</CODE> backend will
automatically use a non-priviledged mode that is not 100%
compliant with RFC 1179. The <CODE>parallel</CODE>,
<CODE>serial</CODE>, and <CODE>usb</CODE> backends will need
write access to the corresponding device files.

<!-- NEED 3in -->
<H3><A NAME="Satisfy">Satisfy</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Satisfy all
Satisfy any
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Satisfy</CODE> directive specifies whether all
conditions must be satisfied to allow access to the resource. If
set to <CODE>all</CODE>, then all authentication and access
control conditions must be satified to allow access.

<P>Setting <CODE>Satisfy</CODE> to <CODE>any</CODE> allows a user to
gain access if the authentication or access control requirements are
satisfied. For example, you might require authentication for remote
access, but allow local access without authentication.

<P>The default is <CODE>all</CODE>. This directive must appear
inside a <A HREF="#Location"><CODE>Location</CODE></A>
directive.

<!-- NEED 3in -->
<H3><A NAME="ServerAdmin">ServerAdmin</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ServerAdmin user@host
ServerAdmin root@foo.bar.com
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ServerAdmin</CODE> directive identifies the email address for the
administrator on the system. By default the administrator email address is
<CODE>root@server</CODE>, where <CODE>server</CODE> is the server name.

<!-- NEED 3in -->
<H3><A NAME="ServerBin">ServerBin</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ServerBin /usr/lib/cups
ServerBin /foo/bar/lib/cups
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ServerBin</CODE> directive sets the directory for
server-run executables. If an absolute path is not provided then it is
assumed to be relative to the
<A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
default executable directory is <VAR>/usr/lib/cups</VAR>.

<!-- NEED 3in -->
<H3><A NAME="ServerCertificate">ServerCertificate</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ServerCertificate /etc/cups/ssl/server.crt
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ServerCertificate</CODE> directive specifies the
location of the SSL certificate file used by the server when
negotiating encrypted connections. The certificate must not be
encrypted (password protected) since the scheduler normally runs
in the background and will be unable to ask for a password.
The default certificate file is <VAR>/etc/cups/ssl/server.crt</VAR>.

<!-- NEED 3in -->
<H3><A NAME="ServerKey">ServerKey</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ServerKey /etc/cups/ssl/server.key
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ServerKey</CODE> directive specifies the location
of the SSL private key file used by the server when negotiating
encrypted connections. The default key file is
<VAR>/etc/cups/ssl/server.crt</VAR>.

<!-- NEED 3in -->
<H3><A NAME="ServerName"></A>ServerName</H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ServerName foo.domain.com
ServerName myserver.domain.com
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ServerName</CODE> directive specifies the hostname that is
reported to clients. By default the server name is the hostname.

<!-- NEED 3in -->
<H3><A NAME="ServerRoot">ServerRoot</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ServerRoot /etc/cups
ServerRoot /foo/bar/cups
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ServerRoot</CODE> directive specifies the absolute path to
the server configuration and state files. It is also used to resolve
relative paths in the <VAR>cupsd.conf</VAR> file. The default server
directory is <VAR>/etc/cups</VAR>.

<!-- NEED 3in -->
<H3><A NAME="ServerTokens">ServerTokens</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ServerTokens None
ServerTokens ProductOnly
ServerTokens Major
ServerTokens Minor
ServerTokens Minimal
ServerTokens OS
ServerTokens Full
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ServerTokens</CODE> directive specifies the information
that is included in the Server header of HTTP responses. The default value
is <tt>Minor</tt> which generates "CUPS/1.1".

<!-- NEED 3in -->
<H3><A NAME="SSLListen">SSLListen</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
SSLListen 127.0.0.1:443
SSLListen 192.0.2.1:443
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>SSLListen</CODE> directive specifies a network
address and port to listen for secure connections. Multiple
<CODE>SSLListen</CODE> directives can be provided to listen on
multiple addresses.

<P>The <CODE>SSLListen</CODE> directive is similar to the
<A HREF="#SSLPort"><CODE>SSLPort</CODE></A> directive but allows
you to restrict access to specific interfaces or networks.

<!-- NEED 3in -->
<H3><A NAME="SSLPort">SSLPort</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
SSLPort 443
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>SSLPort</CODE> directive specifies a port to listen
on for secure connections. Multiple <CODE>SSLPort</CODE> lines
can be specified to listen on multiple ports.

<!-- NEED 3in -->
<H3><A NAME="SystemGroup">SystemGroup</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
SystemGroup sys
SystemGroup system
SystemGroup root
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>SystemGroup</CODE> directive specifies the system
administration group for <CODE>System</CODE> authentication. More
information can be found later in this chapter in
<A HREF="#PRINTING_SECURITY">"Printing System Security"</A>.

<!-- NEED 3in -->
<H3><A NAME="TempDir">TempDir</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
TempDir /var/tmp
TempDir /foo/bar/tmp
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>TempDir</CODE> directive specifies an absolute path for
the directory to use for temporary files. The default directory is
<VAR>/var/tmp</VAR>.

<P>Temporary directories must be world-writable and should have the
"sticky" permission bit enabled so that other users cannot delete
filter temporary files. The following commands will create an
appropriate temporary directory called <VAR>/foo/bar/tmp</VAR>:

<UL><PRE>
<B>mkdir /foo/bar/tmp ENTER</B>
<B>chmod a+rwxt /foo/bar/tmp ENTER</B>
</PRE></UL>

<!-- NEED 3in -->
<H3><A NAME="Timeout">Timeout</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Timeout 300
Timeout 90
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Timeout</CODE> directive controls the amount of time to
wait before an active HTTP or IPP request times out. The default
timeout is 300 seconds.

<!-- NEED 3in -->
<H3><A NAME="User">User</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
User lp
User guest
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>User</CODE> directive specifies the UNIX user that
filter and CGI programs run as. The default user is <CODE>lp</CODE>.



<H2>Changing the Client Configuration</H2>

<P>The CUPS client application (<CODE>lp</CODE>, <CODE>lpr</CODE>, and so forth)
use the <VAR>/etc/cups/client.conf</VAR> file for default settings.
The client application also look in the user's home directory for a file called <VAR>.cupsrc</VAR>.
Each directive is listed on a line by itself followed by its value. Comments are introduced
using the number sign ("#") character at the beginning of a line.

<P>Since the client configuration file consists of plain text, you can
use your favorite text editor to make changes to it.

<!-- NEED 4in -->
<H2>Client Directives</H2>

<P>The <VAR>client.conf</VAR> file contains two directives that
determine how the client behaves:</P>

<UL>
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD VALIGN="TOP">

        <LI><A HREF="#Encryption"><CODE>Encryption</CODE></A>
        <LI><A HREF="#ServerName"><CODE>ServerName</CODE></A>

</TD>
</TR>
</TABLE>
</UL>

<!-- NEED 3in -->
<H3><A NAME="Encryption">Encryption</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Encryption Never
Encryption IfRequested
Encryption Required
Encryption Always
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Encryption</CODE> directive specifies the default encryption settings for the client.
The default setting is <VAR>IfRequested</VAR>.


<!-- NEED 3in -->
<H3><A NAME="ServerName">ServerName</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
ServerName foo.bar.com
ServerName 11.22.33.44
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>ServerName</CODE> directive specifies sets the remote server that is to be used
for all client operations.  That is, it redirects all client requests to the remote server.

The default is to use the local server ("<VAR>localhost</VAR>").


<!-- NEW PAGE -->
<H2>Changing the Printer Configuration</H2>

<P>The CUPS scheduler (cupsd) uses the <VAR>/etc/cups/printers.conf</VAR> file 
to store the list of available printers.  This file contains only locally defined
printers, but not remote printers that are created automatically.  Each directive
is listed on a line by itself followed by its value. Comments are introduced 
using the number sign ("#") character at the beginning of a line.

<P>Since the printer configuration file consists of plain text, you can
use your favorite text editor to make changes to it.

<!-- NEED 4in -->
<H2>Printer Directives</H2>

<P>The <VAR>printers.conf</VAR> file contains many directives that
determine how the printer behaves:</P>

<UL>
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD VALIGN="TOP">

	<LI><A HREF="#Accepting"><CODE>Accepting</CODE></A>
	<LI><A HREF="#AllowUser"><CODE>AllowUser</CODE></A>
	<LI><A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
	<LI><A HREF="#DenyUser"><CODE>DenyUser</CODE></A>
	<LI><A HREF="#DeviceURI"><CODE>DeviceURI</CODE></A>

</TD>
<TD VALIGN="TOP">
&nbsp;&nbsp;&nbsp;
</TD>
<TD VALIGN="TOP">

	<LI><A HREF="#Info"><CODE>Info</CODE></A>
	<LI><A HREF="#JobSheets"><CODE>JobSheets</CODE></A>
	<LI><A HREF="#KLimit"><CODE>KLimit</CODE></A>
	<LI><A HREF="#PrinterLocation"><CODE>Location</CODE></A>
	<LI><A HREF="#PageLimit"><CODE>PageLimit</CODE></A>

</TD>
<TD VALIGN="TOP">
&nbsp;&nbsp;&nbsp;
</TD>
<TD VALIGN="TOP">

	<LI><A HREF="#Printer"><CODE>Printer</CODE></A>
<LI><A HREF="#QuotaPeriod"><CODE>QuotaPeriod</CODE></A>
<LI><A HREF="#State"><CODE>State</CODE></A>
<LI><A HREF="#StateMessage"><CODE>StateMessage</CODE></A>

</TD>
</TR>
</TABLE>
</UL>

<!-- NEED 3in -->
<H3><A NAME="Accepting">Accepting</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Accepting yes

Accepting no
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Accepting</CODE> directive defines the initial Boolean
value for the <VAR>printer-is-accepting-job</VAR> attribute which can
be set by the <CODE>accept</CODE> and <CODE>reject</CODE> commands. 

<P>This directive must appear inside a <A HREF="#Printer"><CODE>Printer</CODE></A> 
or <A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.  

<!-- NEED 3in -->
<H3><A NAME="AllowUser">AllowUser</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
AllowUser foo_user
AllowUser bar_user
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>AllowUser</CODE> directive adds a username to the 
<VAR>requesting-user-name-allowed</VAR> attribute which can be set
by the <CODE>lpadmin -u</CODE> command.

<P>This directive must appear inside a <A HREF="#Printer"><CODE>Printer</CODE></A> 
or <A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.  

<!-- NEED 3in -->
<H3><A NAME="DefaultPrinter">DefaultPrinter</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
&lt;DefaultPrinter name/&gt;
...
&lt;/Printer&gt;
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>DefaultPrinter</CODE> directive begins a printer definition 
for the default server destination.  
It can be added by the <CODE>lpadmin</CODE> command or if already defined, 
set as default by the <CODE>lpoptions -d</CODE> command.</P>

<!-- NEED 3in -->
<H3><A NAME="DenyUser">DenyUser</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
DenyUser foo_user
DenyUser bar_user
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>DenyUser</CODE> directive adds a username to the 
<VAR>requesting-user-name-allowed</VAR> attribute which can be set
by the <CODE>lpadmin -u</CODE> command.</P>

<P>This directive must appear inside a <A HREF="#Printer"><CODE>Printer</CODE></A> 
or <A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.</P>

<!-- NEED 3in -->
<H3><A NAME="DeviceURI">DeviceURI</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
DeviceURI socket://foo.bar.com:9100
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>DeviceURI</CODE> directive defines the value of the 
<VAR>device-uri-attribute</VAR> attribute which can be set by 
the <CODE>lpadmin -v</CODE> command.

<P>This directive must appear inside a <A HREF="#Printer"><CODE>Printer</CODE></A> 
or <A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.  

<!-- NEED 3in -->
<H3><A NAME="Info">Info</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Info My Printer
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Info</CODE> directive defines the string for the 
<VAR>printer-info</VAR> attribute which can be set by the 
<CODE>lpadmin -D</CODE> command.</P>

<P>This directive must appear inside a <A HREF="#Printer"><CODE>Printer</CODE></A> 
or <A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.</P>

<!-- NEED 6in -->
<H3><A NAME="JobSheets">JobSheets</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
JobSheets none,standard
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>JobSheets</CODE> directive specifies the default banner pages 
to print before and after a print job.
In the above example, only a <VAR>standard</VAR> banner will print after each job.</P>

<P>The <CODE>lpoptions -o job-sheets=</CODE> command can be used to set banners. 
For example, the following command would produce the same results of a 
<VAR>standard</VAR> banner at the end of each print job for the default printer.</P>

<UL><B>
lpoptions -o job-sheets=none,standard
</B></UL>

<P>If only one banner file is specified, it will be printed before the 
files in the job. If a second banner file is specified, it is printed 
after the files in the job.</P>

<P>The available banner pages depend on the local system configuration;
 CUPS includes the following banner files:</P>

<UL>
<LI><CODE>none</CODE> - Do not produce a banner page.</LI>
<LI><CODE>classified</CODE> - A banner page with a &quot;classified&quot; label at the top and bottom.</LI>
<LI><CODE>confidential</CODE> - A banner page with a &quot;confidential&quot; label at the top and bottom.</LI>
<LI><CODE>secret</CODE> - A banner page with a &quot;secret&quot; label at the top and bottom.</LI>
<LI><CODE>standard</CODE> - A banner page with no label at the top and bottom.</LI>
<LI><CODE>topsecret</CODE> - A banner page with a &quot;top secret&quot; label at the top and bottom.</LI>
<LI><CODE>unclassified</CODE> - A banner page with an &quot;unclassified&quot; label at the top and bottom.</LI>
</UL>

<P>This directive must appear inside a <A HREF="#Printer"><CODE>Printer</CODE></A> 
or <A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.  

<!-- NEED 3in -->
<H3><A NAME="KLimit">KLimit</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
KLimit 1234
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>KLimit</CODE> directive defines the value of the 
<VAR>job-k-limit</VAR> attribute which can be set by the 
<CODE>lpadmin -o job-k-limit=</CODE> command.

<P>This directive must appear inside a <A HREF="#Printer"><CODE>Printer</CODE></A> 
or <A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.</P>

<!-- NEED 6in -->
<H3><A NAME="PrinterLocation">Location</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Location Building 3321
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Location</CODE> directive defines the string for the 
<VAR>printer-location</VAR> attribute which can be set by the 
<CODE>lpadmin -L</CODE> command.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
	<TD>
	<B>NOTE:</B>

	<P>Do not confuse this <CODE>Location</CODE> directive with the 
	one in cupsd.conf.  They are completely different.
	</TD>
</TR>
</TABLE></CENTER>

<P>This directive must appear inside a <A HREF="#Printer"><CODE>Printer</CODE></A> 
or <A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.</P>

<!-- NEED 3in -->
<H3><A NAME="PageLimit">PageLimit</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
PageLimit 1234
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>PageLimit</CODE> directive defines the value of the 
<VAR>job-page-limit</VAR> attribute which can be set
by the <CODE>lpadmin -o job-page-limit=</CODE> command.</P>

<P>This directive must appear inside a <A HREF="#Printer"><CODE>Printer</CODE></A> 
or <A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.</P>

<!-- NEED 3in -->
<H3><A NAME="Printer">Printer</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
&lt;Printer name/&gt;
...
&lt;/Printer&gt;
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Printer</CODE> directive begins a printer definition.
It can be added by the <CODE>lpadmin</CODE> command.

<!-- NEED 3in -->
<H3><A NAME="QuotaPeriod">QuotaPeriod</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
QuotaPeriod 604800
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>QuotaPeriod</CODE> directive defines the value of the 
<VAR>job-quota-period</VAR> attribute which can be set
by the <CODE>lpadmin -o job-quota-period=</CODE> command.</P>

<P>This directive must appear inside a <A HREF="#Printer"><CODE>Printer</CODE></A> 
or <A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.</P>

<!-- NEED 3in -->
<H3><A NAME="State">State</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
State stopped
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>State</CODE> directive defines the initial value of the 
<VAR>printer-state</VAR> attribute.  The strings <VAR>idle</VAR> and 
<VAR>stopped</VAR> correspond to the IPP enumeration values.</P>

<P>This directive must appear inside a <A HREF="#Printer"><CODE>Printer</CODE></A> 
or <A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.</P>

<!-- NEED 6in -->
<H3><A NAME="StateMessage">StateMessage</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
StateMessage Ready to print.
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>StateMessage</CODE> directive defines the initial string for the 
<VAR>printer-state-message</VAR> attribute.  
The following are some example messages:</P>

<UL>
<LI>Connected to <VAR>host_name</VAR>...
<LI>Connecting to <VAR>printer_queue</VAR> on port <VAR>port_number</VAR>...
<LI>Network host <VAR>host_name</VAR> is busy; will retry in 30 seconds...
<LI>Printer busy; will retry in 10 seconds...
<LI>Printer is busy; retrying print job...
<LI>Print file accepted - job ID <VAR>id_number</VAR>.
<LI>Ready to print.
<LI>Waiting for job to complete
</UL>

<P>This directive must appear inside a <A HREF="#Printer"><CODE>Printer</CODE></A> 
or <A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.</P>


<!-- NEW PAGE -->
<H2>Changing the Classes Configuration</H2>

<P>The CUPS scheduler (cupsd) uses the <VAR>/etc/cups/classes.conf</VAR> file
to store the list of available classes.  This file contains only locally defined
classes, but not remote or implicit classes that are created automatically.
Each directive is listed on a line by itself followed by its value.
Comments are introduced using the number sign ("#") character at the beginning of a line.

<P>Since the classes configuration file consists of plain text, you can
use your favorite text editor to make changes to it.

<!-- NEED 4in -->
<H2>Classes Directives</H2>

<P>The <VAR>classes.conf</VAR> file contains many directives that
determine how the classes behaves:</P>

<UL>
<TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
<TR>
<TD VALIGN="TOP">

        <LI><A HREF="#ClassAccepting"><CODE>Accepting</CODE></A>
        <LI><A HREF="#ClassAllowUser"><CODE>AllowUser</CODE></A>
        <LI><A HREF="#Class"><CODE>Class</CODE></A>
        <LI><A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A>
        <LI><A HREF="#ClassDenyUser"><CODE>DenyUser</CODE></A>

</TD>
<TD VALIGN="TOP">
&nbsp;&nbsp;&nbsp;
</TD>
<TD VALIGN="TOP">

        <LI><A HREF="#ClassInfo"><CODE>Info</CODE></A>
        <LI><A HREF="#ClassJobSheets"><CODE>JobSheets</CODE></A>
        <LI><A HREF="#ClassKLimit"><CODE>KLimit</CODE></A>
        <LI><A HREF="#ClassLocation"><CODE>Location</CODE></A>
        <LI><A HREF="#ClassPageLimit"><CODE>PageLimit</CODE></A>

</TD>
<TD VALIGN="TOP">
&nbsp;&nbsp;&nbsp;
</TD>
<TD VALIGN="TOP">

        <LI><A HREF="#ClassPrinter"><CODE>Printer</CODE></A>
        <LI><A HREF="#ClassQuotaPeriod"><CODE>QuotaPeriod</CODE></A>
        <LI><A HREF="#ClassState"><CODE>State</CODE></A>
        <LI><A HREF="#ClassStateMessage"><CODE>StateMessage</CODE></A>

</TD>
</TR>
</TABLE>
</UL>

<!-- NEED 3in -->
<H3><A NAME="ClassAccepting">Accepting</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Accepting yes

Accepting no
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Accepting</CODE> directive defines the initial Boolean
value for the <VAR>printer-is-accepting-job</VAR> attribute which can
be set by the <CODE>accept</CODE> and <CODE>reject</CODE> commands.

<P>This directive must appear inside a <A HREF="#Class"><CODE>Class</CODE></A>
or <A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="ClassAllowUser">AllowUser</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
AllowUser foo_user
AllowUser bar_user
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>AllowUser</CODE> directive adds a username to the
<VAR>requesting-user-name-allowed</VAR> attribute which can be set
by the <CODE>lpadmin -u</CODE> command.

<P>This directive must appear inside a <A HREF="#Class"><CODE>Class</CODE></A>
or <A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A> directive.


<!-- NEED 3in -->
<H3><A NAME="Class">Class</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
&lt;Class name/&gt;
...
&lt;/Class&gt;
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Class</CODE> directive begins a class definition.
It can be added by the <CODE>lpadmin -c</CODE> command.</P>

<!-- NEED 3in -->
<H3><A NAME="DefaultClass">DefaultClass</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
&lt;DefaultClass name/&gt;
...
&lt;/DefaultClass&gt;
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>DefaultClass</CODE> directive begins a class definition
for the default server destination.
It can be added by the <CODE>lpadmin -c</CODE> command or if already defined,
set as default by the <CODE>lpoptions -d</CODE> command.</P>

<!-- NEED 3in -->
<H3><A NAME="ClassDenyUser">DenyUser</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
DenyUser foo_user
DenyUser bar_user
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>DenyUser</CODE> directive adds a username to the
<VAR>requesting-user-name-allowed</VAR> attribute which can be set
by the <CODE>lpadmin -u</CODE> command.</P>

<P>This directive must appear inside a <A HREF="#Class"><CODE>Class</CODE></A>
or <A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="ClassInfo">Info</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Info My Printer
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Info</CODE> directive defines the string for the
<VAR>printer-info</VAR> attribute which can be set by the
<CODE>lpadmin -D</CODE> command.</P>

<P>This directive must appear inside a <A HREF="#Class"><CODE>Class</CODE></A>
or <A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A> directive.

<!-- NEED 6in -->
<H3><A NAME="ClassJobSheets">JobSheets</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
JobSheets none,standard
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>JobSheets</CODE> directive specifies the default banner pages
to print before and after a print job.
In the above example, only a <VAR>standard</VAR> banner will print after each job.</P>

<P>The <CODE>lpoptions -o job-sheets=</CODE> command can be used to set banners.
For example, the following command would produce the same results of a
<VAR>standard</VAR> banner at the end of each print job for the default class.</P>

<UL><B>
lpoptions -o job-sheets=none,standard
</B></UL>

<P>If only one banner file is specified, it will be printed before the
files in the job. If a second banner file is specified, it is printed
after the files in the job.</P>

<P>The available banner pages depend on the local system configuration;
 CUPS includes the following banner files:</P>

<UL>
<LI><CODE>none</CODE> - Do not produce a banner page.</LI>
<LI><CODE>classified</CODE> - A banner page with a &quot;classified&quot; label at the top and bottom.</LI>
<LI><CODE>confidential</CODE> - A banner page with a &quot;confidential&quot; label at the top and bottom.</LI>
<LI><CODE>secret</CODE> - A banner page with a &quot;secret&quot; label at the top and bottom.</LI>
<LI><CODE>standard</CODE> - A banner page with no label at the top and bottom.</LI>
<LI><CODE>topsecret</CODE> - A banner page with a &quot;top secret&quot; label at the top and bottom.</LI>
<LI><CODE>unclassified</CODE> - A banner page with an &quot;unclassified&quot; label at the top and bottom.</LI>
</UL>

<P>This directive must appear inside a <A HREF="#Class"><CODE>Class</CODE></A>
or <A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="ClassKLimit">KLimit</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
KLimit 1234
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>KLimit</CODE> directive defines the value of the
<VAR>job-k-limit</VAR> attribute which can be set by the
<CODE>lpadmin -o job-k-limit=</CODE> command.

<P>This directive must appear inside a <A HREF="#Class"><CODE>Class</CODE></A>
or <A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A> directive.

<!-- NEED 6in -->
<H3><A NAME="ClassLocation">Location</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Location Building 3321
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Location</CODE> directive defines the string for the
<VAR>printer-location</VAR> attribute which can be set by the
<CODE>lpadmin -L</CODE> command.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
        <TD>
        <B>NOTE:</B>

        <P>Do not confuse this <CODE>Location</CODE> directive with the
        one in cupsd.conf.  They are completely different.
        </TD>
</TR>
</TABLE></CENTER>

<P>This directive must appear inside a <A HREF="#Class"><CODE>Class</CODE></A>
or <A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="ClassPageLimit">PageLimit</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
PageLimit 1234
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>PageLimit</CODE> directive defines the value of the
<VAR>job-page-limit</VAR> attribute which can be set
by the <CODE>lpadmin -o job-page-limit=</CODE> command.</P>

<P>This directive must appear inside a <A HREF="#Class"><CODE>Class</CODE></A>
or <A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="ClassPrinter">Printer</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
Printer foo
Printer bar
Printer foo@bar
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>Printer</CODE> directive adds a printer to the class.
It can be added by the <CODE>lpadmin -c</CODE> command.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
        <TD>
        <B>NOTE:</B>

        <P>Do not confuse this <CODE>Printer</CODE> directive with the
        one in printers.conf.  They are completely different.
        </TD>
</TR>
</TABLE></CENTER>

<P>This directive must appear inside a <A HREF="#Class"><CODE>Class</CODE></A>
or <A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A> directive.</P>

<!-- NEED 3in -->
<H3><A NAME="ClassQuotaPeriod">QuotaPeriod</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
QuotaPeriod 604800
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>QuotaPeriod</CODE> directive defines the value of the
<VAR>job-quota-period</VAR> attribute which can be set
by the <CODE>lpadmin -o job-quota-period=</CODE> command.</P>

<P>This directive must appear inside a <A HREF="#Class"><CODE>Class</CODE></A>
or <A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A> directive.

<!-- NEED 3in -->
<H3><A NAME="ClassState">State</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
State stopped
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>State</CODE> directive defines the initial value of the
<VAR>printer-state</VAR> attribute.  The strings <VAR>idle</VAR> and
<VAR>stopped</VAR> correspond to the IPP enumeration values.</P>

<P>This directive must appear inside a <A HREF="#Class"><CODE>Class</CODE></A>
or <A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A> directive.

<!-- NEED 6in -->
<H3><A NAME="ClassStateMessage">StateMessage</A></H3>
<HR>

<H4>Examples</H4>

<UL><PRE>
StateMessage Ready to print.
</PRE></UL>

<H4>Description</H4>

<P>The <CODE>StateMessage</CODE> directive defines the initial string for the
<VAR>printer-state-message</VAR> attribute.
The following are some example messages:</P>

<UL>
<LI>Connected to <VAR>host_name</VAR>...
<LI>Connecting to <VAR>class_queue</VAR> on port <VAR>port_number</VAR>...
<LI>Network host <VAR>host_name</VAR> is busy; will retry in 30 seconds...
<LI>Printer busy; will retry in 10 seconds...
<LI>Printer is busy; retrying print job...
<LI>Print file accepted - job ID <VAR>id_number</VAR>.
<LI>Ready to print.
<LI>Waiting for job to complete
</UL>

<P>This directive must appear inside a <A HREF="#Class"><CODE>Class</CODE></A>
or <A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A> directive.</P>




<!-- NEW PAGE -->
<H2><A NAME="PRINTING_SECURITY">Printing System Security</A></H2>

<P>CUPS provides support for address, certificate, and password (Basic
and Digest) based authentication and access control. Certificate and
password authentication provide ways to limit access to individual
people or groups.

<P>Address based access control allows you to limit access to specific
systems, networks, or domains. While this does not provide authentication,
it does allow you to limit the potential users of your system efficiently.

<P>CUPS maintains a list of locations that have access control and/or
authentication enabled. Locations are specified using the
<A HREF="#Location"><CODE>Location</CODE></A> directive:

<UL><PRE>
&lt;Location /resource&gt;
<A HREF="#AuthClass">AuthClass</A> ...
<A HREF="#AuthGroupName">AuthGroupName</A> ...
<A HREF="#AuthType">AuthType</A> ...

<A HREF="#Order">Order</A> ...
<A HREF="#Allow">Allow</A> from ...
<A HREF="#Deny">Deny</A> from ...
&lt;/Location&gt;
</PRE></UL>

<P>Locations generally follow the directory structure of the
<A HREF="#DocumentRoot"><CODE>DocumentRoot</CODE></A> directory, however
CUPS does have several virtual locations for administration, classes, jobs,
and printers:

<CENTER><TABLE BORDER="1">
<TR>
<TH>Location</TH>
<TH>Description</TH>
</TR>
<TR>
<TD>/admin</TD>
<TD>The path for all administration operations.</TD>
</TR>
<TR>
<TD>/classes</TD>
<TD>The path for all classes.</TD>
</TR>
<TR>
<TD>/classes/name</TD>
<TD>The resource for class <CODE>name</CODE>.</TD>
</TR>
<TR>
<TD>/jobs</TD>
<TD>The path for all jobs.</TD>
</TR>
<TR>
<TD>/jobs/id</TD>
<TD>The resource for job <CODE>id</CODE>.</TD>
</TR>
<TR>
<TD>/printers</TD>
<TD>The path for all printers.</TD>
</TR>
<TR>
<TD>/printers/name</TD>
<TD>The path for printer <CODE>name</CODE>.</TD>
</TR>
<TR>
<TD>/printers/name.ppd</TD>
<TD>The PPD file path for printer <CODE>name</CODE>.</TD>
</TR>
</TABLE></CENTER>

<H3><A NAME="CERTIFICATES">Authentication Using Certificates</A></H3>

<P>CUPS supports a local certificate-based authentication scheme that
can be used in place of <CODE>Basic</CODE> or <CODE>Digest</CODE>
authentication by clients connecting through the <CODE>localhost</CODE>
interface. Certificate authentication is not supported or allowed from
clients on any other interface.

<P>Certificates are 128-bit random numbers that refer to an internal
authentication record in the server. A client connecting via the
<CODE>localhost</CODE> interface sends a request with an
authorization header of:

<UL><PRE>
Authorization: Local 0123456789ABCDEF0123456789ABCDEF
</PRE></UL>

<P>The server then looks up the local certificate and authenticates
using the username associated with it.

<P>Certificates are generated by the server automatically and stored in
the <VAR>/etc/cups/certs</VAR> directory using the process ID of the
CGI program started by the server. Certificate files are only readable
by the <A HREF="#User"><CODE>User</CODE></A> and
<A HREF="#Group"><CODE>Group</CODE></A> defined in the
<VAR>cupsd.conf</VAR> file. When the CGI program ends the certificate
is removed and invalidated automatically.

<P>The special file <VAR>/etc/cups/certs/0</VAR> defines the <I>root
certificate</I> which can be used by any client running as the super-user
or another user that is part of the group defined by the
<A HREF="#SystemGroup"><CODE>SystemGroup</CODE></A> directive. The
root certificate is automatically regenerated every 5 minutes.

<H3>Using Basic Authentication</H3>

<P>Basic authentication uses UNIX users and passwords to authenticate
access to resources such as printers and classes, and to limit access
to administrative functions.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
<TD>
<B>NOTE:</B>

<P>Basic authentication sends the username and password Base64
encoded from the client to the server, so it offers no
protection against eavesdropping. This means that a malicious
user can monitor network packets and discover valid users and
passwords that could result in a serious compromise in network
security. Use Basic authentication with extreme care.
</TD>
</TR>
</TABLE></CENTER>

<P>The CUPS implementation of Basic authentication does not allow access
through user accounts without a password. If you try to authenticate
using an account without a password, your access will be immediately
blocked.

<P>Once a valid username and password is authenticated by CUPS, any
additional group membership requirements are checked.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
<TD>
<B>NOTE:</B>

<P>The root user is considered by CUPS to be a member of every
group.
</TD>
</TR>
</TABLE></CENTER>

<!-- NEED 1in -->
<P>Use the <CODE>AuthType</CODE> directive to enable Basic authentication:

<UL><PRE>
AuthType Basic
</PRE></UL>

<!-- NEED 7in -->
<H3>Using Digest Authentication</H3>

<P>Digest authentication uses users and passwords defined in the
<VAR>/etc/cups/passwd.md5</VAR> file to authenticate access to
resources such as printers and classes, and to limit access to
administrative functions.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
<TD>
<B>NOTE:</B>

<P>Unlike Basic authentication, Digest passes the MD5 sum
(basically a complicated checksum) of the username and password
instead of the strings themselves. Also, Digest authentication
does not use the UNIX password file, so if an attacker does
discover the original password it is less likely to result in a
serious security problem so long as you use a different UNIX
password than the corresponding Digest password.

<P>The current CUPS implementation of Digest authentication
uses the client's hostname or IP address for the "nonce" value.
The nonce value is an additional string added to the username
and password to make guessing the password more difficult. The
server checks that the nonce value matches the client's hostname
or address and rejects the MD5 sum if it doesn't.  Future versions
of CUPS will support Digest "session" authentication which adds
the request data to the MD5 sum, providing even better
authentication and security.

<P>Digest authentication does not guarantee that an attacker
cannot gain unauthorized access, but it is safer than Basic
authentication and should be used in place of Basic
authentication whenever possible. <B>Support for Digest
authentication in web browsers is not yet universally
available.</B>
</TD>
</TR>
</TABLE></CENTER>

<!-- NEED 2in -->
<P>The <CODE>lppasswd(1)</CODE> command is used to add, change, or
remove accounts from the <VAR>passwd.md5</VAR> file. To add a
user to the default system group, type:

<UL><PRE>
<B>lppasswd -a user ENTER</B>
Password: <B>(password) ENTER</B> [password is not echoed]
Password again: <B>(password) ENTER</B> [password is not echoed]
</PRE></UL>

<!-- NEED 2in -->
<P>Once added, a user can change his/her password by typing:

<UL><PRE>
<B>lppasswd ENTER</B>
Old password: <B>(password) ENTER</B> [password is not echoed]
Password: <B>(password) ENTER</B> [password is not echoed]
Password again: <B>(password) ENTER</B> [password is not echoed]
</PRE></UL>

<!-- NEED 1in -->
<P>To remove a user from the password file, type:

<UL><PRE>
<B>lppasswd -x user ENTER</B>
</PRE></UL>

<P>Once a valid username and password is authenticated by CUPS, any
additional group membership requirements are checked.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
<TD>
<B>NOTE:</B>

<P>The root user is considered by CUPS to be a member of every
group.
</TD>
</TR>
</TABLE></CENTER>

<P>Use the <CODE>AuthType</CODE> directive to enable Digest authentication:

<UL><PRE>
AuthType Digest
</PRE></UL>

<H3>System and Group Authentication</H3>

<P>The <A HREF="#AuthClass"><CODE>AuthClass</CODE></A> directive controls
the level of authentication to perform. <CODE>System</CODE> and
<CODE>Group</CODE> authentication extend the normal user-based authentication
to require membership in a UNIX group. For <CODE>System</CODE> authentication
each user must belong to the <CODE>sys</CODE>, <CODE>system</CODE>, or
<CODE>root</CODE> group; the actual group depends on the operating system.

<P>For <CODE>Group</CODE> authentication each user must belong to the
group named by the <A HREF="#AuthGroupName"><CODE>AuthGroupName</CODE></A>
directive:

<UL><PRE>
&lt;Location /path&gt;
AuthType Digest
AuthClass Group
AuthGroupName mygroup
&lt;/Location&gt;
</PRE></UL>

<P>The named group must be a valid UNIX user group, usually defined in the
<VAR>/etc/group</VAR> or <VAR>/etc/netgroup</VAR> files. Additionally, when
using Digest authentication you need to create user accounts with the named
group:

<UL><PRE>
<B>lppasswd -g mygroup -a user ENTER</B>
Password: <B>(password) ENTER</B> [password is not echoed]
Password again: <B>(password) ENTER</B> [password is not echoed]
</PRE></UL>

<!-- NEW PAGE -->
<H2><A NAME="PRINTER_ACCOUNTING">Printer Accounting</A></H2>

<P>CUPS maintains a log of all accesses, errors, and
pages that are printed. The log files are normally stored in the
<VAR>/var/log/cups</VAR> directory. You can change this by
editing the <VAR>/etc/cups/cupsd.conf</VAR> configuration file.

<H3>The access_log File</H3>

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

<UL><PRE>
host group user date-time \"method resource version\" status bytes

127.0.0.1 - - [20/May/1999:19:20:29 +0000] "POST /admin/ HTTP/1.1" 401 0
127.0.0.1 - mike [20/May/1999:19:20:31 +0000] "POST /admin/ HTTP/1.1" 200 0
</PRE></UL>

<P>The <I>host</I> field will normally only be an IP address unless you
have enabled the <A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A>
directive in the <VAR>cupsd.conf</VAR> file.

<P>The <I>group</I> field always contains "-" in CUPS.

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

<P>The <I>date-time</I> field is the date and time of the request in local time
and is in the format:

<UL><PRE>
[DD/MON/YYYY:HH:MM:SS +ZZZZ]
</PRE></UL>

<P>where <I>ZZZZ</I> is the timezone offset in hours and minutes
from coordinated universal time (UTC). UTC may sometimes be
referred to as GMT or ZULU on legacy systems.</P>

<P>The <I>method</I> field is the HTTP method used ("GET", "PUT", "POST", etc.)

<P>The <I>resource</I> field is the filename of the requested resource.

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

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

<P>The <I>bytes</I> field contains the number of bytes in the request.
For POST requests the <I>bytes</I> field contains the number of bytes
that was received from the client.

<H3>The error_log File</H3>

<P>The <VAR>error_log</VAR> file lists messages from the scheduler (errors,
warnings, etc.):

<UL><PRE>
level date-time message

I [20/May/1999:19:18:28 +0000] Job 1 queued on 'DeskJet' by 'mike'.
I [20/May/1999:19:21:02 +0000] Job 2 queued on 'DeskJet' by 'mike'.
I [20/May/1999:19:22:24 +0000] Job 2 was cancelled by 'mike'.
</PRE></UL>

<P>The <I>level</I> field contains the type of message:

<UL>

<LI><CODE>E</CODE> - An error occurred.

<LI><CODE>W</CODE> - The server was unable to perform some action.

<LI><CODE>I</CODE> - Informational message.

<LI><CODE>D</CODE> - Debugging message.

</UL>

<P>The <I>date-time</I> field contains the date and time of when the page
started printing. The format of this field is identical to the <I>data-time</I>
field in the <VAR>access_log</VAR> file.

<P>The <I>message</I> fields contains a free-form textual message.

<H3>The page_log File</H3>

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

<UL><PRE>
printer user job-id date-time page-number num-copies job-billing hostname

DeskJet root 2 [20/May/1999:19:21:05 +0000] 1 0 acme-123 localhost
</PRE></UL>

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

<P>The <I>user</I> field contains the name of the user (the IPP
<CODE>requesting-user-name</CODE> attribute) that submitted this file for
printing.

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

<P>The <I>date-time</I> field contains the date and time of when the page
started printing. The format of this field is identical to the <I>data-time</I>
field in the <VAR>access_log</VAR> file.

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

<P>The <I>job-billing</I> field contains a copy of the
<CODE>job-billing</CODE> attribute provided with the IPP
<CODE>create-job</CODE> or <CODE>print-job</CODE> requests or "-" if none
was provided.

<P>The <I>hostname</I> field contains the name of the host (the
IPP <CODE>job-originating-host-name</CODE> attribute) that
originated the print job.

<!-- NEW PAGE -->
<H2><A NAME="FILE_TYPING_FILTERING">File Typing and Filtering</A></H2>

<P>CUPS provides a MIME-based file typing and filtering mechanism to
convert files to a printable format for each printer. On startup the
CUPS server reads MIME database files from the <VAR>/etc/cups</VAR>
directory (or a directory specified by the
<A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directive) to build
a file type and conversion database in memory. These database files are
plain ASCII text and can be edited with your favorite text editor.

<P>The <VAR>mime.types</VAR> and <VAR>mime.convs</VAR> files define the
standard file types and filters that are available on the system.

<H3>mime.types</H3>

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

<UL><PRE>
text/html       html htm \
	printable(0,1024) + \
	(string(0,"&lt;HTML&gt;") string(0,"&lt;!DOCTYPE"))
</PRE></UL>

<P>The first two rules say that any file with an extension of
<VAR>.html</VAR> or <VAR>.htm</VAR> is a HTML file. The third rule
says that any file whose first 1024 characters are printable text and
starts with the strings <CODE>&lt;HTML&gt;</CODE> or
<CODE>&lt;!DOCTYPE</CODE> is a HTML file as well.

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

<P>The available tests are:

<UL>

<LI><CODE>( expr )</CODE> - Parenthesis for expression grouping

<LI><CODE>+</CODE> - Logical AND

<LI><CODE>,</CODE> or whitespace - Logical OR

<LI><CODE>!</CODE> - Logical NOT

<LI><CODE>match("pattern")</CODE> - Pattern match on filename

<LI><CODE>extension</CODE> - Pattern match on "*.extension"

<LI><CODE>ascii(offset,length)</CODE> - True if bytes are valid
printable ASCII (CR, NL, TAB, BS, 32-126)

<LI><CODE>printable(offset,length)</CODE> - True if bytes are
printable 8-bit chars (CR, NL, TAB, BS, 32-126, 160-254)

<LI><CODE>string(offset,"string")</CODE> - True if bytes are
identical to string

<LI><CODE>istring(offset,"string")</CODE> - True if bytes are
identical to string after reducing both strings to lowercase

<LI><CODE>contains(offset,range,"string")</CODE> - True if the
range of bytes contains the string

<LI><CODE>char(offset,value)</CODE> - True if byte is identical

<LI><CODE>short(offset,value)</CODE> - True if 16-bit integer
is identical (network or "big-endian" byte order)

<LI><CODE>int(offset,value)</CODE> - True if 32-bit integer is
identical (network or "big-endian" byte order)

<LI><CODE>locale("string")</CODE> - True if current locale
matches string

</UL>

<P>All numeric values can be in decimal (123), octal (0123), or hexadecimal
(0x123) as desired.

<!-- NEED 2.5in -->
<P>Strings can be in quotes, all by themselves, as a string
of hexadecimal values, or some combination:

<UL><PRE>
"string"
'string'
string
&lt;737472696e67&gt;
&lt;7374&gt;ring
</PRE></UL>

<P>As shown in the <CODE>text/html</CODE> example, rules can continue on
multiple lines using the backslash (\) character. A more complex example is
the <CODE>image/jpeg</CODE> rules:

<UL><PRE>
image/jpeg      jpeg jpg jpe string(0,&lt;FFD8FF&gt;) &amp;&amp;\
	(char(3,0xe0) char(3,0xe1) char(3,0xe2) char(3,0xe3)\
	 char(3,0xe4) char(3,0xe5) char(3,0xe6) char(3,0xe7)\
	 char(3,0xe8) char(3,0xe9) char(3,0xea) char(3,0xeb)\
	 char(3,0xec) char(3,0xed) char(3,0xee) char(3,0xef))
</PRE></UL>

<P>This rule states that any file with an extension of
<VAR>.jpeg</VAR>, <VAR>.jpg</VAR>, or <VAR>.jpe</VAR> is a JPEG file.
In addition, any file starting with the hexadecimal string
<CODE>&lt;FFD8FF&gt;</CODE> (JPEG Start-Of-Image) followed by a
character between and including <CODE>0xe0</CODE> and <CODE>0xef</CODE>
(JPEG APPn markers) is also a JPEG file.

<H3>mime.convs</H3>

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

<UL><PRE>
source destination cost program

text/plain application/postscript 50 texttops
application/vnd.cups-postscript application/vnd.cups-raster 50 pstoraster
image/* application/vnd.cups-postscript 50 imagetops
image/* application/vnd.cups-raster 50 imagetoraster
</PRE></UL>

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

<P>The <I>destination</I> field is a MIME type defined in the
<VAR>mime.types</VAR> file.

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

<P>The <I>program</I> field defines the filter program to run; the
special program "-" can be used to make two file types equivalent. The
program must accept the standard filter arguments and environment
variables described in the CUPS Interface Design Description and CUPS
Software Programmers Manual:

<UL><PRE>
program job user title options [filename]
</PRE></UL>

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

<!-- NEED 4in -->
<H3>Adding Filetypes and Filters</H3>

<P>Adding a new file type or filter is fairly straight-forward. Rather
than adding the new type and filter to the <VAR>mime.types</VAR> and
<VAR>mime.convs</VAR> files which are overwritten when you upgrade to a
new version of CUPS, you simple need to create new files with
<VAR>.types</VAR> and <VAR>.convs</VAR> extensions in the
<VAR>/etc/cups</VAR> directory. We recommend that you use the product
or format name, e.g.:

<UL><PRE>
myproduct.types
myproduct.convs
</PRE></UL>

<P>If you are providing a filter for a common file format or printer,
add the company or author name:

<UL><PRE>
acme-msword.types
acme-msword.convs
</PRE></UL>

<P>This will help to prevent name collisions if you install many
different file types and filters.

<P>Once you choose the names for these files, create them using your
favorite text editor as described earlier in this chapter.  Once you
have created the files, restart the <CODE>cupsd</CODE> process as
described earlier in <A HREF="#RESTARTING">"Restarting the CUPS Server"</A>.

<H3>Printer Drivers and PPD Files</H3>

<P>Most CUPS printer drivers utilize one or more printer-specific filters
and a PPD file for each printer model. Printer driver filters are registered
via the PPD file using <CODE>cupsFilter</CODE> attributes:

<UL><PRE>
*cupsFilter: "application/vnd.cups-raster 0 rastertohp"
</PRE></UL>

<P>The filter is specified using the source file type only; the destination
file type is assumed to be <CODE>printer/name</CODE> - suitable for sending
to the printer.

<H3>Writing Your Own Filter or Printer Driver</H3>

<P>CUPS supports an unlimited number of file formats and filters, and can
handle any printer. If you'd like to write a filter or printer driver for
your favorite file format or printer, consult the CUPS Software Programmers
Manual for step-by-step instructions.


<H1 ALIGN="RIGHT"><A NAME="PRINTING_OTHER">7 - Printing with Other Systems</A></H1>

<P>This chapter describes how to print from client systems that use the
LPD, Mac OS, or Windows printing protocols.

<H2>The Basics</H2>

<P>CUPS is based on the IPP protocol, so any system that supports IPP
can send jobs to and receive jobs from CUPS automatically. However, not
all systems support IPP yet. This chapter will show you how to connect
these systems to your CUPS server, either to accept jobs from your
server for printing, or to send jobs to your server.

<H2>Printing from LPD Clients</H2>

<P>CUPS supports limited functionality for LPD-based clients. With LPD you can
print files to specific printers, list the queue status, and so forth. However,
the automatic client configuration and printer options are not supported by
the LPD protocol, so you must manually configure each client for the printers
it needs to access.

<P>The <CODE>cups-lpd(8)</CODE> program provides support for LPD
clients and can be used from either the <CODE>inetd(8)</CODE> or
<CODE>xinetd(8)</CODE> programs. Add the following line to the
<VAR>/etc/inetd.conf</VAR> file to enable LPD support on your
server through the <CODE>inetd</CODE> program:

<UL><PRE>
printer stream tcp nowait lp /usr/lib/cups/daemon/cups-lpd cups-lpd
</PRE></UL>

<P>The path to the <CODE>cups-lpd</CODE> may vary depending on your
installation.

<P>Once you have added this line, send the <CODE>inetd</CODE>
process a <CODE>HUP</CODE> signal or reboot the system:

<UL><PRE>
<B>killall -HUP inetd ENTER</B> [IRIX and some versions of Linux]
<B>kill -HUP <I>pid</I> ENTER [Others]</B>
<B>reboot ENTER [For all systems if the HUP signal fails]</B>
</PRE></UL>

<P>If you are using the <CODE>xinetd</CODE> program, create a
file named <VAR>/etc/xinetd.d/printer</VAR> containing the
following lines:

<UL><PRE>
service printer
{
socket_type = stream
protocol = tcp
wait = no
user = lp
server = /usr/lib/cups/daemon/cups-lpd
}
</PRE></UL>

<P>The <CODE>xinetd</CODE> program automatically reads the new
configuration file and enables LPD printing support.

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
<TD><B>Warning:</B>

<P><CODE>cups-lpd</CODE> currently does not perform any
access control based on the settings in
<VAR>cupsd.conf</VAR> or in the <VAR>hosts.allow</VAR>
or <VAR>hosts.deny</VAR> files used by TCP wrappers.
Therefore, running <CODE>cups-lpd</CODE> on your server
will allow any computer on your network (and perhaps the
entire Internet) to print to your server.

<P>While <CODE>xinetd</CODE> has built-in access control
support, you should use the TCP wrappers package with
<CODE>inetd</CODE> to limit access to only those
computers that should be able to print through your
server.

</TD>
</TR>
</TABLE></CENTER>

<H2><A NAME="LPD">Printing to LPD Servers</A></H2>

<P>CUPS provides the <CODE>lpd</CODE> backend for printing to
LPD-based servers and printers. Use a device URI of
<CODE>lpd://server/name</CODE> to print to a printer on an LPD
server, where <CODE>server</CODE> is the hostname or IP address
of the server and <CODE>name</CODE> is the queue name.
Additional options can be specified after the remote queue name
to control how the LPD requests are sent - consult <A
HREF="#COMMON_NETWORK">Appendix B - Common Network Settings</A>
for a complete description.

<P>Microsoft Windows NT provides an LPD service under the name "TCP/IP
Printing Services". To enable LPD printing on NT, open the "Services"
control panel, select the "TCP/IP Printing Services" service, and click
on the "Start" button. Any shared printer will then be available via
the LPD protocol.


<!-- NEED 4in -->

<H2>Printing from Mac OS 10.2 and Later Clients</H2>

<P>Since Mac OS 10.2 uses CUPS as its printing system, all CUPS
printers will be available to the clients automatically.

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
<TD><B>Note:</B>

<P>Certain legacy MacOS X applications, including most Adobe
applications, produce PICT files with embedded PostScript. Since
the filter needed to convert these files to pure PostScript is
only available on MacOS X, you need to either use a MacOS X
print server or replace the MacOS X IPP backend with the
standard CUPS IPP backend. The CUPS IPP backend will detect and
locally convert these print files to PostScript prior to sending
the job to the server.
</TD>
</TR>
</TABLE></CENTER>


<!-- NEED 4in -->
<H2>Printing from Mac OS 10.1 and Earlier Clients</H2>

<P>CUPS does not provide support for Mac OS 10.1 and earlier
directly. However, there are several free and commercial
software packages that do.

<H3>Columbia Appletalk Package (CAP)</H3>

<P>Because the CAP LaserWriter server (<CODE>lwsrv(8)</CODE>) does
not support specification of PPD files, we do not recommend that you
use CAP with CUPS. However, you can run the <CODE>lpsrv</CODE> program
for limited printing with the command:

<UL><PRE>
lwsrv -n "<I>Name</I>" -p <I>printer</I> -a /usr/lib/adicts -f /usr/lib/LW+Fonts
</PRE></UL>

<P>where <CODE>Name</CODE> is the name you want to use when sharing the
printer, and <CODE>printer</CODE> is the name of the CUPS print queue.

<!-- NEED 3in -->
<H3>XINET KA/Spool</H3>

<P>To use your system as a print server for Mac OS clients,
configure each printer using a <CODE>papserver(8)</CODE> in the
<VAR>/usr/adm/appletalk/services</VAR> file, specifying the
corresponding PPD file in the <VAR>/etc/cups/ppd</VAR> directory for
each printer.  For a printer named <CODE>MyPrinter</CODE> the entry
would look like:

<UL><PRE>
/usr/etc/appletalk/papserver -I -L -P /etc/cups/ppd/MyPrinter.ppd \
"Printer Description" MyPrinter
</PRE></UL>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
<TD>
<B>NOTE:</B>

<P>Enter the text above on a single line without the backslash (\)
character.
</TD>
</TR>
</TABLE></CENTER>

<!-- NEED 3in -->
<H3>Netatalk</H3>

<P>To use your system as a print server for Mac OS clients,
configure each printer in the <VAR>papd.conf</VAR> file, specifying the
corresponding PPD file in the <VAR>/etc/cups/ppd</VAR> directory for
each printer. For a printer named <CODE>MyPrinter</CODE> the entry
would look like:

<UL><PRE>
Printer Name@Zone Name:\
:pr=|/usr/bin/lp -d MyPrinter:\
:op=daemon:\
:pd=/etc/cups/ppd/MyPrinter.ppd:
</PRE></UL>


<!-- NEED 2in -->
<H2>Printing to Mac OS 10.2 and Later Servers</H2>

<P>Since MacOS 10.2 and later use CUPS, all you need to do is
enable printer sharing to allow CUPS clients to print to a Mac
OS server. You will need to download and install ESP Ghostscript
on your server to provide PostScript printing support for
non-PostScript printers, however.


<!-- NEED 2in -->
<H2>Printing to Mac OS 10.1 and Earlier Servers</H2>

<P>CUPS currently does not provide a backend to communicate with
a Mac OS 10.1 and earlier server. However, you can write and
install a short shell script in the
<VAR>/usr/lib/cups/backend</VAR> directory that sends a print
file using the appropriate command. The following is a short
script that will run the <CODE>papif</CODE> command provided
with CAP.

<P>After copying this script to
<VAR>/usr/lib/cups/backend/cap</VAR>, specify a device URI of
<CODE>cap://server/printer</CODE> to use this backend with a
print queue.

<!-- NEED 8in -->
<UL>
<PRE>
<I>"/usr/lib/cups/backend/cap"</I>
#!/bin/sh
#
# Usage: cap job user title copies options [filename]
#

# No arguments means show available devices...

if test ${#argv} = 0; then
echo "network cap \"Unknown\" \"Mac OS Printer via CAP\""
exit 0
fi

# Collect arguments...

user=$2
copies=$4

if test ${#argv} = 5; then
# Get print file from stdin; copies have already been handled...
file=/var/tmp/$$.prn
copies=1
cat &gt; $file
else
# Print file is on command-line...
file=$6
fi

# Create a dummy cap.printers file for this printer based
# upon a device URI of "cap://server/printer"...

echo $PRINTER/$DEVICE_URI | \
awk -F/ '{print $1 "=" $5 ":LaserWriter@" $4}' &gt; /var/tmp/$$.cap

CAPPRINTERS=/var/tmp/$$.cap; export CAPPRINTERS

# Send the file to the printer, once for each copy. This assumes that you
# have properly initialized the cap.printers file...

while [ $copies -gt 0 ]; do
papif -n $user &lt; $file

copies=`expr $copies - 1`
done

# Remove any temporary files...
if test ${#argv} = 5; then
/bin/rm -f $file
fi

/bin/rm -f /var/tmp/$$.cap

exit 0
</PRE></UL>

<!-- NEED 2in -->
<H2>Printing from Windows Clients</H2>

<P>While CUPS does not provide Windows support directly, the free
SAMBA software package does. SAMBA version 2.0.6 is the first release
of SAMBA that supports CUPS. You can download SAMBA from:

<UL><PRE>
<A HREF="http://www.samba.org">http://www.samba.org</A>
</PRE></UL>

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

<UL><PRE>
printing = cups
printcap name = cups
</PRE></UL>

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

<H3>Exporting Printer Drivers</H3>

<P>You can optionally export printer drivers from your CUPS
server using the <CODE>cupsaddsmb</CODE> command and the SAMBA
2.2.0 or higher software.

<P>Before you can export the printers you must download the CUPS
drivers for Windows from the CUPS site (<A
HREF="http://www.cups.org/">http://www.cups.org/</A>) or the
current Adobe PostScript printer drivers from the Adobe web site
(<A HREF="http://www.adobe.com/">http://www.adobe.com/</A>). If
you download the Adobe drivers, use the free <CODE>unzip</CODE>
software to extract the files from the self-extracting ZIP file
containing the drivers; you will need the following files:

<UL><PRE>
ADFONTS.MFM
ADOBEPS4.DRV
ADOBEPS4.HLP
ADOBEPS5.DLL
ADOBEPSU.DLL
ADOBEPSU.HLP
DEFPRTR2.PPD
ICONLIB.DLL
PSMON.DLL
</PRE></UL>

<P>Copy these files to the <VAR>/usr/share/cups/drivers</VAR>
directory - you may need to rename some of the files so the
filenames are all UPPERCASE.

<P>Next, configure SAMBA (via the <VAR>smb.conf</VAR> file) to
support printing  through CUPS and provide a printer driver
download share, as follows:

<UL><PRE>
[global]
load printers = yes
printing = cups
printcap name = cups

[printers]
comment = All Printers
path = /var/spool/samba
browseable = no
public = yes
guest ok = yes
writable = no
printable = yes
printer admin = root

[print$]
comment = Printer Drivers
path = /etc/samba/drivers
browseable = yes
guest ok = no
read only = yes
write list = root
</PRE></UL>

<P>This configuration assumes a FHS-compliant installation of
SAMBA; adjust the [printers] and [print$] share paths
accordingly on your system as needed. That is, the directory for
your printer drivers can be anywhere on the system; just make
sure it is writable by the users specified by the <CODE>write
list</CODE> directive plus readable and executable by all users.
Also, make sure that you have SAMBA passwords defined for each
user in the  <CODE>write list</CODE> using SAMBA's
<CODE>smbpasswd(1)</CODE> command. Otherwise you will not be
able to authenticate.

<P>Finally, run the <CODE>cupsaddsmb</CODE> command to export
the printer drivers for one or more queues:

<UL><PRE>
<B>cupsaddsmb -U root printer1 ... printerN <I>ENTER</I></B>
</PRE></UL>

<P>Running <CODE>cupsaddsmb</CODE> with the <CODE>-a</CODE> option
will export all printers:

<UL><PRE>
<B>cupsaddsmb -U root -a <I>ENTER</I></B>
</PRE></UL>

<P>Notice in the above examples that the user <CODE>root</CODE>
was used  which was defined in the <CODE>write list</CODE> of
the <VAR>smb.conf</VAR> file.

<H2>Printing to Windows Servers</H2>

<P>CUPS can print to Windows servers in one of two ways. The first way uses
the LPD protocol on the CUPS system and the "TCP/IP Printing Services" on
the Windows system. You can find out more about this configuration in the
<A HREF="#LPD">LPD</A> section earlier in this chapter.

<P>The second way is through the Microsoft Server Message Block ("SMB")
protocol. Support for this protocol is provided with the free SAMBA
software package. You can download SAMBA from:

<UL><PRE>
<A HREF="http://www.samba.org">http://www.samba.org</A>
</PRE></UL>

<P>To configure CUPS for SAMBA, run the following command:

<UL><PRE>
<B>ln -s `which smbspool` /usr/lib/cups/backend/smb ENTER</B>
</PRE></UL>

<P>The <CODE>smbspool(1)</CODE> program is provided with SAMBA starting
with SAMBA 2.0.6. Once you have made the link you can configure your
printers with one of the following device URIs:

<UL><PRE>
smb://workgroup/server/sharename
smb://server/sharename
smb://user:pass@workgroup/server/sharename
smb://user:pass@server/sharename
</PRE></UL>

<P>The <CODE>workgroup</CODE> name need only be specified if your
system is using a different workgroup. The <CODE>user:pass</CODE>
strings are required when printing to Windows NT servers or to shares
with passwords enabled under Windows 95 and 98.


<H1 ALIGN="RIGHT"><A NAME="LICENSE">A - Software License Agreement</A></H1>

<EMBED SRC="../LICENSE.html">


<H1 ALIGN="RIGHT"><A NAME="COMMON_NETWORK">B - Common Network Settings</A></H1>

<P>This appendix covers many of the popular TCP/IP network interfaces
and printer servers available on the market today.

<H2>Configuring a Network Interface</H2>

<P>When you first install a network printer or print server on your
LAN, you need to set the Internet Protocol ("IP") address. On most
higher-end "workgroup" printers, you can set the address through the
printer control panel. However, in most cases you will want to assign
the addresses remotely from your workstation. This makes administration
a bit easier and avoids assigning duplicate addresses accidentally.

<P>To setup your printer or print server for remote address assignment,
you'll need the Ethernet Media Access Control ("MAC") address, also
sometimes called a node address, and the IP address you want to use for
the device. The Ethernet MAC address can often be found on the printer
test page or bottom of the print server.

<!-- NEED 3in -->
<H3>Configuring the IP Address Using ARP</H3>

<P>The easiest way to set the IP address of a network device is to use
the <CODE>arp(8)</CODE> command.  The <CODE>arp</CODE> sends an Address
Resolution Protocol ("ARP") packet to the specified Ethernet MAC address,
setting the network device's IP address:

<UL><PRE>
<B>arp -s ip-address ethernet-address ENTER</B>
<B>arp -s host.domain.com 08:00:69:00:12:34 ENTER</B>
<B>arp -s 192.0.2.2 08:00:69:00:12:34 ENTER</B>
</PRE></UL>

<H3>Configuring the IP Address Using RARP</H3>

<P>The most flexible way to remotely assign IP addresses under UNIX
is through the Reverse Address Resolution Protocol ("RARP"). RARP
allows a network device to request an IP address using its Ethernet
MAC address, and one or more RARP servers on the network will
respond with an ARP packet with the IP address the device can use.

<P>RARP should be used when you have to manage many printers or print
servers, or when you have a network device that does not remember its
IP address after a power cycle. If you just have a single printer or
print server, the <CODE>arp</CODE> command is the way to go.

<P>Some UNIX operating systems use a program called
<CODE>rarpd(8)</CODE> to manage RARP. Others, like Linux, support this
protocol in the kernel. For systems that provide the <CODE>rarpd</CODE>
program you will need to start it before RARP lookups will work:

<UL><PRE>
<B>rarpd ENTER</B>
</PRE></UL>

<P>Under IRIX you can enable this functionality by default using:

<UL><PRE>
<B>chkconfig rarpd on ENTER</B>
</PRE></UL>

<P>Both the <CODE>rarpd</CODE> program and kernel RARP support read a
list of Ethernet and IP addresses from the file <VAR>/etc/ethers</VAR>.
Each line contains the Ethernet address (colon delimited) followed by
an IP address or hostname like:

<UL><PRE>
08:00:69:00:12:34 myprinter.mydomain.com
08:00:69:00:12:34 192.0.2.2
</PRE></UL>

<P>Add a line to this file and cycle the power on the printer or print
server to set its address.

<!-- NEED 2in -->
<H3>Configuring the IP Address Using BOOTP</H3>

<P>The BOOTP protocol is used when you need to provide additional information
such as the location of a configuration file to the network interface. Using
the standard <CODE>bootpd(8)</CODE> program supplied with UNIX you simply need to
add a line to the <VAR>/etc/bootptab</VAR> file; for IRIX:

<UL><PRE>
myprinter 08:00:69:00:12:34 192.0.2.2 <VAR>myprinter.boot</VAR>
</PRE></UL>

<!-- NEED 1in -->
<P>Newer versions of <CODE>bootpd</CODE> use a different format:

<UL><PRE>
myprinter:ha=080069001234:ip=192.0.2.2:<VAR>t144=myprinter.boot</VAR>
</PRE></UL>

<P>The <VAR>myprinter.boot</VAR> file resides in the <VAR>/usr/local/boot</VAR>
directory by default. If you do not need to provide a boot file you may leave
the last part of the line blank.</P>

<!-- NEED 2in -->
<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
<TD>
<B>NOTE:</B>

<P>Some versions of UNIX do not enable the BOOTP service by
default. The <VAR>/etc/inetd.conf</VAR> usually contains a
line for the BOOTP service that can be uncommented if
needed.
</TD>
</TR>
</TABLE></CENTER>

<H2>Verifying the Printer Connection</H2>

<P>To test that the IP address has been successfully assigned and that the
printer is properly connected to your LAN, type:

<UL><PRE>
<B>ping ip-address ENTER</B>
</PRE></UL>

<P>If the connection is working properly you will see something like:

<UL><PRE>
<B>ping myprinter ENTER</B>
PING myprinter (192.0.2.2): 56 data bytes
64 bytes from 192.0.2.2: icmp_seq=0 ttl=15 time=5 ms
64 bytes from 192.0.2.2: icmp_seq=1 ttl=15 time=3 ms
64 bytes from 192.0.2.2: icmp_seq=2 ttl=15 time=3 ms
64 bytes from 192.0.2.2: icmp_seq=3 ttl=15 time=3 ms
</PRE></UL>

<P>If not, verify that the printer or print server is connected to the
LAN, it is powered on, the LAN cabling is good, and the IP address is
set correctly. You can usually see the current IP address and network
status by printing a configuration or test page on the device.

<!-- NEED 4in -->
<H2>Common Network Interface Settings</H2>

<P>Once you have set the IP address you can access the printer or print
server using the <CODE>ipp</CODE>, <CODE>lpd</CODE>, or
<CODE>socket</CODE> backends. The following is a list of common network
interfaces and printer servers and the settings you should use with
CUPS:

<CENTER><TABLE BORDER="1">
<TR VALIGN="TOP" ALIGN="LEFT">
<TH>Model/Manufacturer</TH>
<TH>Device URI(s)</TH>
</TR>
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>Apple LaserWriter</TD>
<TD>lpd://<I>address</I>/PASSTHRU</TD>
</TR>
<!-- NEED 1in -->
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>Axis w/o IPP<BR>
<A HREF="#AXIS">(see directions)</A></TD>
<TD>socket://<I>address</I>:9100<BR>
socket://<I>address</I>:9101<BR>
socket://<I>address</I>:9102</TD>
</TR>
<!-- NEED 1in -->
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>Axis w/IPP</TD>
<TD>ipp://<I>address</I>/LPT1<BR>
ipp://<I>address</I>/LPT2<BR>
ipp://<I>address</I>/COM1</TD>
</TR>
<!-- NEED 1in -->
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>Castelle LANpress<SUP>TM</SUP></TD>
<TD>lpd://<I>address</I>/pr1<BR>
lpd://<I>address</I>/pr2<BR>
lpd://<I>address</I>/pr3</TD>
</TR>
<!-- NEED 1in -->
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>DPI NETPrint</TD>
<TD>lpd://<I>address</I>/pr1<BR>
lpd://<I>address</I>/pr2<BR>
lpd://<I>address</I>/pr3</TD>
</TR>
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>EFI&reg; Fiery&reg; RIP</TD>
<TD>lpd://<I>address</I>/print</TD>
</TR>
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>EPSON&reg; Multiprotocol Ethernet Interface Board</TD>
<TD>socket://<I>address</I></TD>
</TR>
<!-- NEED 1in -->
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>Extended System ExtendNET</TD>
<TD>lpd://<I>address</I>/pr1<BR>
lpd://<I>address</I>/pr2<BR>
lpd://<I>address</I>/pr3</TD>
</TR>
<!-- NEED 1in -->
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>Hewlett Packard JetDirect w/o IPP</TD>
<TD>socket://<I>address</I>:9100<BR>
socket://<I>address</I>:9101<BR>
socket://<I>address</I>:9102</TD>
</TR>
<!-- NEED 1in -->
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>Hewlett Packard JetDirect w/IPP</TD>
<TD>ipp://<I>address</I>/ipp<BR>
ipp://<I>address</I>/ipp/port1<BR>
ipp://<I>address</I>/ipp/port2<BR>
ipp://<I>address</I>/ipp/port3</TD>
</TR>
<!-- NEED 1in -->
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>Intel® NetportExpress XL, PRO/100</TD>
<TD>lpd://<I>address</I>/LPT1_PASSTHRU<BR>
lpd://<I>address</I>/LPT2_PASSTHRU<BR>
lpd://<I>address</I>/COM1_PASSTHRU</TD>
</TR>
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>Lexmark<SUP>TM</SUP> MarkNet</TD>
<TD>lpd://<I>address</I>/ps</TD>
</TR>
<!-- NEED 1in -->
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>Linksys EtherFast&reg;<BR>
<A HREF="#LINKSYS">(see directions)</A></TD>
<TD>socket://<I>address</I>:4010<BR>
socket://<I>address</I>:4020<BR>
socket://<I>address</I>:4030</TD>
</TR>
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>Kodak&reg;</TD>
<TD>lpd://<I>address</I>/ps</TD>
</TR>
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>QMS&reg; CrownNet<SUP>TM</SUP></TD>
<TD>lpd://<I>address</I>/ps</TD>
</TR>
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>Tektronix&reg; PhaserShare<SUP>TM</SUP></TD>
<TD>socket://<I>address</I>:9100</TD>
</TR>
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>XEROX&reg; 4512 NIC</TD>
<TD>lpd://<I>address</I>/PORT1</TD>
</TR>
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>XEROX&reg; XNIC</TD>
<TD>lpd://<I>address</I>/PASSTHRU</TD>
</TR>
<TR ALIGN="LEFT" VALIGN="TOP">
<TD>XEROX&reg; (most others)</TD>
<TD>socket://<I>address</I>:5503</TD>
</TR>
</TABLE></CENTER>

<H2><A NAME="AXIS">Configuring Axis Print Servers</A></H2>

<P>The Axis print servers can be configured using ARP, RARP, or BOOTP.
However, on models that do not provide IPP support an additional step
must be performed to configure the TCP/IP portion of the print server
for use with CUPS.

<!-- NEED 3in -->
<P>Each print server contains a configuration file named
<VAR>config</VAR> that contains a list of network parameters used by
the server. To modify this file you must first download it from the
print server using the <CODE>ftp(1)</CODE> program:

<UL><PRE>
<B>ftp ip-address ENTER</B>
Connected to ip-address.
220 Axis NPS ### FTP Printer Server V#.## MON DD YEAR ready.
ftp> <B>user root ENTER</B>
331 User name ok, need password
Password: <B>pass ENTER</B> <I>(this is not echoed)</I>
230 User logged in
ftp> <B>get config ENTER</B>
local: config remote: config
200 PORT command successful.
150 Opening data connection for config (192,0,2,2),
(mode ascii).
226 Transfer complete.
##### bytes received in #.## seconds (##### Kbytes/s)
ftp> <B>quit ENTER</B>
221 Goodbye.
</PRE></UL>

<!-- NEED 2in -->
<P>Next, edit the file with your favorite text editor and locate the
lines beginning with:

<UL><PRE>
RTN_OPT.     : YES
RTEL_PR1.    : 0
RTEL_PR2.    : 0
RTEL_PR3.    : 0
RTEL_PR4.    : 0
RTEL_PR5.    : 0
RTEL_PR6.    : 0
RTEL_PR7.    : 0
RTEL_PR8.    : 0
</PRE></UL>

<!-- NEED 1in -->
Change the <CODE>RTN_OPT</CODE> line to read:

<UL><PRE>
RTN_OPT.     : <B>NO</B>
</PRE></UL>

<!-- NEED 2in -->
<P>This disables the Reverse TELNET protocol and enables the standard
TELNET protocol on the print server. Next, assign a port number for
each parallel and serial port on the server as follows:

<UL><PRE>
RTEL_PR1.    : <B>9100</B>
RTEL_PR2.    : <B>9101</B>
RTEL_PR3.    : <B>9102</B>
RTEL_PR4.    : <B>9103</B>
RTEL_PR5.    : <B>9104</B>
RTEL_PR6.    : <B>9105</B>
RTEL_PR7.    : <B>9106</B>
RTEL_PR8.    : <B>9107</B>
</PRE></UL>

<!-- NEED 4in -->
<P>This essentially makes the Axis print server look like a Hewlett
Packard JetDirect EX print server. Save the file and then upload the
new <VAR>config</VAR> file using the <CODE>ftp</CODE> command:

<UL><PRE>
<B>ftp ip-address ENTER</B>
Connected to ip-address.
220 Axis NPS ### FTP Printer Server V#.## MON DD YEAR ready.
ftp> <B>user root ENTER</B>
331 User name ok, need password
Password: <B>pass ENTER</B> <I>(this is not echoed)</I>
230 User logged in
ftp> <B>put config CONFIG ENTER</B>
local: config remote: CONFIG
200 PORT command successful.
150 Opening data connection for config (192,0,2,2), (mode ascii).
226 Transfer complete.
##### bytes received in #.## seconds (##### Kbytes/s)
ftp> <B>get hardreset ENTER</B>
local: hardreset remote: hardreset
200 PORT command successful.
421 Axis NPS ### hard reset, closing connection.
ftp> <B>quit ENTER</B>
221 Goodbye.
</PRE></UL>

<P>Your Axis print server is now ready for use!

<H2><A NAME="LINKSYS">Configuring Linksys Print Servers</A></H2>

<P>The Linksys print servers can be configured using ARP, RARP, or
BOOTP. Like older Axis print servers, an additional step must be
performed to configure the TCP/IP portion of the print server for use
with CUPS.

<!-- NEED 3in -->
<P>Each print server contains a configuration file named
<VAR>CONFIG</VAR> that contains a list of network parameters used by
the server. To modify this file you must first download it from the
print server using the <CODE>ftp(1)</CODE> program:

<UL><PRE>
<B>ftp -n ip-address ENTER</B>
Connected to ip-address.
220 Print Server Ready.
Remote system type is Print.
ftp> <B>get CONFIG ENTER</B>
local: CONFIG remote: CONFIG
200 Command OK.
150 Open ASCII Mode Connection.
WARNING! 68 bare linefeeds received in ASCII mode
File may not have transferred correctly.
226 Transfer complete.
##### bytes received in #.## seconds (##### Kbytes/s)
ftp> <B>quit ENTER</B>
221 Goodbye.
</PRE></UL>

<!-- NEED 2in -->
<P>Next, edit the file with your favorite text editor and locate the
lines beginning with:

<UL><PRE>
0100 L1_PROUT:P1
0120 L2_PROUT:P1
0140 L3_PROUT:P1
</PRE></UL>

<P>Change the port number for
each parallel and serial port on the server as follows:

<UL><PRE>
0100 L1_PROUT:<B>P1</B>
0120 L2_PROUT:<B>P2</B>
0140 L3_PROUT:<B>P3</B>
</PRE></UL>

<!-- NEED 4in -->
<P>This maps each virtual printer with a physical port. Save the file and then upload the
new <VAR>CONFIG</VAR> file using the <CODE>ftp</CODE> command:

<UL><PRE>
<B>ftp -n ip-address ENTER</B>
Connected to ip-address.
220 Print Server Ready.
Remote system type is Print.
ftp> <B>put CONFIG ENTER</B>
local: CONFIG remote: CONFIG
200 Command OK.
150 Open ASCII Mode Connection.
226 Transfer complete.
##### bytes received in #.## seconds (##### Kbytes/s)
ftp> <B>quit ENTER</B>
221 Goodbye.
</PRE></UL>

<P>Your Linksys print server is now ready for use!

<H2><A NAME="LPD_OPTIONS">Configuring LPD Printing Options</A></H2>

<P>The LPD backend supports several options which are included in the
device URI, e.g.:

<PRE>
    lpd://server/name?option1=value1+option2=value2+...+optionN=valueN
</PRE>

<P>The following table summarizes the options and values that are supported:

<!-- NEED 9in -->
<CENTER><TABLE BORDER="1" WIDTH="80%">
<TR>
	<TH>Option=Value</TH>
	<TH>Description</TH>
</TR>
<TR>
	<TD>banner=off<BR>
	banner=no<BR>
	banner=false</TD>
	<TD VALIGN="TOP">Does not request a LPD banner page for
	the job. (Default)</TD>
</TR>
<TR>
	<TD>banner=on<BR>
	banner=yes<BR>
	banner=true</TD>
	<TD VALIGN="TOP">Requests a LPD banner page for the
	job.</TD>
</TR>
<TR>
	<TD>format=c<BR>
	format=d<BR>
	format=f<BR>
	format=g<BR>
	format=l<BR>
	format=n<BR>
	format=o<BR>
	format=p<BR>
	format=r<BR>
	format=t<BR>
	format=v</TD>
	<TD VALIGN="TOP">Specifies the LPD format code of the
	print job. "format=l" is raw output, while "format=o" is PostScript.
	(Default is "format=l" for raw output)</TD>
</TR>
<TR>
	<TD>manual_copies=off<BR>
	manual_copies=no<BR>
	manual_copies=false</TD>
	<TD VALIGN="TOP">Specifies that the backend should not
	send multiple copies of a print job in the print data
	file.</TD>
</TR>
<TR>
	<TD>manual_copies=on<BR>
	manual_copies=yes<BR>
	manual_copies=true</TD>
	<TD VALIGN="TOP">Specifies that the backend should send
	multiple copies of a print job in the print data file to
	print more than one copy. (Default)</TD>
</TR>
<TR>
	<TD>order=control,data</TD>
	<TD VALIGN="TOP">Specifies that the LPD control file
	should be sent before the print data file.
	(Default)</TD>
</TR>
<TR>
	<TD>order=data,control=</TD>
	<TD VALIGN="TOP">Specifies that the print data file
	should be sent before the LPD control file.</TD>
</TR>
<TR>
	<TD>reserve=off<BR>
	reserve=no<BR>
	reserve=false</TD>
	<TD VALIGN="TOP">Specifies that the backend should not
	reserve a priviledged source port as required by RFC
	1179.</TD>
</TR>
<TR>
	<TD>reserve=on<BR>
	reserve=yes<BR>
	reserve=true<BR>
	reserve=rfc1179</TD>
	<TD VALIGN="TOP">Specifies that the backend should
	reserve a priviledges source port from 721 to 731
	inclusive as required by RFC 1179. This option may cause
	reduced printing performance when more than 11 LPD
	printers are defined on the server due to port
	contention issues.</TD>
</TR>
<TR>
	<TD>reserve=any</TD>
	<TD VALIGN="TOP">Specifies that the backend should
	reserve a priviledges source port from 1 to 1023
	inclusive. This often works with LPD implementations
	that require a priviledged source port but do not
	limit it to the range defined by RFC 1179, allowing
	for more printers to be active at the same time. (Default)</TD>
</TR>
<TR>
	<TD>sanitize_title=off<BR>
	sanitize_title=no<BR>
	sanitize_title=false</TD>
	<TD VALIGN="TOP">Specifies that the backend should not
	sanitize the job title string. (Default on OSX)</TD>
</TR>
<TR>
	<TD>sanitize_title=on<BR>
	sanitize_title=yes<BR>
	sanitize_title=true</TD>
	<TD VALIGN="TOP">Specifies that the backend should
	sanitize the job title string. (Default on all but OSX)</TD>
</TR>
<TR>
	<TD>timeout=N</TD>
	<TD VALIGN="TOP">Specifies the response timeout for all LPD
	commands and transactions in seconds. (Default is 300 seconds)</TD>
</TR>
</TABLE></CENTER>

<H1 ALIGN="RIGHT"><A NAME="PRINTER_DRIVERS">C - Printer Drivers</A></H1>

<P>This appendix lists the printer drivers that are provided with CUPS.

<H2>Printer Drivers</H2>

<P>CUPS includes the following printer drivers:

<UL>

<LI><A HREF="#DYMO">DYMO Label Printer</A>, <VAR>dymo.ppd</VAR>

<LI><A HREF="#EPSON9">EPSON 9-pin Dot Matrix</A>, <VAR>epson9.ppd</VAR>

<LI><A HREF="#EPSON24">EPSON 24-pin Dot Matrix</A>, <VAR>epson24.ppd</VAR>

<LI><A HREF="#STCOLOR">EPSON Stylus Color</A>, <VAR>stcolor.ppd</VAR>

<LI><A HREF="#STPHOTO">EPSON Stylus Photo</A>, <VAR>stphoto.ppd</VAR>

<LI><A HREF="#DESKJET">HP DeskJet</A>, <VAR>deskjet.ppd</VAR>

<LI><A HREF="#LASERJET">HP LaserJet</A>, <VAR>laserjet.ppd</VAR>

</UL>

<H2><A NAME="DYMO">DYMO Label Printer</A></H2>

<P>The DYMO Label Printer driver (<VAR>dymo.ppd</VAR>) supports
the DYMO LabelWriter 300 series (300/310/315/320/330/330 Turbo)
thermal label printers. It provides 136, 203, and 300 DPI output
in black only.

<H2><A NAME="EPSON9">EPSON 9-pin Dot Matrix</A></H2>

<P>The EPSON 9-pin Dot Matrix driver (<VAR>epson9.ppd</VAR>) supports
9-pin dot matrix printers that implement the ESC/P command set. It
provides 60x72, 120x72, and 240x72 DPI output in black only.

<H2><A NAME="EPSON24">EPSON 24-pin Dot Matrix</A></H2>

<P>The EPSON 24-pin Dot Matrix driver (<VAR>epson9.ppd</VAR>) supports
24-pin dot matrix printers that implement the ESC/P command set. It
provides 120x180, 180x180, 360x180, and 360x360 DPI output in black
only.

<H2><A NAME="STCOLOR">EPSON Stylus Color</A></H2>

<P>The EPSON Stylus Color driver (<VAR>stcolor.ppd</VAR>) supports
EPSON Stylus Color printers that implement the ESC/P2 command set. It
provides 180, 360, and 720 DPI output in black and color (CMYK).

<H2><A NAME="STPHOTO">EPSON Stylus Photo</A></H2>

<P>The EPSON Stylus Photo driver (<VAR>stphoto.ppd</VAR>) supports
EPSON Stylus Photo printers that implement the ESC/P2 command set. It
provides 180, 360, and 720 DPI output in black and color (CMYKcm).

<H2><A NAME="DESKJET">HP DeskJet</A></H2>

<P>The HP DeskJet driver (<VAR>deskjet.ppd</VAR>) supports HP DeskJet
printers that implement the PCL command set. It provides 150, 300, and
600 DPI output in black and color (CMYK).

<P>The DeskJet printers that implement the HP-PPA command set (720C,
722C, 820C, and 1100C) are <B>not</B> supported due to a complete lack
of documentation and support from Hewlett Packard.

<P>The duplexer provided with the HP DeskJet 900 series printers is also
not supported for similar reasons.

<H2><A NAME="LASERJET">HP LaserJet</A></H2>

<P>The HP LaserJet driver (<VAR>laserjet.ppd</VAR>) supports HP
LaserJet printers that implement the PCL command set. It provides 150,
300, and 600 DPI output in black only and supports the duplexer if
installed.

<P>LaserJet printers that do not implement PCL (3100, 3150) are not
supported due to a complete lack of documentation and support from
Hewlett Packard.


<H1 ALIGN="RIGHT"><A NAME="FILES">D - List of Files</A></H1>

<P>This appendix lists the files and directories that are installed for
the Common UNIX Printing System.

<CENTER><TABLE BORDER="1" WIDTH="80%">
<TR VALIGN="TOP">
<TH>Pathname</TH>
<TH>Description</TH>
</TR>
<TR VALIGN="TOP">
<TD>/etc/cups/certs/</TD>
<TD>The location of authentication certificate files for local
HTTP clients.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/etc/cups/classes.conf</TD>
<TD>The printer classes configuration file for the scheduler.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/etc/cups/cupsd.conf</TD>
<TD>The scheduler configuration file.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/etc/cups/interfaces/</TD>
<TD>The location of System V interface scripts for printers.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/etc/cups/mime.convs</TD>
<TD>The list of standard file filters included with CUPS.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/etc/cups/mime.types</TD>
<TD>The list of recognized file types for CUPS.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/etc/cups/ppd/</TD>
<TD>The location of PostScript Printer Description ("PPD") files for
printers.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/etc/cups/printers.conf</TD>
<TD>The printer configuration file for the scheduler.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/bin/cancel</TD>
<TD>The System V cancel job(s) command.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/bin/disable</TD>
<TD>The System V disable printer command.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/bin/enable</TD>
<TD>The System V enable printer command.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/bin/lp</TD>
<TD>The System V print command.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/bin/lpoptions</TD>
<TD>Sets user-defined printing options and defaults.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/bin/lppasswd</TD>
<TD>Adds, changes, or removes Digest password accounts.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/bin/lpq</TD>
<TD>The Berkeley status command.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/bin/lpr</TD>
<TD>The Berkeley print command.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/bin/lprm</TD>
<TD>The Berkeley cancel job(s) command.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/bin/lpstat</TD>
<TD>The System V status command.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/include/cups/</TD>
<TD>CUPS API header files.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/lib32/libcups.a<BR>
/usr/lib32/libcupsimage.a</TD>
<TD>Static libraries (IRIX 6.5)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/lib/libcups.a<BR>
/usr/lib/libcupsimage.a</TD>
<TD>Static libraries (all others)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/lib/libcups.sl.2<BR>
/usr/lib/libcupsimage.sl.2</TD>
<TD>Shared libraries (HP-UX)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/lib32/libcups.so.2<BR>
/usr/lib32/libcupsimage.so.2</TD>
<TD>Shared libraries (IRIX 6.5)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/lib/libcups.so.2<BR>
/usr/lib/libcupsimage.so.2</TD>
<TD>Shared libraries (all others)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/libexec/cups/backend/</TD>
<TD>Backends for various types of printer connections (*BSD and OSX)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/lib/cups/backend/</TD>
<TD>Backends for various types of printer connections (all others)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/libexec/cups/cgi-bin/</TD>
<TD>CGI programs for the scheduler (*BSD and OSX)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/lib/cups/cgi-bin/</TD>
<TD>CGI programs for the scheduler (all others)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/libexec/cups/daemon/</TD>
<TD>Daemons for polling and LPD support (*BSD and OSX)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/lib/cups/daemon/</TD>
<TD>Daemons for polling and LPD support (all others)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/libexec/cups/filter/</TD>
<TD>Filters for various types of files (*BSD and OSX)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/lib/cups/filter/</TD>
<TD>Filters for various types of files (all others)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/lib/locale/</TD>
<TD>The location of language-specific message files. (System V)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/lib/nls/msg/</TD>
<TD>The location of language-specific message files. (Compaq Tru64 UNIX)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/share/locale/</TD>
<TD>The location of language-specific message files. (Linux, *BSD)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/sbin/accept</TD>
<TD>The accept-jobs command.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/sbin/cupsd</TD>
<TD>The CUPS print scheduler.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/sbin/lpadmin</TD>
<TD>The System V printer administration tool.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/sbin/lpc</TD>
<TD>The Berkeley printer administration tool.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/sbin/lpinfo</TD>
<TD>The get-devices and get-ppds command.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/sbin/lpmove</TD>
<TD>The move-jobs command.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/sbin/reject</TD>
<TD>The reject-jobs command.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/share/catman/a_man/<BR>
/usr/share/catman/u_man/</TD>
<TD>Man pages (IRIX)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/share/man/</TD>
<TD>Man pages (Compaq Tru64 UNIX, HP-UX, Solaris)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/man/</TD>
<TD>Man pages (all others)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/share/cups/data/</TD>
<TD>The location of filter data files.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/share/cups/data/testprint.ps</TD>
<TD>The PostScript test page file.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/share/cups/fonts/</TD>
<TD>The location of PostScript fonts for the PostScript RIP.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/share/cups/model/</TD>
<TD>The location of PostScript Printer Description ("PPD") files and
interface scripts that may be used to setup a printer queue.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/share/cups/pstoraster/</TD>
<TD>Other PostScript RIP initialization files.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/share/cups/pstoraster/Fontmap</TD>
<TD>The font mapping file (converts filenames to fontnames)</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/share/cups/templates/</TD>
<TD>The location of HTML template files for the web interfaces.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/usr/share/doc/cups/</TD>
<TD>Documentation and web page data for the scheduler.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/var/log/cups/</TD>
<TD>The location of scheduler log files.</TD>
</TR>
<TR VALIGN="TOP">
<TD>/var/spool/cups/</TD>
<TD>The location of print files waiting to be printed.</TD>
</TR>
</TABLE></CENTER>


<H1 ALIGN="RIGHT"><A NAME="FAQ">E - Troubleshooting Common Problems</A></H1>

<P>This appendix covers some of the common problems first-time users
encounter when installing and configuring CUPS.

<P>Commercial support for CUPS is available from Easy Software Products.
For more information please contact us at:

<UL>

<LI>WWW: <A HREF="http://www.easysw.com/cups/">
<CODE>http://www.easysw.com/cups/</CODE></A>

<LI>EMail: <A HREF="mailto:info@easysw.com">info@easysw.com</A>

<LI>Telephone (M-F, 9-5 EST): +1.301.373.9600

</UL>

<H2>My Applications Don't See the Available Printers</H2>

<P>Many applications read the <VAR>/etc/printcap</VAR> file to
get a list of available printers.

<P>The default CUPS configuration creates the
<VAR>/etc/printcap</VAR> file automatically. To enable or
disable automatic creation and updating of this file, use the <A
HREF="#Printcap"><CODE>Printcap</CODE></A> directive described
in <A HREF="#PRINTING_MANAGEMENT">Chapter 6, "Printing System
Management"</A>.

<H2>CUPS Doesn't Recognize My Username or Password!</H2>

<P>CUPS will ask you for a UNIX username and password when you perform
printer administration tasks remotely or via a web browser. The default
configuration requires that you use the <CODE>root</CODE> username and
the corresponding password to authenticate the request.

<P>CUPS does not allow you to authenticate an administration request
with an account that has no password for security reasons. If you do
not have a password on your <CODE>root</CODE> account then you won't be
able to add printers remotely or via the web interface!

<!-- NEED 2in -->
<P>To disable password authentication you need to edit the
<VAR>/etc/cups/cupsd.conf</VAR> file and comment out the
lines reading:

<UL><PRE>
AuthType Basic
AuthClass System
</PRE></UL>

<P>for the <VAR>/admin</VAR> location. Then restart the CUPS server as
described in <A HREF="#PRINTING_MANAGEMENT">Chapter 6, "Printing System
Management"</A>.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
<TD>
<B>NOTE:</B>

<P>Disabling password checks will allow any local user to
change your printer and class configuration, but remote
administration from another machine will still not be allowed.
</TD>
</TR>
</TABLE></CENTER>

<H2><A NAME="ALLOW_REMOTE">I Can't Do Administration Tasks from Another Machine!</A></H2>

<P>The default CUPS configuration limits administration to the local
machine. To open up access, edit the <VAR>/etc/cups/cupsd.conf</VAR>
and comment out the lines reading:

<UL><PRE>
Order deny,allow
Deny from all
Allow from 127.0.0.1
</PRE></UL>

<P>for the <VAR>/admin</VAR> location. Then restart the CUPS server as
described in <A HREF="#PRINTING_MANAGEMENT">Chapter 6, "Printing System
Management"</A>.</P>

<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" BGCOLOR="#cccccc">
<TR>
<TD>
<B>NOTE:</B>

<P>Allowing administration access from all hosts is a potential
security risk. Please read <A HREF="#PRINTING_SECURITY">Chapter
6, "Printing System Management"</A> for a description of these
risks and ways to minimize them.
</TD>
</TR>
</TABLE></CENTER>

<!-- NEED 4in -->
<H2>I Can't Do Administration Tasks from My Web Browser!</H2>

<P>This problem is usually caused by:

<OL>

<LI>not specifying the correct password for the
root account.

<LI>accessing the CUPS server using the hostname or IP
address of the server without enabling remote access for
administration functions. This can be corrected by following
the instructions in the <A HREF="#ALLOW_REMOTE">"I Can't Do
Administration Tasks from Another Machine!"</A> section earlier
in this appendix.

<LI>not setting a password on the root account. CUPS will not
authenticate a user account that does not have a password for
security reasons.

<LI>authenticating using an account other than root, but the
account you are using is not a member of the system group.

<LI>configuring CUPS to use Digest authentication, but
your web browser does not support Digest authentication.

</OL>

<H2>Connection Refused Messages</H2>

<P>Under normal circumstances, "connection refused" messages for a
networked printer should be expected from time to time. Most network
interfaces only allow a single connection to be made at any given time
(one job at a time) and will refuse access to all other systems while
the first connection is active. CUPS automatically retries the
connection once every 30 seconds.

<P>If the problem persists and you are unable to print any jobs to the printer,
verify that another machine is not maintaining a connection with the printer,
and that you have selected the proper port or printer name for the printer.

<P>Also, most external print servers will refuse connections if the connected
printer is turned off or is off-line. Verify that the affected printer is
turned on and is online.

<H2>Write Error Messages</H2>

<P>If you get "write error" messages on a printer queue the printer
interface (usually a Hewlett Packard JetDirect interface) has timed out
and reset the network connection from your workstation.

<P>The error is caused by that startup delay between the initial setup
of the printer or plotter and the first page of print data that is
sent.

<!-- NEED 3in -->
<P>To correct the problem, change the idle timeout on the interface to at least
180 seconds or 3 minutes. To change the timeout on a Hewlett Packard
JetDirect interface, type:

<UL><PRE>
<B>telnet ip-address ENTER</B>

Trying ip-address...
Connected to ip-address.
Escape character is `^]'.

Please type [Return] two times, to initialize telnet configuration
For HELP type "?"
> <B>idle-timeout: 180 ENTER</B>
> <B>quit ENTER</B>
</PRE></UL>

</BODY>
</HTML>