doc/sam.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>CUPS Software Administrators Manual</TITLE>
   5 <META NAME="author" CONTENT="Easy Software Products">
   6 <META NAME="copyright" CONTENT="Copyright 1997-2002, All Rights Reserved">
   7 <META NAME="docnumber" CONTENT="CUPS-SAM-1.1.18">
   8 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-8859-1">
   9 <STYLE TYPE="text/css"><!--
  10 BODY { font-family: serif }
  11 H1 { font-family: sans-serif }
  12 H2 { font-family: sans-serif }
  13 H3 { font-family: sans-serif }
  14 H4 { font-family: sans-serif }
  15 H5 { font-family: sans-serif }
  16 H6 { font-family: sans-serif }
  17 SUB { font-size: smaller }
  18 SUP { font-size: smaller }
  19 PRE { font-family: monospace }
  20 --></STYLE>
  21 </HEAD>
  22 <BODY BGCOLOR="white">
  23 <CENTER><A HREF="#CONTENTS"><IMG SRC="images/cups-large.gif" BORDER="0" WIDTH="431" HEIGHT="511"><BR>
  24 <H1>CUPS Software Administrators Manual</H1></A><BR>
  25 CUPS-SAM-1.1.18<BR>
  26 Easy Software Products<BR>
  27 Copyright 1997-2002, All Rights Reserved<BR>
  28 </CENTER>
  29 <HR>
  30 <H1 ALIGN="CENTER"><A NAME="CONTENTS">Table of Contents</A></H1>
  31 <BR>
  32 <BR><B><A HREF="#1">Preface</A></B>
  33 <UL>
  34 <LI><A HREF="#1_1">System Overview</A></LI>
  35 <LI><A HREF="#1_2">Document Overview</A></LI>
  36 <LI><A HREF="#1_3">Notation Conventions</A></LI>
  37 <LI><A HREF="#1_4">Abbreviations</A></LI>
  38 <LI><A HREF="#1_5">Other References</A></LI>
  39 </UL>
  40 <B><A HREF="#OVERVIEW">1 - Printing System Overview</A></B>
  41 <UL>
  42 <LI><A HREF="#2_1">The Printing Problem</A></LI>
  43 <LI><A HREF="#2_2">The Technology</A></LI>
  44 <LI><A HREF="#2_3">Jobs</A></LI>
  45 <LI><A HREF="#2_4">Classes</A></LI>
  46 <LI><A HREF="#2_5">Filters</A></LI>
  47 <LI><A HREF="#2_6">Backends</A></LI>
  48 <LI><A HREF="#2_7">Printer Drivers</A></LI>
  49 <LI><A HREF="#2_8">Networking</A></LI>
  50 </UL>
  51 <B><A HREF="#BUILDING_INSTALLING">2 - Building and Installing CUPS</A></B>
  52 <UL>
  53 <LI><A HREF="#3_1">Installing a Source Distribution</A></LI>
  54 <UL>
  55 <LI><A HREF="#REQUIREMENTS">Requirements</A></LI>
  56 <LI><A HREF="#COMPILING">Compiling CUPS</A></LI>
  57 <LI><A HREF="#INSTALLING">Installing the Software</A></LI>
  58 <LI><A HREF="#RUNNING">Running the Software</A></LI>
  59 </UL>
  60 <LI><A HREF="#BINARY">Installing a Binary Distribution</A></LI>
  61 <UL>
  62 <LI><A HREF="#PORTABLE-BINARY">Installing a Portable Distribution</A></LI>
  63 <LI><A HREF="#RPM-BINARY">Installing an RPM Distribution</A></LI>
  64 <LI><A HREF="#DPKG-BINARY">Installing an Debian Distribution</A></LI>
  65 </UL>
  66 </UL>
  67 <B><A HREF="#MANAGING_PRINTERS">3 - Managing Printers</A></B>
  68 <UL>
  69 <LI><A HREF="#4_1">The Basics</A></LI>
  70 <LI><A HREF="#4_2">Adding Your First Printer</A></LI>
  71 <UL>
  72 <LI><A HREF="#4_2_1">Adding Your First Printer from the Command-Line</A></LI>
  73 <LI><A HREF="#ADD_WEB">Adding Your First Printer from the Web</A></LI>
  74 </UL>
  75 <LI><A HREF="#4_3">Managing Printers from the Command-Line</A></LI>
  76 <UL>
  77 <LI><A HREF="#4_3_1">Adding and Modifying Printers</A></LI>
  78 <LI><A HREF="#4_3_2">Deleting Printers</A></LI>
  79 <LI><A HREF="#4_3_3">Setting the Default Printer</A></LI>
  80 <LI><A HREF="#4_3_4">Starting and Stopping Printers</A></LI>
  81 <LI><A HREF="#4_3_5">Accepting and Rejecting Print Jobs</A></LI>
  82 <LI><A HREF="#4_3_6">Setting Quotas on a Printer</A></LI>
  83 <LI><A HREF="#4_3_7">Restricting User Access to a Printer</A></LI>
  84 </UL>
  85 <LI><A HREF="#4_4">Managing Printers from the Web</A></LI>
  86 </UL>
  87 <B><A HREF="#PRINTER_CLASSES">4 - Printer Classes</A></B>
  88 <UL>
  89 <LI><A HREF="#5_1">The Basics</A></LI>
  90 <LI><A HREF="#5_2">Managing Printer Classes from the Command-Line</A></LI>
  91 <LI><A HREF="#5_3">Managing Printer Classes from the Web Interface</A></LI>
  92 <LI><A HREF="#5_4">Implicit Classes</A></LI>
  93 </UL>
  94 <B><A HREF="#CLIENT_SETUP">5 - Client Setup</A></B>
  95 <UL>
  96 <LI><A HREF="#6_1">The Basics</A></LI>
  97 <UL>
  98 <LI><A HREF="#CLIENT_MANUAL">Manual Configuration of Print Queues</A></LI>
  99 <LI><A HREF="#CLIENT_SERVER">Specifying a Single Server for Printing</A></LI>
 100 <LI><A HREF="#CLIENT_AUTO">Automatic Configuration of Print Queues</A></LI>
 101 <LI><A HREF="#CLIENT_POLL">Specifying Multiple Servers for Printing</A></LI>
 102 <LI><A HREF="#CLIENT_RELAY">Relaying Printers to Other Clients</A></LI>
 103 </UL>
 104 <LI><A HREF="#6_2">Load Balancing and Failsafe Operation</A></LI>
 105 </UL>
 106 <B><A HREF="#PRINTING_MANAGEMENT">6 - Printing System Management</A></B>
 107 <UL>
 108 <LI><A HREF="#7_1">The Basics</A></LI>
 109 <LI><A HREF="#RESTARTING">Restarting the CUPS Server</A></LI>
 110 <LI><A HREF="#7_3">Changing the Server Configuration</A></LI>
 111 <LI><A HREF="#7_4">Server Directives</A></LI>
 112 <UL>
 113 <LI><A HREF="#AccessLog">AccessLog</A></LI>
 114 <LI><A HREF="#Allow">Allow</A></LI>
 115 <LI><A HREF="#AuthClass">AuthClass</A></LI>
 116 <LI><A HREF="#AuthGroupName">AuthGroupName</A></LI>
 117 <LI><A HREF="#AuthType">AuthType</A></LI>
 118 <LI><A HREF="#AutoPurgeJobs">AutoPurgeJobs</A></LI>
 119 <LI><A HREF="#BrowseAddress">BrowseAddress</A></LI>
 120 <LI><A HREF="#BrowseAllow">BrowseAllow</A></LI>
 121 <LI><A HREF="#BrowseDeny">BrowseDeny</A></LI>
 122 <LI><A HREF="#BrowseOrder">BrowseOrder</A></LI>
 123 <LI><A HREF="#BrowseInterval">BrowseInterval</A></LI>
 124 <LI><A HREF="#BrowsePoll">BrowsePoll</A></LI>
 125 <LI><A HREF="#BrowsePort">BrowsePort</A></LI>
 126 <LI><A HREF="#BrowseProtocols">BrowseProtocols</A></LI>
 127 <LI><A HREF="#BrowseRelay">BrowseRelay</A></LI>
 128 <LI><A HREF="#BrowseShortNames">BrowseShortNames</A></LI>
 129 <LI><A HREF="#BrowseTimeout">BrowseTimeout</A></LI>
 130 <LI><A HREF="#Browsing">Browsing</A></LI>
 131 <LI><A HREF="#Classification">Classification</A></LI>
 132 <LI><A HREF="#ClassifyOverride">ClassifyOverride</A></LI>
 133 <LI><A HREF="#ConfigFilePerm">ConfigFilePerm</A></LI>
 134 <LI><A HREF="#DataDir">DataDir</A></LI>
 135 <LI><A HREF="#DefaultCharset">DefaultCharset</A></LI>
 136 <LI><A HREF="#DefaultLanguage">DefaultLanguage</A></LI>
 137 <LI><A HREF="#Deny">Deny</A></LI>
 138 <LI><A HREF="#DocumentRoot">DocumentRoot</A></LI>
 139 <LI><A HREF="#Encryption">Encryption</A></LI>
 140 <LI><A HREF="#ErrorLog">ErrorLog</A></LI>
 141 <LI><A HREF="#FilterLimit">FilterLimit</A></LI>
 142 <LI><A HREF="#FilterNice">FilterNice</A></LI>
 143 <LI><A HREF="#FontPath">FontPath</A></LI>
 144 <LI><A HREF="#Group">Group</A></LI>
 145 <LI><A HREF="#HideImplicitMembers">HideImplicitMembers</A></LI>
 146 <LI><A HREF="#HostNameLookups">HostNameLookups</A></LI>
 147 <LI><A HREF="#ImplicitClasses">ImplicitClasses</A></LI>
 148 <LI><A HREF="#ImplicitAnyClasses">ImplicitAnyClasses</A></LI>
 149 <LI><A HREF="#Include">Include</A></LI>
 150 <LI><A HREF="#KeepAlive">KeepAlive</A></LI>
 151 <LI><A HREF="#KeepAliveTimeout">KeepAliveTimeout</A></LI>
 152 <LI><A HREF="#Limit">Limit</A></LI>
 153 <LI><A HREF="#LimitExcept">LimitExcept</A></LI>
 154 <LI><A HREF="#LimitRequestBody">LimitRequestBody</A></LI>
 155 <LI><A HREF="#Listen">Listen</A></LI>
 156 <LI><A HREF="#Location">Location</A></LI>
 157 <LI><A HREF="#LogFilePerm">LogFilePerm</A></LI>
 158 <LI><A HREF="#LogLevel">LogLevel</A></LI>
 159 <LI><A HREF="#MaxClients">MaxClients</A></LI>
 160 <LI><A HREF="#MaxClientsPerHost">MaxClientsPerHost</A></LI>
 161 <LI><A HREF="#MaxCopies">MaxCopies</A></LI>
 162 <LI><A HREF="#MaxJobs">MaxJobs</A></LI>
 163 <LI><A HREF="#MaxJobsPerPrinter">MaxJobsPerPrinter</A></LI>
 164 <LI><A HREF="#MaxJobsPerUser">MaxJobsPerUser</A></LI>
 165 <LI><A HREF="#MaxLogSize">MaxLogSize</A></LI>
 166 <LI><A HREF="#MaxRequestSize">MaxRequestSize</A></LI>
 167 <LI><A HREF="#Order">Order</A></LI>
 168 <LI><A HREF="#PageLog">PageLog</A></LI>
 169 <LI><A HREF="#Port">Port</A></LI>
 170 <LI><A HREF="#PreserveJobHistory">PreserveJobHistory</A></LI>
 171 <LI><A HREF="#PreserveJobFiles">PreserveJobFiles</A></LI>
 172 <LI><A HREF="#Printcap">Printcap</A></LI>
 173 <LI><A HREF="#PrintcapFormat">PrintcapFormat</A></LI>
 174 <LI><A HREF="#PrintcapGUI">PrintcapGUI</A></LI>
 175 <LI><A HREF="#RemoteRoot">RemoteRoot</A></LI>
 176 <LI><A HREF="#RequestRoot">RequestRoot</A></LI>
 177 <LI><A HREF="#Require">Require</A></LI>
 178 <LI><A HREF="#RIPCache">RIPCache</A></LI>
 179 <LI><A HREF="#RootCertDuration">RootCertDuration</A></LI>
 180 <LI><A HREF="#RunAsUser">RunAsUser</A></LI>
 181 <LI><A HREF="#Satisfy">Satisfy</A></LI>
 182 <LI><A HREF="#ServerAdmin">ServerAdmin</A></LI>
 183 <LI><A HREF="#ServerBin">ServerBin</A></LI>
 184 <LI><A HREF="#ServerCertificate">ServerCertificate</A></LI>
 185 <LI><A HREF="#ServerKey">ServerKey</A></LI>
 186 <LI><A HREF="#ServerName">ServerName</A></LI>
 187 <LI><A HREF="#ServerRoot">ServerRoot</A></LI>
 188 <LI><A HREF="#SSLListen">SSLListen</A></LI>
 189 <LI><A HREF="#SSLPort">SSLPort</A></LI>
 190 <LI><A HREF="#SystemGroup">SystemGroup</A></LI>
 191 <LI><A HREF="#TempDir">TempDir</A></LI>
 192 <LI><A HREF="#Timeout">Timeout</A></LI>
 193 <LI><A HREF="#User">User</A></LI>
 194 </UL>
 195 <LI><A HREF="#7_5">Changing the Client Configuration</A></LI>
 196 <LI><A HREF="#7_6">Client Directives</A></LI>
 197 <UL>
 198 <LI><A HREF="#Encryption">Encryption</A></LI>
 199 <LI><A HREF="#ServerName">ServerName</A></LI>
 200 </UL>
 201 <LI><A HREF="#7_7">Changing the Printer Configuration</A></LI>
 202 <LI><A HREF="#7_8">Printer Directives</A></LI>
 203 <UL>
 204 <LI><A HREF="#Accepting">Accepting</A></LI>
 205 <LI><A HREF="#AllowUser">AllowUser</A></LI>
 206 <LI><A HREF="#DefaultPrinter">DefaultPrinter</A></LI>
 207 <LI><A HREF="#DenyUser">DenyUser</A></LI>
 208 <LI><A HREF="#DeviceURI">DeviceURI</A></LI>
 209 <LI><A HREF="#Info">Info</A></LI>
 210 <LI><A HREF="#JobSheets">JobSheets</A></LI>
 211 <LI><A HREF="#KLimit">KLimit</A></LI>
 212 <LI><A HREF="#PrinterLocation">Location</A></LI>
 213 <LI><A HREF="#PageLimit">PageLimit</A></LI>
 214 <LI><A HREF="#Printer">Printer</A></LI>
 215 <LI><A HREF="#QuotaPeriod">QuotaPeriod</A></LI>
 216 <LI><A HREF="#State">State</A></LI>
 217 <LI><A HREF="#StateMessage">StateMessage</A></LI>
 218 </UL>
 219 <LI><A HREF="#7_9">Changing the Classes Configuration</A></LI>
 220 <LI><A HREF="#7_10">Classes Directives</A></LI>
 221 <UL>
 222 <LI><A HREF="#ClassAccepting">Accepting</A></LI>
 223 <LI><A HREF="#ClassAllowUser">AllowUser</A></LI>
 224 <LI><A HREF="#Class">Class</A></LI>
 225 <LI><A HREF="#DefaultClass">DefaultClass</A></LI>
 226 <LI><A HREF="#ClassDenyUser">DenyUser</A></LI>
 227 <LI><A HREF="#ClassInfo">Info</A></LI>
 228 <LI><A HREF="#ClassJobSheets">JobSheets</A></LI>
 229 <LI><A HREF="#ClassKLimit">KLimit</A></LI>
 230 <LI><A HREF="#ClassLocation">Location</A></LI>
 231 <LI><A HREF="#ClassPageLimit">PageLimit</A></LI>
 232 <LI><A HREF="#ClassPrinter">Printer</A></LI>
 233 <LI><A HREF="#ClassQuotaPeriod">QuotaPeriod</A></LI>
 234 <LI><A HREF="#ClassState">State</A></LI>
 235 <LI><A HREF="#ClassStateMessage">StateMessage</A></LI>
 236 </UL>
 237 <LI><A HREF="#PRINTING_SECURITY">Printing System Security</A></LI>
 238 <UL>
 239 <LI><A HREF="#CERTIFICATES">Authentication Using Certificates</A></LI>
 240 <LI><A HREF="#7_11_2">Using Basic Authentication</A></LI>
 241 <LI><A HREF="#7_11_3">Using Digest Authentication</A></LI>
 242 <LI><A HREF="#7_11_4">System and Group Authentication</A></LI>
 243 </UL>
 244 <LI><A HREF="#PRINTER_ACCOUNTING">Printer Accounting</A></LI>
 245 <UL>
 246 <LI><A HREF="#7_12_1">The access_log File</A></LI>
 247 <LI><A HREF="#7_12_2">The error_log File</A></LI>
 248 <LI><A HREF="#7_12_3">The page_log File</A></LI>
 249 </UL>
 250 <LI><A HREF="#FILE_TYPING_FILTERING">File Typing and Filtering</A></LI>
 251 <UL>
 252 <LI><A HREF="#7_13_1">mime.types</A></LI>
 253 <LI><A HREF="#7_13_2">mime.convs</A></LI>
 254 <LI><A HREF="#7_13_3">Adding Filetypes and Filters</A></LI>
 255 <LI><A HREF="#7_13_4">Printer Drivers and PPD Files</A></LI>
 256 <LI><A HREF="#7_13_5">Writing Your Own Filter or Printer Driver</A></LI>
 257 </UL>
 258 </UL>
 259 <B><A HREF="#PRINTING_OTHER">7 - Printing with Other Systems</A></B>
 260 <UL>
 261 <LI><A HREF="#8_1">The Basics</A></LI>
 262 <LI><A HREF="#8_2">Printing from LPD Clients</A></LI>
 263 <LI><A HREF="#8_3">Printing to LPD Servers</A></LI>
 264 <LI><A HREF="#8_4">Printing from Mac OS Clients</A></LI>
 265 <UL>
 266 <LI><A HREF="#8_4_1">Columbia Appletalk Package (CAP)</A></LI>
 267 <LI><A HREF="#8_4_2">XINET KA/Spool</A></LI>
 268 <LI><A HREF="#8_4_3">NetATalk</A></LI>
 269 </UL>
 270 <LI><A HREF="#8_5">Printing to Mac OS Servers</A></LI>
 271 <LI><A HREF="#8_6">Printing from Windows Clients</A></LI>
 272 <UL>
 273 <LI><A HREF="#8_6_1">Exporting Printer Drivers</A></LI>
 274 </UL>
 275 <LI><A HREF="#8_7">Printing to Windows Servers</A></LI>
 276 </UL>
 277 <B><A HREF="#LICENSE">A - Software License Agreement</A></B>
 278 <UL>
 279 <LI><A HREF="#9_1">Common UNIX Printing System License Agreement</A></LI>
 280 <UL>
 281 <LI><A HREF="#9_1_1">Introduction</A></LI>
 282 <LI><A HREF="#9_1_2">License Exceptions</A></LI>
 283 <LI><A HREF="#9_1_3">Trademarks</A></LI>
 284 <LI><A HREF="#9_1_4">Binary Distribution Rights</A></LI>
 285 <LI><A HREF="#9_1_5">Support</A></LI>
 286 </UL>
 287 <LI><A HREF="#9_2">GNU GENERAL PUBLIC LICENSE</A></LI>
 288 <LI><A HREF="#9_3">GNU LIBRARY GENERAL PUBLIC LICENSE</A></LI>
 289 </UL>
 290 <B><A HREF="#COMMON_NETWORK">B - Common Network Settings</A></B>
 291 <UL>
 292 <LI><A HREF="#10_1">Configuring a Network Interface</A></LI>
 293 <UL>
 294 <LI><A HREF="#10_1_1">Configuring the IP Address Using ARP</A></LI>
 295 <LI><A HREF="#10_1_2">Configuring the IP Address Using RARP</A></LI>
 296 <LI><A HREF="#10_1_3">Configuring the IP Address Using BOOTP</A></LI>
 297 </UL>
 298 <LI><A HREF="#10_2">Verifying the Printer Connection</A></LI>
 299 <LI><A HREF="#10_3">Common Network Interface Settings</A></LI>
 300 <LI><A HREF="#AXIS">Configuring Axis Print Servers</A></LI>
 301 <LI><A HREF="#LINKSYS">Configuring Linksys Print Servers</A></LI>
 302 </UL>
 303 <B><A HREF="#PRINTER_DRIVERS">C - Printer Drivers</A></B>
 304 <UL>
 305 <LI><A HREF="#11_1">Printer Drivers</A></LI>
 306 <LI><A HREF="#EPSON9">EPSON 9-pin Dot Matrix</A></LI>
 307 <LI><A HREF="#EPSON24">EPSON 24-pin Dot Matrix</A></LI>
 308 <LI><A HREF="#STCOLOR">EPSON Stylus Color</A></LI>
 309 <LI><A HREF="#STPHOTO">EPSON Stylus Photo</A></LI>
 310 <LI><A HREF="#DESKJET">HP DeskJet</A></LI>
 311 <LI><A HREF="#LASERJET">HP LaserJet</A></LI>
 312 </UL>
 313 <B><A HREF="#FILES">D - List of Files</A></B>
 314 <BR>
 315 <BR><B><A HREF="#FAQ">E - Troubleshooting Common Problems</A></B>
 316 <UL>
 317 <LI><A HREF="#13_1">My Applications Don't See the Available Printers</A></LI>
 318 <LI><A HREF="#13_2">CUPS Doesn't Recognize My Username or Password!</A></LI>
 319 <LI><A HREF="#ALLOW_REMOTE">I Can't Do Administration Tasks from Another
 320  Machine!</A></LI>
 321 <LI><A HREF="#13_4">I Can't Do Administration Tasks from My Web Browser!</A>
 322 </LI>
 323 <LI><A HREF="#13_5">Connection Refused Messages</A></LI>
 324 <LI><A HREF="#13_6">Write Error Messages</A></LI>
 325 </UL>
 326 <HR>
 327 <H1 ALIGN="RIGHT"><A NAME="1">Preface</A></H1>
 328 <P>This software administrators manual provides printer administration
 329  information for the Common UNIX Printing System<SUP>TM</SUP> (&quot;CUPS<SUP>
 330 TM</SUP>&quot;), version 1.1.18.</P>
 331 <H2><A NAME="1_1">System Overview</A></H2>
 332 <P>CUPS provides a portable printing layer for UNIX&reg;-based operating
 333  systems. It has been developed by<A HREF="http://www.easysw.com"> Easy
 334  Software Products</A> to promote a standard printing solution for all
 335  UNIX vendors and users. CUPS provides the System V and Berkeley
 336  command-line interfaces.</P>
 337 <P>CUPS uses the Internet Printing Protocol (&quot;IPP&quot;) as the basis for
 338  managing print jobs and queues. The Line Printer Daemon (&quot;LPD&quot;) Server
 339  Message Block (&quot;SMB&quot;), and AppSocket (a.k.a. JetDirect) protocols are
 340  also supported with reduced functionality. CUPS adds network printer
 341  browsing and PostScript Printer Description (&quot;PPD&quot;) based printing
 342  options to support real-world printing under UNIX.</P>
 343 <P>CUPS also includes a customized version of GNU Ghostscript (currently
 344  based off GNU Ghostscript 5.50) and an image file RIP that are used to
 345  support non-PostScript printers. Sample drivers for HP and EPSON
 346  printers are included that use these filters.</P>
 347
 348 <!-- NEED 3in -->
 349 <H2><A NAME="1_2">Document Overview</A></H2>
 350 <P>This software administrators manual is organized into the following
 351  sections:</P>
 352 <UL>
 353 <LI><A HREF="#OVERVIEW">1 - Printing System Overview</A></LI>
 354 <LI><A HREF="#BUILDING_INSTALLING">2 - Building and Installing CUPS</A></LI>
 355 <LI><A HREF="#MANAGING_PRINTERS">3 - Managing Printers</A></LI>
 356 <LI><A HREF="#PRINTER_CLASSES">4 - Printer Classes</A></LI>
 357 <LI><A HREF="#CLIENT_SETUP">5 - Client Setup</A></LI>
 358 <LI><A HREF="#PRINTING_MANAGEMENT">6 - Printing System Management</A></LI>
 359 <LI><A HREF="#PRINTING_OTHER">7 - Printing with Other Systems</A></LI>
 360 <LI><A HREF="#LICENSE">A - Software License Agreement</A></LI>
 361 <LI><A HREF="#COMMON_NETWORK">B - Common Network Settings</A></LI>
 362 <LI><A HREF="#PRINTER_DRIVERS">C - Printer Drivers</A></LI>
 363 <LI><A HREF="#FILES">D - List of Files</A></LI>
 364 <LI><A HREF="#FAQ">E - Troubleshooting Common Problems</A></LI>
 365 </UL>
 366 <H2><A NAME="1_3">Notation Conventions</A></H2>
 367 <P>Various font and syntax conventions are used in this guide. Examples
 368  and their meanings and uses are explained below:
 369 <CENTER>
 370 <TABLE WIDTH="80%">
 371 <TR><TH>Example</TH><TD>&nbsp;&nbsp;&nbsp;</TD><TH>Description</TH></TR>
 372 <TR><TD>&nbsp;</TD></TR>
 373 <TR VALIGN="TOP"><TD><CODE>lpstat</CODE>
 374 <BR> <CODE>lpstat(1)</CODE></TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>The names of commands;
 375  the first mention of a command or function in a chapter is followed by
 376  a manual page section number.</TD></TR>
 377 <TR><TD>&nbsp;</TD></TR>
 378 <TR VALIGN="TOP"><TD><VAR>/var</VAR>
 379 <BR><VAR> /usr/share/cups/data/testprint.ps</VAR></TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>
 380 File and directory names.</TD></TR>
 381 <TR><TD>&nbsp;</TD></TR>
 382 <TR VALIGN="TOP"><TD NOWRAP><TT>Request ID is Printer-123</TT></TD><TD>
 383 &nbsp;&nbsp;&nbsp;</TD><TD>Screen output.</TD></TR>
 384 <TR><TD>&nbsp;</TD></TR>
 385 <TR VALIGN="TOP"><TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD><TD>
 386 &nbsp;&nbsp;&nbsp;</TD><TD>Literal user input; special keys like <KBD>ENTER</KBD> are
 387  in ALL CAPS.</TD></TR>
 388 <TR><TD>&nbsp;</TD></TR>
 389 <TR VALIGN="TOP"><TD>12.3</TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>Numbers in the text are
 390  written using the period (.) to indicate the decimal point.</TD></TR>
 391 </TABLE>
 392 </CENTER>
 393
 394 <!-- NEED 3in -->
 395 </P>
 396 <H2><A NAME="1_4">Abbreviations</A></H2>
 397  The following abbreviations are used throughout this manual:
 398 <UL>
 399 <DL>
 400 <DT>kb</DT>
 401 <DD>Kilobytes, or 1024 bytes
 402 <BR>&nbsp;</DD>
 403 <DT>Mb</DT>
 404 <DD>Megabytes, or 1048576 bytes
 405 <BR>&nbsp;</DD>
 406 <DT>Gb</DT>
 407 <DD>Gigabytes, or 1073741824 bytes
 408 <BR>&nbsp;</DD>
 409 </DL>
 410 </UL>
 411 <H2><A NAME="1_5">Other References</A></H2>
 412 <UL>
 413 <DL>
 414 <DT>CUPS Software Programmers Manual</DT>
 415 <DD>A programmer guide for interfacing with and/or extending the CUPS
 416  software.
 417 <BR>&nbsp;</DD>
 418 <DT>CUPS Software Users Manual</DT>
 419 <DD>An end-user guide for using the CUPS software.
 420 <BR>&nbsp;</DD>
 421 </DL>
 422 </UL>
 423 <H1 ALIGN="RIGHT"><A NAME="OVERVIEW">1 - Printing System Overview</A></H1>
 424 <P>This chapter provides an overview of how the Common UNIX Printing
 425  System works.</P>
 426 <H2><A NAME="2_1">The Printing Problem</A></H2>
 427 <P>For years<I> the printing problem</I> has plagued UNIX. Unlike
 428  Microsoft&reg; Windows&reg; or Mac OS, UNIX has no standard interface or system
 429  in place for supporting printers. Among the solutions currently
 430  available, the Berkeley and System V printing systems are the most
 431  prevalent.</P>
 432 <P>These printing systems support line printers (text only) or
 433  PostScript printers (text and graphics), and with some coaxing they can
 434  be made to support a full range of printers and file formats. However,
 435  because each varient of the UNIX operating system uses a different
 436  printing system than the next developing printer drivers for a wide
 437  range of printers and operating systems is extremely difficult. That
 438  combined with the limited volume of customers for each UNIX varient has
 439  forced most printer vendors to give up supporting UNIX entirely.</P>
 440 <P>CUPS is designed to eliminate<I> the printing problem</I>. One common
 441  printing system can be used by all UNIX varients to support the
 442  printing needs of users. Printer vendors can use its modular filter
 443  interface to develop a single driver program that supports a wide range
 444  of file formats with little or no effort. Since CUPS provides both the
 445  System V and Berkeley printing commands, users (and applications) can
 446  reap the benefits of this new technology with no changes.</P>
 447 <H2><A NAME="2_2">The Technology</A></H2>
 448 <P>CUPS is based upon an emerging Internet standard called the Internet
 449  Printing Protocol. IPP has been embraced by dozens of printer and
 450  printer server manufacturers and is supported by Microsoft Windows
 451  2000.</P>
 452 <P>IPP defines a standard protocol for printing as well as managing
 453  print jobs and printer options like media size, resolution, and so
 454  forth. Like all IP-based protocols, IPP can be used locally or over the
 455  Internet to printers hundreds or thousands of miles away. Unlike other
 456  protocols, however, IPP also supports access control, authentication,
 457  and encryption, making it a much more capable and secure printing
 458  solution than older ones.</P>
 459 <P>IPP is layered on top of the Hyper-Text Transport Protocol (&quot;HTTP&quot;)
 460  which is the basis of web servers on the Internet. This allows users to
 461  view documentation, check status information on a printer or server,
 462  and manage their printers, classes, and jobs using their web browser.</P>
 463 <P>CUPS provides a complete IPP/1.1 based printing system that provides
 464  Basic, Digest, and local certificate authentication and user, domain,
 465  or IP-based access control. TLS encryption will be available in future
 466  versions of CUPS.</P>
 467 <H2><A NAME="2_3">Jobs</A></H2>
 468 <P>Each file or set of files that is submitted for printing is called a<I>
 469  job</I>. Jobs are identified by a unique number starting at 1 and are
 470  assigned to a particular destination, usually a printer. Jobs can also
 471  have options associated with them such as media size, number of copies,
 472  and priority.</P>
 473 <H2><A NAME="2_4">Classes</A></H2>
 474 <P>CUPS supports collections of printers known as<I> classes</I>. Jobs
 475  sent to a class are forwarded to the first available printer in the
 476  class.</P>
 477 <H2><A NAME="2_5">Filters</A></H2>
 478 <P>Filters allow a user or application to print many types of files
 479  without extra effort. Print jobs sent to a CUPS server are filtered
 480  before sending them to a printer. Some filters convert job files to
 481  different formats that the printer can understand. Others perform page
 482  selection and ordering tasks.</P>
 483 <P>CUPS provides filters for printing many types of image files, HP-GL/2
 484  files, PDF files, and text files. CUPS also supplies PostScript and
 485  image file Raster Image Processor (&quot;RIP&quot;) filters that convert
 486  PostScript or image files into bitmaps that can be sent to a raster
 487  printer.</P>
 488 <H2><A NAME="2_6">Backends</A></H2>
 489 <P>Backends perform the most important task of all - they send the
 490  filtered print data to the printer.</P>
 491 <P>CUPS provides backends for printing over parallel, serial, and USB
 492  ports, and over the network via the IPP, JetDirect (AppSocket), and
 493  Line Printer Daemon (&quot;LPD&quot;) protocols. Additional backends are
 494  available in network service packages such as the SMB backend included
 495  with the popular SAMBA software.</P>
 496 <P>Backends are also used to determine the available devices. On startup
 497  each backend is asked for a list of devices it supports, and any
 498  information that is available. This allows the parallel backend to tell
 499  CUPS that an EPSON Stylus Color 600 printer is attached to parallel
 500  port 1, for example.</P>
 501 <H2><A NAME="2_7">Printer Drivers</A></H2>
 502 <P>Printer drivers in CUPS consist of one of more filters specific to a
 503  printer. CUPS includes sample printer drivers for Hewlett-Packard
 504  LaserJet and DeskJet printers and EPSON 9-pin, 24-pin, Stylus Color,
 505  and Stylus Photo printers. While these drivers do not generate optimal
 506  output for the different printer models, they do provide basic printing
 507  and demonstrate how you can write your own printer drivers and
 508  incorporate them into CUPS.</P>
 509 <H2><A NAME="2_8">Networking</A></H2>
 510 <P>Printers and classes on the local system are automatically shared
 511  with other systems on the network. This allows you to setup one system
 512  to print to a printer and use this system as a printer server or spool
 513  host for all of the others. Users may then select a local printer by
 514  name or a remote printer using &quot;name@server&quot;.</P>
 515 <P>CUPS also provides<I> implicit classes</I>, which are collections of
 516  printers and/or classes with the same name. This allows you to setup
 517  multiple servers pointing to the same physical network printer, for
 518  example, so that you aren't relying on a single system for printing.
 519  Because this also works with printer classes, you can setup multiple
 520  servers and printers and never worry about a single point of failure
 521  unless all of the printers and servers go down!</P>
 522 <H1 ALIGN="RIGHT"><A NAME="BUILDING_INSTALLING">2 - Building and
 523  Installing CUPS</A></H1>
 524 <P>This chapter shows how to build and install the Common UNIX Printing
 525  System. If you are installing a binary distribution from the CUPS web
 526  site, proceed to the section titled,<A HREF="#BINARY"> Installing a
 527  Binary Distribution</A>.</P>
 528 <H2><A NAME="3_1">Installing a Source Distribution</A></H2>
 529 <P>This section describes how to compile and install CUPS on your system
 530  from the source code.</P>
 531 <H3><A NAME="REQUIREMENTS">Requirements</A></H3>
 532 <P>You'll need ANSI-compliant C and C++ compilers to build CUPS on your
 533  system. As its name implies, CUPS is designed to run on the UNIX
 534  operating system, however the CUPS interface library and most of the
 535  filters and backends supplied with CUPS should also compile and run
 536  under Microsoft Windows.</P>
 537 <P>For the image file filters and PostScript RIP, you'll need the JPEG,
 538  PNG, TIFF, and ZLIB libraries. CUPS will build without these, but with
 539  significantly reduced functionality. Easy Software Products maintains a
 540  mirror of the current versions of these libraries at:</P>
 541 <UL>
 542 <PRE>
 543 <A HREF="ftp://ftp.easysw.com/pub/libraries">ftp://ftp.easysw.com/pub/libraries</A>
 544 </PRE>
 545 </UL>
 546 <P>If you make changes to the man pages you'll need GNU groff or another
 547  nroff-like package. GNU groff is available from:</P>
 548 <UL>
 549 <PRE>
 550 <A HREF="ftp://ftp.gnu.org/pub/groff">ftp://ftp.gnu.org/pub/groff</A>
 551 </PRE>
 552 </UL>
 553 <P>The documentation is formatted using the HTMLDOC software. If you
 554  need to make changes you can get the HTMLDOC software from:</P>
 555 <UL>
 556 <PRE>
 557 <A HREF="http://www.easysw.com/htmldoc">http://www.easysw.com/htmldoc</A>
 558 </PRE>
 559 </UL>
 560 <P>Finally, you'll need a <CODE>make</CODE> program that understands the
 561  <CODE>include</CODE> directive - FreeBSD, NetBSD, and OpenBSD
 562  developers should use the <CODE>gmake</CODE> program.</P>
 563 <H3><A NAME="COMPILING">Compiling CUPS</A></H3>
 564 <P>CUPS uses GNU autoconf to configure the makefiles and source code for
 565  your system. Type the following command to configure CUPS for your
 566  system:</P>
 567 <UL>
 568 <PRE>
 569 <B>./configure ENTER</B>
 570 </PRE>
 571 </UL>
 572 <P>The default installation will put the CUPS software in the<VAR> /etc</VAR>
 573 ,<VAR> /usr</VAR>, and<VAR> /var</VAR> directories on your system, which
 574  will overwrite any existing printing commands on your system. Use the <CODE>
 575 --prefix</CODE> option to install the CUPS software in another location:</P>
 576 <UL>
 577 <PRE>
 578 <B>./configure --prefix=/some/directory ENTER</B>
 579 </PRE>
 580 </UL>
 581 <P>If the PNG, JPEG, TIFF, and ZLIB libraries are not installed in a
 582  system default location (typically<VAR> /usr/include</VAR> and<VAR>
 583  /usr/lib</VAR>) you'll need to set the <CODE>CFLAGS</CODE>, <CODE>
 584 CXXFLAGS</CODE>, and <CODE>LDFLAGS</CODE> environment variables prior to
 585  running configure:</P>
 586 <UL>
 587 <PRE>
 588 <B>setenv CFLAGS &quot;-I/some/directory&quot; ENTER</B>
 589 <B>setenv CXXFLAGS &quot;-I/some/directory&quot; ENTER</B>
 590 <B>setenv LDFLAGS &quot;-L/some/directory&quot; ENTER</B>
 591 <B>setenv DSOFLAGS &quot;-L/some/directory&quot; ENTER</B>
 592 <B>./configure ... ENTER</B>
 593 </PRE>
 594 </UL>
 595 <P>or:</P>
 596 <UL>
 597 <PRE>
 598 <B>CFLAGS=&quot;-I/some/directory&quot;; export CFLAGS ENTER</B>
 599 <B>CXXFLAGS=&quot;-I/some/directory&quot;; export CXXFLAGS ENTER</B>
 600 <B>LDFLAGS=&quot;-L/some/directory&quot;; export LDFLAGS ENTER</B>
 601 <B>DSOFLAGS=&quot;-L/some/directory&quot;; export DSOFLAGS ENTER</B>
 602 <B>./configure ... ENTER</B>
 603 </PRE>
 604 </UL>
 605 <P>To enable support for encryption, you'll also want to add the
 606  &quot;--enable-ssl&quot; option:</P>
 607 <UL>
 608 <PRE>
 609 ./configure --enable-ssl
 610 </PRE>
 611 </UL>
 612 <P>SSL and TLS support require the OpenSSL library, available at:</P>
 613 <UL>
 614 <PRE>
 615 <A HREF="http://www.openssl.org">http://www.openssl.org</A>
 616 </PRE>
 617 </UL>
 618 <P>If the OpenSSL headers and libraries are not installed in the
 619  standard directories, use the <CODE>--with-openssl-includes</CODE> and <CODE>
 620 --with-openssl-libs</CODE> options:</P>
 621 <UL>
 622 <PRE>
 623 ./configure --enable-ssl \
 624     --with-openssl-includes=/foo/bar/include \
 625     --with-openssl-libs=/foo/bar/lib
 626 </PRE>
 627 </UL>
 628 <P>Once you have configured things, just type:</P>
 629 <UL>
 630 <PRE>
 631 <B>make ENTER</B>
 632 </PRE>
 633 </UL>
 634 <P>to build the software.
 635 <!-- NEED 4in -->
 636 </P>
 637 <H3><A NAME="INSTALLING">Installing the Software</A></H3>
 638 <P>Use the &quot;install&quot; target to install the software:</P>
 639 <UL>
 640 <PRE>
 641 <B>make install ENTER</B>
 642 </PRE>
 643 </UL>
 644 <CENTER>
 645 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
 646 <TR><TD><B> WARNING:</B>
 647 <P>Installing CUPS will overwrite your existing printing system. If you
 648  experience difficulties with the CUPS software and need to go back to
 649  your old printing system, you will need to reinstall the old printing
 650  system from your operating system CDs.</P>
 651 </TD></TR>
 652 </TABLE>
 653 </CENTER>
 654 <H3><A NAME="RUNNING">Running the Software</A></H3>
 655 <P>Once you have installed the software you can start the CUPS server by
 656  typing:</P>
 657 <UL>
 658 <PRE>
 659 <B>/usr/sbin/cupsd ENTER</B>
 660 </PRE>
 661 </UL>
 662
 663 <!-- NEED 4in -->
 664 <H2><A NAME="BINARY">Installing a Binary Distribution</A></H2>
 665 <P>CUPS comes in a variety of binary distribution formats. Easy Software
 666  Products provides binaries in TAR format with installation and removal
 667  scripts (&quot;portable&quot; distributions), and in RPM and DPKG formats for Red
 668  Hat and Debian-based distributions. Portable distributions are
 669  available for all platforms, while the RPM and DPKG distributions are
 670  only available for Linux.
 671 <CENTER>
 672 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
 673 <TR><TD><B> WARNING:</B>
 674 <P>Installing CUPS will overwrite your existing printing system. If you
 675  experience difficulties with the CUPS software and need to go back to
 676  your old printing system, you will need to remove the CUPS software
 677  with the provided script and/or reinstall the old printing system from
 678  your operating system CDs.</P>
 679 </TD></TR>
 680 </TABLE>
 681 </CENTER>
 682 </P>
 683 <H3><A NAME="PORTABLE-BINARY">Installing a Portable Distribution</A></H3>
 684 <P>To install the CUPS software from a portable distribution you will
 685  need to be logged in as root; doing an <CODE>su</CODE> is good enough.
 686  Once you are the root user, run the installation script with:</P>
 687 <UL>
 688 <PRE>
 689 <B>./cups.install ENTER</B>
 690 </PRE>
 691 </UL>
 692 <P>After asking you a few yes/no questions the CUPS software will be
 693  installed and the scheduler will be started automatically.
 694 <!-- NEED 2in -->
 695 </P>
 696 <H3><A NAME="RPM-BINARY">Installing an RPM Distribution</A></H3>
 697 <P>To install the CUPS software from an RPM distribution you will need
 698  to be logged in as root; doing an <CODE>su</CODE> is good enough. Once
 699  you are the root user, run RPM with:</P>
 700 <UL>
 701 <PRE>
 702 <B>rpm -e lpr</B>
 703 <B>rpm -i cups-1.1-linux-M.m.n-intel.rpm ENTER</B>
 704 </PRE>
 705 </UL>
 706 <P>After a short delay the CUPS software will be installed and the
 707  scheduler will be started automatically.</P>
 708 <H3><A NAME="DPKG-BINARY">Installing an Debian Distribution</A></H3>
 709 <P>To install the CUPS software from a Debian distribution you will need
 710  to be logged in as root; doing an <CODE>su</CODE> is good enough. Once
 711  you are the root user, run dpkg with:</P>
 712 <UL>
 713 <PRE>
 714 <B>dpkg -i cups-1.1-linux-M.m.n-intel.deb ENTER</B>
 715 </PRE>
 716 </UL>
 717 <P>After a short delay the CUPS software will be installed and the
 718  scheduler will be started automatically.</P>
 719 <H1 ALIGN="RIGHT"><A NAME="MANAGING_PRINTERS">3 - Managing Printers</A></H1>
 720 <P>This chapter describes how to add your first printer and how to
 721  manage your printers.</P>
 722 <H2><A NAME="4_1">The Basics</A></H2>
 723 <P>Each printer queue has a name associated with it; the printer name
 724  must start with any printable character except &quot; &quot;, &quot;/&quot;, and &quot;@&quot;. It
 725  can contain up to 127 letters, numbers, and the underscore (_). Case is
 726  not significant, e.g. &quot;PRINTER&quot;, &quot;Printer&quot;, and &quot;printer&quot; are
 727  considered to be the same name.</P>
 728 <P>Printer queues also have a device associated with them. The device
 729  can be a parallel port, a network interface, and so forth. Devices
 730  within CUPS use Uniform Resource Identifiers (&quot;URIs&quot;) which are a more
 731  general form of Uniform Resource Locators (&quot;URLs&quot;) that are used in
 732  your web browser. For example, the first parallel port in Linux usually
 733  uses a device URI of <CODE>parallel:/dev/lp1</CODE>.
 734 <!-- NEED 2.5in -->
 735 </P>
 736 <P>You can see a complete list of supported devices by running the <CODE>
 737 lpinfo(8)</CODE> command:</P>
 738 <UL>
 739 <PRE>
 740 <B>lpinfo -v ENTER</B>
 741 network socket
 742 network http
 743 network ipp
 744 network lpd
 745 direct parallel:/dev/lp1
 746 serial serial:/dev/ttyS1?baud=115200
 747 serial serial:/dev/ttyS2?baud=115200
 748 direct usb:/dev/usb/lp0
 749 network smb
 750 </PRE>
 751 </UL>
 752 <P>The <CODE>-v</CODE> option specifies that you want a list of
 753  available devices. The first word in each line is the type of device
 754  (direct, file, network, or serial) and is followed by the device URI or
 755  method name for that device. File devices have device URIs of the form <CODE>
 756 file:/directory/filename</CODE> while network devices use the more
 757  familiar <CODE>method://server</CODE> or <CODE>method://server/path</CODE>
 758  format.</P>
 759 <P>Finally, printer queues usually have a PostScript Printer Description
 760  (&quot;PPD&quot;) file associated with them. PPD files describe the capabilities
 761  of each printer, the page sizes supported, etc., and are used for
 762  PostScript and non-PostScript printers. CUPS includes PPD files for HP
 763  LaserJet, HP DeskJet, EPSON 9-pin, EPSON 24-pin, and EPSON Stylus
 764  printers.</P>
 765 <H2><A NAME="4_2">Adding Your First Printer</A></H2>
 766 <P>CUPS provides two methods for adding printers: a command-line program
 767  called <CODE>lpadmin(8)</CODE> and a Web interface. The <CODE>lpadmin</CODE>
 768  command allows you to perform most printer administration tasks from
 769  the command-line and is located in<VAR> /usr/sbin</VAR>. The Web
 770  interface is located at:</P>
 771 <UL>
 772 <PRE>
 773 <A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
 774 </PRE>
 775 </UL>
 776 <P>and steps you through printer configuration. If you don't like
 777  command-line interfaces, try the<A HREF="#ADD_WEB"> Web interface</A>
 778  instead.</P>
 779 <H3><A NAME="4_2_1">Adding Your First Printer from the Command-Line</A></H3>
 780 <P>Run the <CODE>lpadmin</CODE> command with the <CODE>-p</CODE> option
 781  to add a printer to CUPS:</P>
 782 <UL>
 783 <PRE>
 784 <B>/usr/sbin/lpadmin -p <I>printer</I> -E -v <I>device</I> -m <I>ppd</I> ENTER</B>
 785 </PRE>
 786 </UL>
 787 <P>For a HP DeskJet printer connected to the parallel port this would
 788  look like:</P>
 789 <UL>
 790 <PRE>
 791 <B>/usr/sbin/lpadmin -p DeskJet -E -v parallel:/dev/lp1 -m deskjet.ppd ENTER</B>
 792 </PRE>
 793 </UL>
 794 <P>Similarly, a HP LaserJet printer using a JetDirect network interface
 795  at IP address 11.22.33.44 would be added with the command:</P>
 796 <UL>
 797 <PRE>
 798 <B>/usr/sbin/lpadmin -p LaserJet -E -v socket://11.22.33.44 -m laserjet.ppd ENTER</B>
 799 </PRE>
 800 </UL>
 801 <P>As you can see, <CODE>deskjet.ppd</CODE> and <CODE>laserjet.ppd</CODE>
 802  are the PPD files for the HP DeskJet and HP LaserJet drivers included
 803  with CUPS. You'll find a complete list of PPD files and the printers
 804  they will work with in<A HREF="#PRINTER_DRIVERS"> Appendix C, &quot;Printer
 805  Drivers&quot;</A>.</P>
 806 <P>For a dot matrix printer connected to the serial port this would
 807  might look like:</P>
 808 <UL>
 809 <PRE>
 810 <B>/usr/sbin/lpadmin -p DotMatrix -E -v serial:/dev/ttyS0?baud=9600+size=8+parity=none+flow=soft deskjet.ppd ENTER</B>
 811 </PRE>
 812 </UL>
 813 <P>Here you specify the serial port (e.g. S0,S1, d0, d1), baud rate
 814  (e.g. 9600, 19200, 38400, 115200, etc.), number of bits, parity, and
 815  flow control. If you do not need flow control, delete the &quot;+flow=soft&quot;
 816  portion.</P>
 817 <H3><A NAME="ADD_WEB">Adding Your First Printer from the Web</A></H3>
 818 <P>The CUPS web server provides a user-friendly &quot;wizard&quot; interface for
 819  adding your printers. Rather than figuring out which device URI and PPD
 820  file to use, you can instead click on the appropriate listings and fill
 821  in some simple information. Enter the following URL in your web browser
 822  to begin:</P>
 823 <UL>
 824 <PRE>
 825 <A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
 826 </PRE>
 827 </UL>
 828 <P>Click on the<VAR> Add Printer</VAR> button to add a printer.</P>
 829 <H2><A NAME="4_3">Managing Printers from the Command-Line</A></H2>
 830 <P>The <CODE>lpadmin</CODE> command enables you to perform most printer
 831  administration tasks from the command-line. You'll find <CODE>lpadmin</CODE>
 832  in the<VAR> /usr/sbin</VAR> directory.</P>
 833 <H3><A NAME="4_3_1">Adding and Modifying Printers</A></H3>
 834 <P>Run the <CODE>lpadmin</CODE> command with the <CODE>-p</CODE> option
 835  to add or modify a printer:</P>
 836 <UL>
 837 <PRE>
 838 <B>/usr/sbin/lpadmin -p <I>printer</I> <I>options</I> ENTER</B>
 839 </PRE>
 840 </UL>
 841 <P>The<I> options</I> arguments can be any of the following:</P>
 842 <UL>
 843 <DL>
 844 <DT>-c<I> class</I></DT>
 845 <DD>Adds the named printer to printer class<VAR> class</VAR>. If the
 846  class does not exist then it is created.</DD>
 847 <DT>-i<I> interface</I></DT>
 848 <DD>Copies the named<VAR> interface</VAR> script to the printer.
 849  Interface scripts are used by System V printer drivers. Since all
 850  filtering is disabled when using an interface script, scripts generally
 851  should not be used unless there is no other driver for a printer.</DD>
 852 <DT>-m<I> model</I></DT>
 853 <DD>Specifies a standard printer driver which is usually a PPD file.
 854  PPD's are usually stored under the<VAR> /usr/share/cups/model/</VAR>
 855  directory structure. A list of all available models can be displayed
 856  using the <CODE>lpinfo</CODE> command with the <CODE>-m</CODE> option.
 857  A list of printer drivers included with CUPS can be found in<A HREF="#PRINTER_DRIVERS">
 858  Appendix C, &quot;Printer Drivers&quot;</A>.</DD>
 859 <DT>-r<I> class</I></DT>
 860 <DD>Removes the named printer from printer class<VAR> class</VAR>. If
 861  the resulting class becomes empty then it is removed.</DD>
 862 <DT>-v<I> device-uri</I></DT>
 863 <DD>Sets the device for communicating with the printer. If a job is
 864  currently printing on the named printer then the job will be restarted
 865  and sent to the new device.</DD>
 866 <DT>-D<I> info</I></DT>
 867 <DD>Provides a textual description of the printer, e.g. &quot;John's Personal
 868  Printer&quot;.</DD>
 869 <DT>-E</DT>
 870 <DD>Enables the printer and accepts job. This option is equivalent to
 871  running the <CODE>enable(1)</CODE> and <CODE>accept(8)</CODE> commands
 872  on the printer.</DD>
 873 <DT>-L<I> location</I></DT>
 874 <DD>Provides a textual location for the printer, e.g. &quot;Computer Lab 5&quot;.</DD>
 875 <DT>-P<I> ppd-file</I></DT>
 876 <DD>Specifies a local PPD file for the printer driver.</DD>
 877 </DL>
 878 </UL>
 879 <H3><A NAME="4_3_2">Deleting Printers</A></H3>
 880 <P>Run the <CODE>lpadmin</CODE> command with the <CODE>-x</CODE> option
 881  to delete a printer:</P>
 882 <UL>
 883 <PRE>
 884 <B>/usr/sbin/lpadmin -x <I>printer</I> ENTER</B>
 885 </PRE>
 886 </UL>
 887 <H3><A NAME="4_3_3">Setting the Default Printer</A></H3>
 888 <P>Run the <CODE>lpadmin</CODE> command with the <CODE>-d</CODE> option
 889  to set a default printer:</P>
 890 <UL>
 891 <PRE>
 892 <B>/usr/sbin/lpadmin -d <I>printer</I> ENTER</B>
 893 </PRE>
 894 </UL>
 895 <P>The default printer can be overridden by the user using the <CODE>
 896 lpoptions(1)</CODE> command.</P>
 897 <H3><A NAME="4_3_4">Starting and Stopping Printers</A></H3>
 898 <P>The <CODE>enable</CODE> and <CODE>disable</CODE> commands start and
 899  stop printer queues, respectively:</P>
 900 <UL>
 901 <PRE>
 902 <B>/usr/bin/enable <I>printer</I> ENTER</B>
 903 <B>/usr/bin/disable <I>printer</I> ENTER</B>
 904 </PRE>
 905 </UL>
 906 <P>Printers that are disabled may still accept jobs for printing, but
 907  won't actually print any files until they are restarted. This is useful
 908  if the printer malfunctions and you need time to correct the problem.
 909  Any queued jobs are printed after the printer is enabled (started).</P>
 910 <H3><A NAME="4_3_5">Accepting and Rejecting Print Jobs</A></H3>
 911 <P>The <CODE>accept</CODE> and <CODE>reject</CODE> commands accept and
 912  reject print jobs for the named printer, respectively:</P>
 913 <UL>
 914 <PRE>
 915 <B>/usr/sbin/accept <I>printer</I> ENTER</B>
 916 <B>/usr/sbin/reject <I>printer</I> ENTER</B>
 917 </PRE>
 918 </UL>
 919 <P>As noted above, a printer can be stopped but accepting new print
 920  jobs. A printer can also be rejecting new print jobs while it finishes
 921  those that have been queued. This is useful for when you must perform
 922  maintenance on the printer and will not have it available to users for
 923  a long period of time.</P>
 924 <H3><A NAME="4_3_6">Setting Quotas on a Printer</A></H3>
 925 <P>CUPS supports page and size-based quotas for each printer. The quotas
 926  are tracked individually for each user, but a single set of limits
 927  applies to all users for a partiuclar printer. For example, you can
 928  limit every user to 5 pages per day on an expensive printer, but you
 929  cannot limit every user except Johnny.</P>
 930 <P>The<I> job-k-limit</I>,<I> job-page-limit</I>, and<I> job-quota-peiod</I>
 931  options determine whether and how quotas are enforced for a printer.
 932  The<I> job-quota-period</I> option determines the time interval for
 933  quota tracking. The interval is expressed in seconds, so a day is
 934  86,400, a week is 604,800 and a month is 2,592,000 seconds. The<I>
 935  job-k-limit</I> option specifies the job size limit in killobytes. The<I>
 936  job-page-limit</I> option specifies the number of pages limit.</P>
 937 <P>For quotas to be enforced, the period and at least one of the limits
 938  must be set to a non-zero value. The following options will enable
 939  quotas:</P>
 940 <UL>
 941 <PRE>
 942 <B>/usr/sbin/lpadmin -p <I>printer</I> -o job-quota-period=604800 -o job-k-limit=1024 <I>ENTER</I></B>
 943 <B>/usr/sbin/lpadmin -p <I>printer</I> -o job-quota-period=604800 -o job-page-limit=100 <I>ENTER</I></B>
 944 </PRE>
 945 </UL>
 946 <P>Or, you can combine all three options on the same line.</P>
 947 <H3><A NAME="4_3_7">Restricting User Access to a Printer</A></H3>
 948 <P>The <CODE>-u</CODE> option of the <CODE>lpadmin</CODE> command
 949  controls which users can print to a printer. The default configuration
 950  allows all users to print to a printer:</P>
 951 <UL>
 952 <PRE>
 953 <B>/usr/sbin/lpadmin -p <I>printer</I> -u allow:all <I>ENTER</I></B>
 954 </PRE>
 955 </UL>
 956 <P>CUPS supports allow and deny lists so that you can specify a list of
 957  users who are allowed to print or not allowed to print. Along with your
 958  list of users, you can specify whether they are allowed or not allowed
 959  to use the printer:</P>
 960 <UL>
 961 <PRE>
 962 <B>/usr/sbin/lpadmin -p <I>printer</I> -u allow:peter,paul,mary <I>ENTER</I></B>
 963 </PRE>
 964 </UL>
 965 <P>This command allows peter, paul, and mary to print to the named
 966  printer, but all other users cannot print. The command:</P>
 967 <UL>
 968 <PRE>
 969 <B>/usr/sbin/lpadmin -p <I>printer</I> -u deny:peter,paul,mary <I>ENTER</I></B>
 970 </PRE>
 971 </UL>
 972 <P>has the opposite effect. All users except peter, paul, and mary will
 973  be able to print to the named printer.</P>
 974 <CENTER>
 975 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
 976 <TR><TD><B>NOTE:</B>
 977 <P>The<I> allow</I> and<I> deny</I> options are not cummulative. That
 978  is, you must provide the complete list of users to allow or deny each
 979  time.</P>
 980 <P>Also, CUPS only maintains one list of users - the list can allow or
 981  deny users from printing. If you specify an allow list and then specify
 982  a deny list, the deny list will replace the allow list - only one list
 983  is active at any time.</P>
 984 </TD></TR>
 985 </TABLE>
 986 </CENTER>
 987 <H2><A NAME="4_4">Managing Printers from the Web</A></H2>
 988 <P>The Web interface is located at:</P>
 989 <UL>
 990 <PRE>
 991 <A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
 992 </PRE>
 993 </UL>
 994 <P>From there you can perform all printer management tasks with a few
 995  simple mouse clicks.</P>
 996 <H1 ALIGN="RIGHT"><A NAME="PRINTER_CLASSES">4 - Printer Classes</A></H1>
 997 <P>This chapter describes what printer classes are and how to manage
 998  them.</P>
 999 <H2><A NAME="5_1">The Basics</A></H2>
1000 <P>CUPS provides collections of printers called<I> printer classes</I>.
1001  Jobs sent to a class are forwarded to the first available printer in
1002  the class. Classes can themselves be members of other classes, so it is
1003  possible for you to define very large, distributed printer classes for
1004  high-availability printing.</P>
1005 <P>CUPS also supports<I> implicit classes</I>. Implicit classes work
1006  just like printer classes, but they are created automatically based
1007  upon the available printers and classes on the network. This allows you
1008  to setup multiple print servers with identical printer configurations
1009  and have the client machines send their print jobs to the first
1010  available server. If one or more servers go down, the jobs are
1011  automatically redirected to the servers that are running, providing
1012  fail-safe printing.</P>
1013 <H2><A NAME="5_2">Managing Printer Classes from the Command-Line</A></H2>
1014 <P>Run the <CODE>lpadmin</CODE> command with the <CODE>-p</CODE> and <CODE>
1015 -c</CODE> options to add a printer to a class:</P>
1016 <UL>
1017 <PRE>
1018 <B>/usr/sbin/lpadmin -p <I>printer</I> -c <I>class</I> ENTER</B>
1019 </PRE>
1020 </UL>
1021 <P>The<I> class</I> is created automatically if it doesn't exist. To
1022  remove a printer from a class use the <CODE>-r</CODE> option:</P>
1023 <UL>
1024 <PRE>
1025 <B>/usr/sbin/lpadmin -p <I>printer</I> -r <I>class</I> ENTER</B>
1026 </PRE>
1027 </UL>
1028 <P>To remove the entire class just use the <CODE>-x</CODE> option:</P>
1029 <UL>
1030 <PRE>
1031 <B>/usr/sbin/lpadmin -x <I>class</I> ENTER</B>
1032 </PRE>
1033 </UL>
1034 <H2><A NAME="5_3">Managing Printer Classes from the Web Interface</A></H2>
1035 <P>The Web interface is located at:</P>
1036 <UL>
1037 <PRE>
1038 <A HREF="http://localhost:631/admin">http://localhost:631/admin</A>
1039 </PRE>
1040 </UL>
1041 <P>The<VAR> Add Class</VAR> and<VAR> Modify Class</VAR> interfaces
1042  provide a list of available printers; click on the printers of interest
1043  to add them to the class.</P>
1044 <H2><A NAME="5_4">Implicit Classes</A></H2>
1045 <P>A noted earlier, implicit classes are created automatically from the
1046  available network printers and classes. To disable this functionality,
1047  set the<A HREF="#ImplicitClasses"> <CODE>ImplicitClasses</CODE></A>
1048  directive to <CODE>Off</CODE> in the <CODE>cupsd.conf</CODE> file. You
1049  will find more information on doing this in<A HREF="#PRINTING_MANAGEMENT">
1050  Chapter 6, &quot;Printing System Management&quot;</A>.</P>
1051 <H1 ALIGN="RIGHT"><A NAME="CLIENT_SETUP">5 - Client Setup</A></H1>
1052 <P>This chapter discusses several ways to configure CUPS clients for
1053  printing.</P>
1054 <H2><A NAME="6_1">The Basics</A></H2>
1055 <P>A client is any machine that sends print jobs to another machine for
1056  final printing. Clients can also be servers if they communicate
1057  directly with any printers of their own.</P>
1058 <P>CUPS supports several methods of configuring client machines:</P>
1059 <UL>
1060 <LI><A HREF="#CLIENT_MANUAL">Manual configuration of print queues.</A></LI>
1061 <LI><A HREF="#CLIENT_SERVER">Specifying a single server for printing.</A>
1062 </LI>
1063 <LI><A HREF="#CLIENT_AUTO">Automatic configuration of print queues.</A></LI>
1064 <LI><A HREF="#CLIENT_POLL">Specifying multiple servers for printing.</A></LI>
1065 <LI><A HREF="#CLIENT_RELAY">Relaying printers to other clients.</A></LI>
1066 </UL>
1067 <H3><A NAME="CLIENT_MANUAL">Manual Configuration of Print Queues</A></H3>
1068 <P>The most tedious method of configuring client machines is to
1069  configure each remote queue by hand using the <CODE>lpadmin</CODE>
1070  command:</P>
1071 <UL>
1072 <PRE>
1073 <B>lpadmin -p <I>printer</I> -E -v ipp://<I>server</I>/printers/<I>printer</I> ENTER</B>
1074 </PRE>
1075 </UL>
1076 <P>The <CODE>printer</CODE> name is the name of the printer on the
1077  server machine. The <CODE>server</CODE> name is the hostname or IP
1078  address of the server machine. Repeat the <CODE>lpadmin</CODE> command
1079  for each remote printer you wish to use.</P>
1080 <CENTER>
1081 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
1082 <TR><TD><B> NOTE:</B>
1083 <P>Manual configuration of print queues is not recommended for large
1084  numbers of client machines because of the administration nightmare it
1085  creates. For busy networks, consider subnetting groups of clients and
1086  polling and relaying printer information instead.</P>
1087 </TD></TR>
1088 </TABLE>
1089 </CENTER>
1090 <H3><A NAME="CLIENT_SERVER">Specifying a Single Server for Printing</A></H3>
1091 <P>CUPS can be configured to run without a local spooler and send all
1092  jobs to a single server. However, if that server goes down then all
1093  printing will be disabled. Use this configuration only as absolutely
1094  needed.</P>
1095 <P>The default server is normally &quot;localhost&quot;. To override the default
1096  server create a file named<VAR> /etc/cups/client.conf</VAR> and add a
1097  line reading:</P>
1098 <UL>
1099 <PRE>
1100 ServerName <I>server</I>
1101 </PRE>
1102 </UL>
1103 <P>to the file. The<VAR> server</VAR> name can be the hostname or IP
1104  address of the default server.</P>
1105 <P>The default server can also be customized on a per-user basis. To set
1106  a user-specific server create a file named<VAR> ~/.cupsrc</VAR> and add
1107  a line reading:</P>
1108 <UL>
1109 <PRE>
1110 ServerName <I>server</I>
1111 </PRE>
1112 </UL>
1113 <P>to the file. The<VAR> server</VAR> name can be the hostname or IP
1114  address of the default server.</P>
1115 <H3><A NAME="CLIENT_AUTO">Automatic Configuration of Print Queues</A></H3>
1116 <P>CUPS supports automatic client configuration of printers on the same
1117  subnet. To configure printers on the same subnet,<I> do nothing</I>.
1118  Each client should see the available printers within 30 seconds
1119  automatically. The printer and class lists are updated automatically as
1120  printers and servers are added or removed.</P>
1121 <P>If you want to see printers on other subnets as well, use the<A HREF="#BrowsePoll">
1122  <CODE>BrowsePoll</CODE></A> directive as described next.</P>
1123 <CENTER>
1124 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
1125 <TR><TD><B> NOTE:</B>
1126 <P>The<A HREF="#BrowseAddress"> <CODE>BrowseAddress</CODE></A> directive
1127  enables broadcast traffic from your server. The default configuration
1128  braodcasts printer information every 30 seconds. Although this printer
1129  information does not use much bandwidth, typically about 80 bytes per
1130  printer, it can add up with large numbers of servers and printers.</P>
1131 <P>Use the<A HREF="#BrowseInterval"> <CODE>BrowseInterval</CODE></A> and<A
1132 HREF="#BrowseTimeout"> <CODE>BrowseTimeout</CODE></A> directives to tune
1133  the amount of data that is added to your network load. In addition,
1134  subnets can be used to minimize the amount of traffic that is carried
1135  by the &quot;backbone&quot; of your large network.</P>
1136 </TD></TR>
1137 </TABLE>
1138 </CENTER>
1139 <H3><A NAME="CLIENT_POLL">Specifying Multiple Servers for Printing</A></H3>
1140 <P>If you have CUPS servers on different subnets, then you should
1141  configure CUPS to poll those servers. Polling provides the benefits of
1142  automatic configuration without significant configuration on the
1143  clients, and multiple clients on the same subnet can share the same
1144  configuration information.</P>
1145 <P>Polling is enabled by specifying one or more<A HREF="#BrowsePoll"> <CODE>
1146 BrowsePoll</CODE></A> directives in the<VAR> /etc/cups/cupsd.conf</VAR>
1147  file. For information on making these changes, see<A HREF="#PRINTING_MANAGEMENT">
1148  Chapter 6, &quot;Printing System Management&quot;</A>.</P>
1149 <P>Multiple<A HREF="#BrowsePoll"> <CODE>BrowsePoll</CODE></A> lines can
1150  be used to poll multiple CUPS servers. To limit the amount of polling
1151  you do from client machines, you can have only one of the clients do
1152  the polling and relay that information to the others on the same subnet
1153  (described next).</P>
1154 <H3><A NAME="CLIENT_RELAY">Relaying Printers to Other Clients</A></H3>
1155 <P>When you have clients and servers spread across multiple subnets, the
1156  polling method is inefficient. CUPS provides a<A HREF="#BrowseRelay"> <CODE>
1157 BrowseRelay</CODE></A> directive that enables a single client to relay
1158  (broadcast) the polled printer information to the local subnet.</P>
1159 <P>For example, Server A and Server B are on subnet 1 and subnet 2,
1160  while the clients are on subnet 3. To provide printers to all of the
1161  clients in subnet 3, client C will be configured with the following
1162  directives in<VAR> /etc/cups/cupsd.conf</VAR>:</P>
1163 <UL>
1164 <PRE>
1165 # Poll the two servers
1166 <B>
1167 BrowsePoll ServerA ENTER
1168 BrowsePoll ServerB ENTER
1169 </B>
1170
1171 # Relay the printers to the local subnet
1172 <B>
1173 BrowseRelay 127.0.0.1 192.168.3.255 ENTER
1174 </B></PRE>
1175 </UL>
1176 <P>The<A HREF="#BrowseRelay"> <CODE>BrowseRelay</CODE></A> line
1177  specifies a source address and mask. Any browse packets coming from a
1178  matching address wil be sent to the given broadcast address. In this
1179  case, we want the packets from the local machine (127.0.0.1) relayed to
1180  the other clients.</P>
1181 <P>As printers are found using polling, they are relayed from client C
1182  to the rest of the clients through a broadcast on subnet 3. The rest of
1183  the clients can use the standard<VAR> cupsd.conf</VAR> configuration.</P>
1184 <P>The<A HREF="#BrowseRelay"> <CODE>BrowseRelay</CODE></A> directive can
1185  also be used to relay browsing packets from one network interface to
1186  another. For example, if client C in the previous example had network
1187  interfaces attaches to both subnet 1 and subnet 2, it could use the<A HREF="#BrowseRelay">
1188  <CODE>BrowseRelay</CODE></A> directive exclusively:</P>
1189 <UL>
1190 <PRE>
1191 # Relay the printers from subnet 1 and 2 to subnet 3
1192 <B>
1193 BrowseRelay 192.168.1 192.168.3.255 ENTER
1194 BrowseRelay 192.168.2 192.168.3.255 ENTER
1195 </B></PRE>
1196 </UL>
1197 <H2><A NAME="6_2">Load Balancing and Failsafe Operation</A></H2>
1198 <P>When using server polling or broadcasting, CUPS clients can
1199  automatically merge identical printers on multiple servers into a
1200  single<I> implicit class</I> queue. Clients assume that printers with
1201  the same name on multiple servers are in fact the same printer or type
1202  of printer being served by multiple machines.</P>
1203 <P>If you have two printers, LaserJet@ServerA and LaserJet@ServerB, a
1204  third implicit class called<I> LaserJet</I> will be created
1205  automatically on the client that refers to both printers. If the client
1206  also has a local printer with the name LaserJet then an implicit class
1207  named<I> AnyLaserJet</I> will be created instead.</P>
1208 <P>The client will alternate between servers and automatically stop
1209  sending jobs to a server if it goes down, providing a load-balancing
1210  effect and fail-safe operation with automatic switchover.</P>
1211 <CENTER>
1212 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
1213 <TR><TD><B> NOTE:</B>
1214 <P>Note that implicit classes (<A HREF="#ImplicitClasses"><CODE>
1215 ImplicitClasses</CODE></A>) are enabled by default.</P>
1216 </TD></TR>
1217 </TABLE>
1218 </CENTER>
1219 <H1 ALIGN="RIGHT"><A NAME="PRINTING_MANAGEMENT">6 - Printing System
1220  Management</A></H1>
1221 <P>This chapter shows how you can configure the CUPS server.</P>
1222 <H2><A NAME="7_1">The Basics</A></H2>
1223 <P>Several text files are used to configure CUPS. All of the server
1224  configuration files are located in the<VAR> /etc/cups</VAR> directory:</P>
1225 <UL>
1226 <DL>
1227 <!-- NEED 1in -->
1228
1229 <DT>classes.conf</DT>
1230 <DD>This file contains information on each printer class. Normally you
1231  manipulate this file using the <CODE>lpadmin</CODE> command or the Web
1232  interface.
1233 <BR>&nbsp;
1234 <!-- NEED 1in -->
1235 </DD>
1236 <DT>client.conf</DT>
1237 <DD>This file provides the default server name for client machines. See<A
1238 HREF="#CLIENT_SETUP"> Chapter 5, &quot;Client Setup&quot;</A> for more
1239  information.
1240 <BR>&nbsp;
1241 <!-- NEED 1in -->
1242 </DD>
1243 <DT>cupsd.conf</DT>
1244 <DD>This file controls how the CUPS server (<VAR>/usr/sbin/cupsd</VAR>)
1245  operates and is normally edited by hand.
1246 <BR>&nbsp;
1247 <!-- NEED 1in -->
1248 </DD>
1249 <DT>mime.convs</DT>
1250 <DD>This file contains a list of standard file conversion filters and
1251  their costs. You normally do not edit this file.
1252 <BR>&nbsp;
1253 <!-- NEED 1in -->
1254 </DD>
1255 <DT>mime.types</DT>
1256 <DD>This file contains a list of standard file formats and how to
1257  recognize them. You normally do not edit this file.
1258 <BR>&nbsp;
1259 <!-- NEED 1in -->
1260 </DD>
1261 <DT>printers.conf</DT>
1262 <DD>This file contains information on each printer. Normally you
1263  manipulate this file using the <CODE>lpadmin</CODE> command or the Web
1264  Interface.
1265 <BR>&nbsp;</DD>
1266 </DL>
1267 </UL>
1268 <H2><A NAME="RESTARTING">Restarting the CUPS Server</A></H2>
1269 <P>Once you have made a change to a configuration file you need to
1270  restart the CUPS server by sending it a <CODE>HUP</CODE> signal or
1271  using the supplied initialization script. The CUPS distributions
1272  install the script in the<VAR> init.d</VAR> directory with the name<VAR>
1273  cups</VAR>. The location varies based upon the operating system:</P>
1274 <UL>
1275 <PRE>
1276 <B>/etc/software/init.d/cups restart ENTER</B>
1277 <B>/etc/rc.d/init.d/cups restart ENTER</B>
1278 <B>/etc/init.d/cups restart ENTER</B>
1279 <B>/sbin/init.d/cups restart ENTER</B>
1280 </PRE>
1281 </UL>
1282 <H2><A NAME="7_3">Changing the Server Configuration</A></H2>
1283 <P>The<VAR> /etc/cups/cupsd.conf</VAR> file contains configuration<I>
1284  directives</I> that control how the server functions. Each directive is
1285  listed on a line by itself followed by its value. Comments are
1286  introduced using the number sign (&quot;#&quot;) character at the beginning of a
1287  line. Since the server configuration file consists of plain text, you
1288  can use your favorite text editor to make changes to it.
1289 <!-- NEED 4in -->
1290 </P>
1291 <H2><A NAME="7_4">Server Directives</A></H2>
1292 <P>The<VAR> cupsd.conf</VAR> file contains many directives that
1293  determine how the server operates:</P>
1294 <UL>
1295 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0">
1296 <TR><TD VALIGN="TOP">
1297 <LI><A HREF="#AccessLog"><CODE>AccessLog</CODE></A></LI>
1298 <LI><A HREF="#Allow"><CODE>Allow</CODE></A></LI>
1299 <LI><A HREF="#AuthClass"><CODE>AuthClass</CODE></A></LI>
1300 <LI><A HREF="#AuthGroupName"><CODE>AuthGroupName</CODE></A></LI>
1301 <LI><A HREF="#AuthType"><CODE>AuthType</CODE></A></LI>
1302 <LI><A HREF="#AutoPurgeJobs"><CODE>AutoPurgeJobs</CODE></A></LI>
1303 <LI><A HREF="#BrowseAddress"><CODE>BrowseAddress</CODE></A></LI>
1304 <LI><A HREF="#BrowseAllow"><CODE>BrowseAllow</CODE></A></LI>
1305 <LI><A HREF="#BrowseDeny"><CODE>BrowseDeny</CODE></A></LI>
1306 <LI><A HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A></LI>
1307 <LI><A HREF="#BrowseOrder"><CODE>BrowseOrder</CODE></A></LI>
1308 <LI><A HREF="#BrowsePoll"><CODE>BrowsePoll</CODE></A></LI>
1309 <LI><A HREF="#BrowsePort"><CODE>BrowsePort</CODE></A></LI>
1310 <LI><A HREF="#BrowseProtocols"><CODE>BrowseProtocols</CODE></A></LI>
1311 <LI><A HREF="#BrowseRelay"><CODE>BrowseRelay</CODE></A></LI>
1312 <LI><A HREF="#BrowseShortNames"><CODE>BrowseShortNames</CODE></A></LI>
1313 <LI><A HREF="#BrowseTimeout"><CODE>BrowseTimeout</CODE></A></LI>
1314 <LI><A HREF="#Browsing"><CODE>Browsing</CODE></A></LI>
1315 <LI><A HREF="#Classification"><CODE>Classification</CODE></A></LI>
1316 <LI><A HREF="#ClassifyOverride"><CODE>ClassifyOverride</CODE></A></LI>
1317 <LI><A HREF="#ConfigFilePerm"><CODE>ConfigFilePerm</CODE></A></LI>
1318 <LI><A HREF="#DataDir"><CODE>DataDir</CODE></A></LI>
1319 <LI><A HREF="#DefaultCharset"><CODE>DefaultCharset</CODE></A></LI>
1320 <LI><A HREF="#DefaultLanguage"><CODE>DefaultLanguage</CODE></A></LI>
1321 <LI><A HREF="#Deny"><CODE>Deny</CODE></A></LI>
1322 <LI><A HREF="#DocumentRoot"><CODE>DocumentRoot</CODE></A></LI>
1323 <LI><A HREF="#Encryption"><CODE>Encryption</CODE></A></LI>
1324 </TD><TD VALIGN="TOP"> &nbsp;&nbsp;&nbsp;</TD><TD VALIGN="TOP">
1325 <LI><A HREF="#ErrorLog"><CODE>ErrorLog</CODE></A></LI>
1326 <LI><A HREF="#FilterLimit"><CODE>FilterLimit</CODE></A></LI>
1327 <LI><A HREF="#FilterNice"><CODE>FilterNice</CODE></A></LI>
1328 <LI><A HREF="#FontPath"><CODE>FontPath</CODE></A></LI>
1329 <LI><A HREF="#Group"><CODE>Group</CODE></A></LI>
1330 <LI><A HREF="#HideImplicitMembers"><CODE>HideImplicitMembers</CODE></A></LI>
1331 <LI><A HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A></LI>
1332 <LI><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A></LI>
1333 <LI><A HREF="#ImplicitAnyClasses"><CODE>ImplicitAnyClasses</CODE></A></LI>
1334 <LI><A HREF="#Include"><CODE>Include</CODE></A></LI>
1335 <LI><A HREF="#KeepAliveTimeout"><CODE>KeepAliveTimeout</CODE></A></LI>
1336 <LI><A HREF="#KeepAlive"><CODE>KeepAlive</CODE></A></LI>
1337 <LI><A HREF="#Limit"><CODE>Limit</CODE></A></LI>
1338 <LI><A HREF="#LimitExcept"><CODE>LimitExcept</CODE></A></LI>
1339 <LI><A HREF="#LimitRequestBody"><CODE>LimitRequestBody</CODE></A></LI>
1340 <LI><A HREF="#Listen"><CODE>Listen</CODE></A></LI>
1341 <LI><A HREF="#Location"><CODE>Location</CODE></A></LI>
1342 <LI><A HREF="#LogFilePerm"><CODE>LogFilePerm</CODE></A></LI>
1343 <LI><A HREF="#LogLevel"><CODE>LogLevel</CODE></A></LI>
1344 <LI><A HREF="#MaxClients"><CODE>MaxClients</CODE></A></LI>
1345 <LI><A HREF="#MaxClientsPerHost"><CODE>MaxClientsPerHost</CODE></A></LI>
1346 <LI><A HREF="#MaxCopies"><CODE>MaxCopies</CODE></A></LI>
1347 <LI><A HREF="#MaxJobs"><CODE>MaxJobs</CODE></A></LI>
1348 <LI><A HREF="#MaxJobsPerPrinter"><CODE>MaxJobsPerPrinter</CODE></A></LI>
1349 <LI><A HREF="#MaxJobsPerUser"><CODE>MaxJobsPerUser</CODE></A></LI>
1350 <LI><A HREF="#MaxLogSize"><CODE>MaxLogSize</CODE></A></LI>
1351 <LI><A HREF="#MaxRequestSize"><CODE>MaxRequestSize</CODE></A></LI>
1352 <LI><A HREF="#Order"><CODE>Order</CODE></A></LI>
1353 <LI><A HREF="#PageLog"><CODE>PageLog</CODE></A></LI>
1354 </TD><TD VALIGN="TOP"> &nbsp;&nbsp;&nbsp;</TD><TD VALIGN="TOP">
1355 <LI><A HREF="#Port"><CODE>Port</CODE></A></LI>
1356 <LI><A HREF="#PreserveJobFiles"><CODE>PreserveJobFiles</CODE></A></LI>
1357 <LI><A HREF="#PreserveJobHistory"><CODE>PreserveJobHistory</CODE></A></LI>
1358 <LI><A HREF="#Printcap"><CODE>Printcap</CODE></A></LI>
1359 <LI><A HREF="#PrintcapFormat"><CODE>PrintcapFormat</CODE></A></LI>
1360 <LI><A HREF="#PrintcapGUI"><CODE>PrintcapGUI</CODE></A></LI>
1361 <LI><A HREF="#RemoteRoot"><CODE>RemoteRoot</CODE></A></LI>
1362 <LI><A HREF="#RequestRoot"><CODE>RequestRoot</CODE></A></LI>
1363 <LI><A HREF="#Require"><CODE>Require</CODE></A></LI>
1364 <LI><A HREF="#RIPCache"><CODE>RIPCache</CODE></A></LI>
1365 <LI><A HREF="#RootCertDuration"><CODE>RootCertDuration</CODE></A></LI>
1366 <LI><A HREF="#RunAsUser"><CODE>RunAsUser</CODE></A></LI>
1367 <LI><A HREF="#Satisfy"><CODE>Satisfy</CODE></A></LI>
1368 <LI><A HREF="#ServerAdmin"><CODE>ServerAdmin</CODE></A></LI>
1369 <LI><A HREF="#ServerBin"><CODE>ServerBin</CODE></A></LI>
1370 <LI><A HREF="#ServerCertificate"><CODE>ServerCertificate</CODE></A></LI>
1371 <LI><A HREF="#ServerKey"><CODE>ServerKey</CODE></A></LI>
1372 <LI><A HREF="#ServerName"><CODE>ServerName</CODE></A></LI>
1373 <LI><A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A></LI>
1374 <LI><A HREF="#SSLListen"><CODE>SSLListen</CODE></A></LI>
1375 <LI><A HREF="#SSLPort"><CODE>SSLPort</CODE></A></LI>
1376 <LI><A HREF="#SystemGroup"><CODE>SystemGroup</CODE></A></LI>
1377 <LI><A HREF="#TempDir"><CODE>TempDir</CODE></A></LI>
1378 <LI><A HREF="#Timeout"><CODE>Timeout</CODE></A></LI>
1379 <LI><A HREF="#User"><CODE>User</CODE></A></LI>
1380 </TD></TR>
1381 </TABLE>
1382 </UL>
1383
1384 <!-- NEED 3in -->
1385 <H3><A NAME="AccessLog">AccessLog</A></H3>
1386 <HR>
1387 <H4>Examples</H4>
1388 <UL>
1389 <PRE>
1390 AccessLog /var/log/cups/access_log
1391 AccessLog /var/log/cups/access_log-%s
1392 AccessLog syslog
1393 </PRE>
1394 </UL>
1395 <H4>Description</H4>
1396 <P>The <CODE>AccessLog</CODE> directive sets the name of the access log
1397  file. If the filename is not absolute then it is assumed to be relative
1398  to the<A HREF="#ServerRoot"> <CODE>ServerRoot</CODE></A> directory. The
1399  access log file is stored in &quot;common log format&quot; and can be used by any
1400  web access reporting tool to generate a report on CUPS server activity.</P>
1401 <P>The server name can be included in the filename by using <CODE>%s</CODE>
1402  in the name.</P>
1403 <P>The special name &quot;syslog&quot; can be used to send the access information
1404  to the system log instead of a plain file.</P>
1405 <P>The default access log file is<VAR> /var/log/cups/access_log</VAR>.
1406 <!-- NEED 6in -->
1407 </P>
1408 <H3><A NAME="Allow">Allow</A></H3>
1409 <HR>
1410 <H4>Examples</H4>
1411 <UL>
1412 <PRE>
1413 Allow from All
1414 Allow from None
1415 Allow from *.domain.com
1416 Allow from .domain.com
1417 Allow from host.domain.com
1418 Allow from nnn.*
1419 Allow from nnn.nnn.*
1420 Allow from nnn.nnn.nnn.*
1421 Allow from nnn.nnn.nnn.nnn
1422 Allow from nnn.nnn.nnn.nnn/mm
1423 Allow from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
1424 Allow from @LOCAL
1425 Allow from @IF(name)
1426 </PRE>
1427 </UL>
1428 <H4>Description</H4>
1429 <P>The <CODE>Allow</CODE> directive specifies a hostname, IP address, or
1430  network that is allowed access to the server. <CODE>Allow</CODE>
1431  directives are cummulative, so multiple <CODE>Allow</CODE> directives
1432  can be used to allow access for multiple hosts or networks. The <CODE>
1433 /mm</CODE> notation specifies a CIDR netmask:
1434 <CENTER>
1435 <TABLE BORDER="1">
1436 <TR><TH WIDTH="10%">mm</TH><TH WIDTH="20%">netmask</TH><TH WIDTH="10%">
1437 mm</TH><TH WIDTH="20%">netmask</TH></TR>
1438 <TR><TD ALIGN="CENTER">0</TD><TD ALIGN="CENTER">0.0.0.0</TD><TD ALIGN="CENTER">
1439 8</TD><TD ALIGN="CENTER">255.0.0.0</TD></TR>
1440 <TR><TD ALIGN="CENTER">1</TD><TD ALIGN="CENTER">128.0.0.0</TD><TD ALIGN="CENTER">
1441 16</TD><TD ALIGN="CENTER">255.255.0.0</TD></TR>
1442 <TR><TD ALIGN="CENTER">2</TD><TD ALIGN="CENTER">192.0.0.0</TD><TD ALIGN="CENTER">
1443 24</TD><TD ALIGN="CENTER">255.255.255.0</TD></TR>
1444 <TR><TD ALIGN="CENTER">...</TD><TD ALIGN="CENTER">...</TD><TD ALIGN="CENTER">
1445 32</TD><TD ALIGN="CENTER">255.255.255.255</TD></TR>
1446 </TABLE>
1447 </CENTER>
1448 </P>
1449 <P>The <CODE>@LOCAL</CODE> name will allow access from all local network
1450  interfaces, but not remote point-to-point interfaces. The <CODE>
1451 @IF(name)</CODE> name will allow access from the named interface.</P>
1452 <P>The <CODE>Allow</CODE> directive must appear inside a<A HREF="#Location">
1453  <CODE>Location</CODE></A> directive.
1454 <!-- NEED 3in -->
1455 </P>
1456 <H3><A NAME="AuthClass">AuthClass</A></H3>
1457 <HR>
1458 <H4>Examples</H4>
1459 <UL>
1460 <PRE>
1461 AuthClass Anonymous
1462 AuthClass User
1463 AuthClass System
1464 AuthClass Group
1465 </PRE>
1466 </UL>
1467 <H4>Description</H4>
1468 <P>The <CODE>AuthClass</CODE> directive defines what level of
1469  authentication is required:</P>
1470 <UL>
1471 <LI><CODE>Anonymous</CODE> - No authentication should be performed
1472  (default.)</LI>
1473 <LI><CODE>User</CODE> - A valid username and password is required.</LI>
1474 <LI><CODE>System</CODE> - A valid username and password is required, and
1475  the username must belong to the &quot;sys&quot; group; this can be changed using
1476  the<A HREF="#SystemGroup"> <CODE>SystemGroup</CODE></A> directive.</LI>
1477 <LI><CODE>Group</CODE> - A valid username and password is required, and
1478  the username must belong to the group named by the <CODE>AuthGroupName</CODE>
1479  directive.</LI>
1480 </UL>
1481 <P>The <CODE>AuthClass</CODE> directive must appear inside a<A HREF="#Location">
1482  <CODE>Location</CODE></A> directive.
1483 <!-- NEED 3in -->
1484 </P>
1485 <H3><A NAME="AuthGroupName">AuthGroupName</A></H3>
1486 <HR>
1487 <H4>Examples</H4>
1488 <UL>
1489 <PRE>
1490 AuthGroupName mygroup
1491 AuthGroupName lp
1492 </PRE>
1493 </UL>
1494 <H4>Description</H4>
1495 <P>The <CODE>AuthGroupName</CODE> directive sets the group to use for <CODE>
1496 Group</CODE> authentication.</P>
1497 <P>The <CODE>AuthGroupName</CODE> directive must appear inside a<A HREF="#Location">
1498  <CODE>Location</CODE></A> directive.
1499 <!-- NEED 3in -->
1500 </P>
1501 <H3><A NAME="AuthType">AuthType</A></H3>
1502 <HR>
1503 <H4>Examples</H4>
1504 <UL>
1505 <PRE>
1506 AuthType None
1507 AuthType Basic
1508 AuthType Digest
1509 AuthType BasicDigest
1510 </PRE>
1511 </UL>
1512 <H4>Description</H4>
1513 <P>The <CODE>AuthType</CODE> directive defines the type of
1514  authentication to perform:</P>
1515 <UL>
1516 <LI><CODE>None</CODE> - No authentication should be performed (default.)</LI>
1517 <LI><CODE>Basic</CODE> - Basic authentication should be performed using
1518  the UNIX password and group files.</LI>
1519 <LI><CODE>Digest</CODE> - Digest authentication should be performed
1520  using the<VAR> /etc/cups/passwd.md5</VAR> file.</LI>
1521 <LI><CODE>BasicDigest</CODE> - Basic authentication should be performed
1522  using the<VAR> /etc/cups/passwd.md5</VAR> file.</LI>
1523 </UL>
1524 <P>When using <CODE>Basic</CODE>, <CODE>Digest</CODE>, or <CODE>
1525 BasicDigest</CODE> authentication, clients connecting through the <CODE>
1526 localhost</CODE> interface can also authenticate using<A HREF="#CERTIFICATES">
1527  certificates</A>.</P>
1528 <P>The <CODE>AuthType</CODE> directive must appear inside a<A HREF="#Location">
1529  <CODE>Location</CODE></A> directive.
1530 <!-- NEED 3in -->
1531 </P>
1532 <H3><A NAME="AutoPurgeJobs">AutoPurgeJobs</A></H3>
1533 <HR>
1534 <H4>Examples</H4>
1535 <UL>
1536 <PRE>
1537 AutoPurgeJobs Yes
1538 AutoPurgeJobs No
1539 </PRE>
1540 </UL>
1541 <H4>Description</H4>
1542 <P>The <CODE>AutoPurgeJobs</CODE> directive specifies whether or not to
1543  purge completed jobs once they are no longer required for quotas. This
1544  option has no effect if quotas are not enabled. The default setting is <CODE>
1545 No</CODE>.
1546 <!-- NEED 5in -->
1547 </P>
1548 <H3><A NAME="BrowseAddress">BrowseAddress</A></H3>
1549 <HR>
1550 <H4>Examples</H4>
1551 <UL>
1552 <PRE>
1553 BrowseAddress 255.255.255.255:631
1554 BrowseAddress 192.0.2.255:631
1555 BrowseAddress host.domain.com:631
1556 BrowseAddress @LOCAL
1557 BrowseAddress @IF(name)
1558 </PRE>
1559 </UL>
1560 <H4>Description</H4>
1561 <P>The <CODE>BrowseAddress</CODE> directive specifies an address to send
1562  browsing information to. Multiple <CODE>BrowseAddress</CODE> directives
1563  can be specified to send browsing information to different networks or
1564  systems.</P>
1565 <P>The <CODE>@LOCAL</CODE> name will broadcast printer information to
1566  all local interfaces. The <CODE>@IF(name)</CODE> name will broadcast to
1567  the named interface.</P>
1568 <P>No browse addresses are set by default.</P>
1569 <CENTER>
1570 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
1571 <TR><TD><B> NOTE:</B>
1572 <P>If you are using HP-UX 10.20 and a subnet that is not 24, 16, or 8
1573  bits, printer browsing (and in fact all broadcast reception) will not
1574  work. This problem appears to be fixed in HP-UX 11.0.</P>
1575 </TD></TR>
1576 </TABLE>
1577 </CENTER>
1578
1579 <!-- NEED 4in -->
1580 <H3><A NAME="BrowseAllow">BrowseAllow</A></H3>
1581 <HR>
1582 <H4>Examples</H4>
1583 <UL>
1584 <PRE>
1585 BrowseAllow from all
1586 BrowseAllow from none
1587 BrowseAllow from 192.0.2
1588 BrowseAllow from 192.0.2.0/24
1589 BrowseAllow from 192.0.2.0/255.255.255.0
1590 BrowseAllow from *.domain.com
1591 BrowseAllow from @LOCAL
1592 BrowseAllow from @IF(name)
1593 </PRE>
1594 </UL>
1595 <H4>Description</H4>
1596 <P>The <CODE>BrowseAllow</CODE> directive specifies a system or network
1597  to accept browse packets from. The default is to accept browse packets
1598  from all hosts.</P>
1599 <P>Host and domain name matching require that you enable the<A HREF="#HostNameLookups">
1600  <CODE>HostNameLookups</CODE></A> directive.</P>
1601 <P>IP address matching supports exact matches, partial addresses that
1602  match networks using netmasks of 255.0.0.0, 255.255.0.0, and
1603  255.255.255.0, or network addresses using the specified netmask or bit
1604  count.</P>
1605 <P>The <CODE>@LOCAL</CODE> name will allow browse data from all local
1606  network interfaces, but not remote point-to-point interfaces. The <CODE>
1607 @IF(name)</CODE> name will allow browse data from the named interface.
1608 <!-- NEED 4in -->
1609 </P>
1610 <H3><A NAME="BrowseDeny">BrowseDeny</A></H3>
1611 <HR>
1612 <H4>Examples</H4>
1613 <UL>
1614 <PRE>
1615 BrowseDeny from all
1616 BrowseDeny from none
1617 BrowseDeny from 192.0.2
1618 BrowseDeny from 192.0.2.0/24
1619 BrowseDeny from 192.0.2.0/255.255.255.0
1620 BrowseDeny from *.domain.com
1621 BrowseDeny from @LOCAL
1622 BrowseDeny from @IF(name)
1623 </PRE>
1624 </UL>
1625 <H4>Description</H4>
1626 <P>The <CODE>BrowseDeny</CODE> directive specifies a system or network
1627  to reject browse packets from. The default is to deny browse packets
1628  from no hosts.</P>
1629 <P>Host and domain name matching require that you enable the<A HREF="#HostNameLookups">
1630  <CODE>HostNameLookups</CODE></A> directive.</P>
1631 <P>IP address matching supports exact matches, partial addresses that
1632  match networks using netmasks of 255.0.0.0, 255.255.0.0, and
1633  255.255.255.0, or network addresses using the specified netmask or bit
1634  count.</P>
1635 <P>The <CODE>@LOCAL</CODE> name will block browse data from all local
1636  network interfaces, but not remote point-to-point interfaces. The <CODE>
1637 @IF(name)</CODE> name will block browse data from the named interface.
1638 <!-- NEED 3in -->
1639 </P>
1640 <H3><A NAME="BrowseOrder">BrowseOrder</A></H3>
1641 <HR>
1642 <H4>Examples</H4>
1643 <UL>
1644 <PRE>
1645 BrowseOrder allow,deny
1646 BrowseOrder deny,allow
1647 </PRE>
1648 </UL>
1649 <H4>Description</H4>
1650 <P>The <CODE>BrowseOrder</CODE> directive specifies the order of
1651  allow/deny processing. The default order is <CODE>deny,allow</CODE>:</P>
1652 <UL>
1653 <LI><CODE>allow,deny</CODE> - Browse packets are accepted unless
1654  specifically denied.</LI>
1655 <LI><CODE>deny,allow</CODE> - Browse packets are rejected unless
1656  specifically allowed.</LI>
1657 </UL>
1658
1659 <!-- NEED 3in -->
1660 <H3><A NAME="BrowseInterval">BrowseInterval</A></H3>
1661 <HR>
1662 <H4>Examples</H4>
1663 <UL>
1664 <PRE>
1665 BrowseInterval 0
1666 BrowseInterval 30
1667 </PRE>
1668 </UL>
1669 <H4>Description</H4>
1670 <P>The <CODE>BrowseInterval</CODE> directive specifies the maximum
1671  amount of time between browsing updates. Specifying a value of 0
1672  seconds disables outgoing browse updates but allows a server to receive
1673  printer information from other hosts.</P>
1674 <P>The <CODE>BrowseInterval</CODE> value should always be less than the<A
1675 HREF="#BrowseTimeout"> <CODE>BrowseTimeout</CODE></A> value. Otherwise
1676  printers and classes will disappear from client systems between
1677  updates.
1678 <!-- NEED 3in -->
1679 </P>
1680 <H3><A NAME="BrowsePoll">BrowsePoll</A></H3>
1681 <HR>
1682 <H4>Examples</H4>
1683 <UL>
1684 <PRE>
1685 BrowsePoll 192.0.2.2:631
1686 BrowsePoll host.domain.com:631
1687 </PRE>
1688 </UL>
1689 <H4>Description</H4>
1690 <P>The <CODE>BrowsePoll</CODE> directive polls a server for available
1691  printers once every<A HREF="#BrowseInterval"> <CODE>BrowseInterval</CODE>
1692 </A> seconds. Multiple <CODE>BrowsePoll</CODE> directives can be
1693  specified to poll multiple servers.</P>
1694 <P>If <CODE>BrowseInterval</CODE> is set to 0 then the server is polled
1695  once every 30 seconds.
1696 <!-- NEED 3in -->
1697 </P>
1698 <H3><A NAME="BrowsePort">BrowsePort</A></H3>
1699 <HR>
1700 <H4>Examples</H4>
1701 <UL>
1702 <PRE>
1703 BrowsePort 631
1704 BrowsePort 9999
1705 </PRE>
1706 </UL>
1707 <H4>Description</H4>
1708 <P>The <CODE>BrowsePort</CODE> directive specifies the UDP port number
1709  used for browse packets. The default port number is 631.</P>
1710 <CENTER>
1711 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
1712 <TR><TD><B> NOTE:</B>
1713 <P>You must set the <CODE>BrowsePort</CODE> to the same value on all of
1714  the systems that you want to see.</P>
1715 </TD></TR>
1716 </TABLE>
1717 </CENTER>
1718
1719 <!-- NEED 3in -->
1720 <H3><A NAME="BrowseProtocols">BrowseProtocols</A></H3>
1721 <HR>
1722 <H4>Examples</H4>
1723 <UL>
1724 <PRE>
1725 BrowseProtocols CUPS
1726 BrowseProtocols SLP
1727 BrowseProtocols CUPS SLP
1728 BrowseProtocols all
1729 </PRE>
1730 </UL>
1731 <H4>Description</H4>
1732 <P>The <CODE>BrowseProtocols</CODE> directive specifies the protocols to
1733  use when collecting and distributing shared printers on the local
1734  network. The default protocol is <CODE>CUPS</CODE>, which is a
1735  broadcast-based protocol.</P>
1736 <CENTER>
1737 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
1738 <TR><TD><B> NOTE:</B>
1739 <P>When using the <CODE>SLP</CODE> protocol, you must have at least one
1740  Directory Agent (DA) server on your network. Otherwise the CUPS
1741  scheduler (<CODE>cupsd</CODE>) will not respond to client requests for
1742  several seconds while polling the network.</P>
1743 </TD></TR>
1744 </TABLE>
1745 </CENTER>
1746
1747 <!-- NEED 4in -->
1748 <H3><A NAME="BrowseRelay">BrowseRelay</A></H3>
1749 <HR>
1750 <H4>Examples</H4>
1751 <UL>
1752 <PRE>
1753 BrowseRelay 193.0.2.1 192.0.2.255
1754 BrowseRelay 193.0.2.0/255.255.255.0 192.0.2.255
1755 BrowseRelay 193.0.2.0/24 192.0.2.255
1756 BrowseRelay *.domain.com 192.0.2.255
1757 BrowseRelay host.domain.com 192.0.2.255
1758 </PRE>
1759 </UL>
1760 <H4>Description</H4>
1761 <P>The <CODE>BrowseRelay</CODE> directive specifies source and
1762  destination addresses for relaying browsing information from one host
1763  or network to another. Multiple <CODE>BrowseRelay</CODE> directives can
1764  be specified as needed.</P>
1765 <P><CODE>BrowseRelay</CODE> is typically used on systems that bridge
1766  multiple subnets using one or more network interfaces. It can also be
1767  used to relay printer information from polled servers with the line:</P>
1768 <UL>
1769 <PRE>
1770 BrowseRelay 127.0.0.1 255.255.255.255
1771 </PRE>
1772 </UL>
1773 <P>This effectively provides access to printers on a WAN for all clients
1774  on the LAN(s).
1775 <!-- NEED 3in -->
1776 </P>
1777 <H3><A NAME="BrowseShortNames">BrowseShortNames</A></H3>
1778 <HR>
1779 <H4>Examples</H4>
1780 <UL>
1781 <PRE>
1782 BrowseShortNames Yes
1783 BrowseShortNames No
1784 </PRE>
1785 </UL>
1786 <H4>Description</H4>
1787 <P>The <CODE>BrowseShortNames</CODE> directive specifies whether or not
1788  short names are used for remote printers when possible. Short names are
1789  just the remote printer name, without the server (&quot;printer&quot;). If more
1790  than one remote printer is detected with the same name, the printers
1791  will have long names (&quot;printer@server1&quot;, &quot;printer@server2&quot;.)</P>
1792 <P>The default value for this option is <CODE>Yes</CODE>.
1793 <!-- NEED 3in -->
1794 </P>
1795 <H3><A NAME="BrowseTimeout">BrowseTimeout</A></H3>
1796 <HR>
1797 <H4>Examples</H4>
1798 <UL>
1799 <PRE>
1800 BrowseTimeout 300
1801 BrowseTimeout 60
1802 </PRE>
1803 </UL>
1804 <H4>Description</H4>
1805 <P>The <CODE>BrowseTimeout</CODE> directive sets the timeout for printer
1806  or class information that is received in browse packets. Once a printer
1807  or class times out it is removed from the list of available
1808  destinations.</P>
1809 <P>The <CODE>BrowseTimeout</CODE> value should always be greater than
1810  the<A HREF="#BrowseInterval"> <CODE>BrowseInterval</CODE></A> value.
1811  Otherwise printers and classes will disappear from client systems
1812  between updates.
1813 <!-- NEED 4in -->
1814 </P>
1815 <H3><A NAME="Browsing">Browsing</A></H3>
1816 <HR>
1817 <H4>Examples</H4>
1818 <UL>
1819 <PRE>
1820 Browsing On
1821 Browsing Off
1822 </PRE>
1823 </UL>
1824 <H4>Description</H4>
1825 <P>The <CODE>Browsing</CODE> directive controls whether or not network
1826  printer browsing is enabled. The default setting is <CODE>On</CODE>.</P>
1827 <CENTER>
1828 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
1829 <TR><TD><B> NOTE:</B>
1830 <P>If you are using HP-UX 10.20 and a subnet that is not 24, 16, or 8
1831  bits, printer browsing (and in fact all broadcast reception) will not
1832  work. This problem appears to be fixed in HP-UX 11.0.</P>
1833 </TD></TR>
1834 </TABLE>
1835 </CENTER>
1836
1837 <!-- NEED 3in -->
1838 <H3><A NAME="Classification">Classification</A></H3>
1839 <HR>
1840 <H4>Examples</H4>
1841 <UL>
1842 <PRE>
1843 Classification
1844 Classification classified
1845 Classification confidential
1846 Classification secret
1847 Classification topsecret
1848 Classification unclassified
1849 </PRE>
1850 </UL>
1851 <H4>Description</H4>
1852 <P>The <CODE>Classification</CODE> directive sets the classification
1853  level on the server. When this option is set, at least one of the
1854  banner pages is forced to the classification level, and the
1855  classification is placed on each page of output. The default is no
1856  classification level.
1857 <!-- NEED 3in -->
1858 </P>
1859 <H3><A NAME="ClassifyOverride">ClassifyOverride</A></H3>
1860 <HR>
1861 <H4>Examples</H4>
1862 <UL>
1863 <PRE>
1864 ClassifyOverride Yes
1865 ClassifyOverride No
1866 </PRE>
1867 </UL>
1868 <H4>Description</H4>
1869 <P>The <CODE>ClassifyOverride</CODE> directive specifies whether users
1870  can override the default classification level on the server. When the
1871  server classification is set, users can change the classification using
1872  the <CODE>job-sheets</CODE> option and can choose to only print one
1873  security banner before or after the job. If the <CODE>job-sheets</CODE>
1874  option is set to <CODE>none</CODE> then the server default
1875  classification is used.</P>
1876 <P>The default is to not allow classification overrides.
1877 <!-- NEED 3in -->
1878 </P>
1879 <H3><A NAME="ConfigFilePerm">ConfigFilePerm</A></H3>
1880 <HR>
1881 <H4>Examples</H4>
1882 <UL>
1883 <PRE>
1884 ConfigFilePerm 0644
1885 ConfigFilePerm 0600
1886 </PRE>
1887 </UL>
1888 <H4>Description</H4>
1889 <P>The <CODE>ConfigFilePerm</CODE> directive specifies the permissions
1890  to use when writing configuration files. The default is 0600.
1891 <!-- NEED 3in -->
1892 </P>
1893 <H3><A NAME="DataDir">DataDir</A></H3>
1894 <HR>
1895 <H4>Examples</H4>
1896 <UL>
1897 <PRE>
1898 DataDir /usr/share/cups
1899 </PRE>
1900 </UL>
1901 <H4>Description</H4>
1902 <P>The <CODE>DataDir</CODE> directive sets the directory to use for data
1903  files.
1904 <!-- NEED 3in -->
1905 </P>
1906 <H3><A NAME="DefaultCharset">DefaultCharset</A></H3>
1907 <HR>
1908 <H4>Examples</H4>
1909 <UL>
1910 <PRE>
1911 DefaultCharset utf-8
1912 DefaultCharset iso-8859-1
1913 DefaultCharset windows-1251
1914 </PRE>
1915 </UL>
1916 <H4>Description</H4>
1917 <P>The <CODE>DefaultCharset</CODE> directive sets the default character
1918  set to use for client connections. The default character set is <CODE>
1919 utf-8</CODE> but is overridden by the character set for the language
1920  specified by the client or the <CODE>DefaultLanguage</CODE> directive.
1921 <!-- NEED 3in -->
1922 </P>
1923 <H3><A NAME="DefaultLanguage">DefaultLanguage</A></H3>
1924 <HR>
1925 <H4>Examples</H4>
1926 <UL>
1927 <PRE>
1928 DefaultLanguage de
1929 DefaultLanguage en
1930 DefaultLanguage es
1931 DefaultLanguage fr
1932 DefaultLanguage it
1933 </PRE>
1934 </UL>
1935 <H4>Description</H4>
1936 <P>The <CODE>DefaultLanguage</CODE> directive specifies the default
1937  language to use for client connections. Setting the default language
1938  also sets the default character set if a language localization file
1939  exists for it. The default language is &quot;en&quot; for English.
1940 <!-- NEED 5in -->
1941 </P>
1942 <H3><A NAME="Deny">Deny</A></H3>
1943 <HR>
1944 <H4>Examples</H4>
1945 <UL>
1946 <PRE>
1947 Deny from All
1948 Deny from None
1949 Deny from *.domain.com
1950 Deny from .domain.com
1951 Deny from host.domain.com
1952 Deny from nnn.*
1953 Deny from nnn.nnn.*
1954 Deny from nnn.nnn.nnn.*
1955 Deny from nnn.nnn.nnn.nnn
1956 Deny from nnn.nnn.nnn.nnn/mm
1957 Deny from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
1958 Deny from @LOCAL
1959 Deny from @IF(name)
1960 </PRE>
1961 </UL>
1962 <H4>Description</H4>
1963 <P>The <CODE>Deny</CODE> directive specifies a hostname, IP address, or
1964  network that is allowed access to the server. <CODE>Deny</CODE>
1965  directives are cummulative, so multiple <CODE>Deny</CODE> directives
1966  can be used to allow access for multiple hosts or networks. The <CODE>
1967 /mm</CODE> notation specifies a CIDR netmask:
1968 <CENTER>
1969 <TABLE BORDER="1">
1970 <TR><TH WIDTH="10%">mm</TH><TH WIDTH="20%">netmask</TH><TH WIDTH="10%">
1971 mm</TH><TH WIDTH="20%">netmask</TH></TR>
1972 <TR><TD ALIGN="CENTER">0</TD><TD ALIGN="CENTER">0.0.0.0</TD><TD ALIGN="CENTER">
1973 8</TD><TD ALIGN="CENTER">255.0.0.0</TD></TR>
1974 <TR><TD ALIGN="CENTER">1</TD><TD ALIGN="CENTER">128.0.0.0</TD><TD ALIGN="CENTER">
1975 16</TD><TD ALIGN="CENTER">255.255.0.0</TD></TR>
1976 <TR><TD ALIGN="CENTER">2</TD><TD ALIGN="CENTER">192.0.0.0</TD><TD ALIGN="CENTER">
1977 24</TD><TD ALIGN="CENTER">255.255.255.0</TD></TR>
1978 <TR><TD ALIGN="CENTER">...</TD><TD ALIGN="CENTER">...</TD><TD ALIGN="CENTER">
1979 32</TD><TD ALIGN="CENTER">255.255.255.255</TD></TR>
1980 </TABLE>
1981 </CENTER>
1982 </P>
1983 <P>The <CODE>@LOCAL</CODE> name will deny access from all local network
1984  interfaces, but not remote point-to-point interfaces. The <CODE>
1985 @IF(name)</CODE> name will deny access from the named interface.</P>
1986 <P>The <CODE>Deny</CODE> directive must appear inside a<A HREF="#Location">
1987  <CODE>Location</CODE></A> directive.
1988 <!-- NEED 3in -->
1989 </P>
1990 <H3><A NAME="DocumentRoot">DocumentRoot</A></H3>
1991 <HR>
1992 <H4>Examples</H4>
1993 <UL>
1994 <PRE>
1995 DocumentRoot /usr/share/doc/cups
1996 DocumentRoot /foo/bar/doc/cups
1997 </PRE>
1998 </UL>
1999 <H4>Description</H4>
2000 <P>The <CODE>DocumentRoot</CODE> directive specifies the location of web
2001  content for the HTTP server in CUPS. If an absolute path is not
2002  specified then it is assumed to be relative to the<A HREF="#ServerRoot">
2003  <CODE>ServerRoot</CODE></A> directory. The default directory is<VAR>
2004  /usr/share/doc/cups</VAR>.</P>
2005 <P>Documents are first looked up in a sub-directory for the primary
2006  language requested by the client (e.g.<VAR> /usr/share/doc/cups/fr/...</VAR>
2007 ) and then directly under the <CODE>DocumentRoot</CODE> directory (e.g.<VAR>
2008  /usr/share/doc/cups/...</VAR>), so it is possible to localize the web
2009  content by providing subdirectories for each language needed.
2010 <!-- NEED 3in -->
2011 </P>
2012 <H3><A NAME="Encryption">Encryption</A></H3>
2013 <HR>
2014 <H4>Examples</H4>
2015 <UL>
2016 <PRE>
2017 Encryption Never
2018 Encryption IfRequested
2019 Encryption Required
2020 Encryption Always
2021 </PRE>
2022 </UL>
2023 <H4>Description</H4>
2024 <P>The <CODE>Encryption</CODE> directive must appear instead a<A HREF="#Location">
2025  <CODE>Location</CODE></A> section and specifies the encryption settings
2026  for that location. The default setting is <CODE>IfRequested</CODE> for
2027  all locations.
2028 <!-- NEED 3in -->
2029 </P>
2030 <H3><A NAME="ErrorLog">ErrorLog</A></H3>
2031 <HR>
2032 <H4>Examples</H4>
2033 <UL>
2034 <PRE>
2035 ErrorLog /var/log/cups/error_log
2036 ErrorLog /var/log/cups/error_log-%s
2037 ErrorLog syslog
2038 </PRE>
2039 </UL>
2040 <H4>Description</H4>
2041 <P>The <CODE>ErrorLog</CODE> directive sets the name of the error log
2042  file. If the filename is not absolute then it is assumed to be relative
2043  to the<A HREF="#ServerRoot"> <CODE>ServerRoot</CODE></A> directory. The
2044  default error log file is<VAR> /var/log/cups/error_log</VAR>.</P>
2045 <P>The server name can be included in the filename by using <CODE>%s</CODE>
2046  in the name.</P>
2047 <P>The special name &quot;syslog&quot; can be used to send the error information
2048  to the system log instead of a plain file.
2049 <!-- NEED 3in -->
2050 </P>
2051 <H3><A NAME="FilterLimit">FilterLimit</A></H3>
2052 <HR>
2053 <H4>Examples</H4>
2054 <UL>
2055 <PRE>
2056 FilterLimit 0
2057 FilterLimit 200
2058 FilterLimit 1000
2059 </PRE>
2060 </UL>
2061 <H4>Description</H4>
2062 <P>The <CODE>FilterLimit</CODE> directive sets the maximum cost of all
2063  running job filters. It can be used to limit the number of filter
2064  programs that are run on a server to minimize disk, memory, and CPU
2065  resource problems. A limit of 0 disables filter limiting.</P>
2066 <P>An average print to a non-PostScript printer needs a filter limit of
2067  about 200. A PostScript printer needs about half that (100). Setting
2068  the limit below these thresholds will effectively limit the scheduler
2069  to printing a single job at any time.</P>
2070 <P>The default limit is 0.
2071 <!-- NEED 3in -->
2072 </P>
2073 <H3><A NAME="FilterNice">FilterNice</A></H3>
2074 <HR>
2075 <H4>Examples</H4>
2076 <UL>
2077 <PRE>
2078 FilterNice 0
2079 FilterNice 39
2080 FilterNice -10
2081 </PRE>
2082 </UL>
2083 <H4>Description</H4>
2084 <P>The <CODE>FilterNice</CODE> directive sets the scheduling priority of
2085  job filters. Values larger than 0 give filters a lower priority while
2086  values smaller than 0 give filters a higher priority. The <CODE>
2087 FilterNice</CODE> value does not affect the priority of job backends.</P>
2088 <P>The default priority is 0.
2089 <!-- NEED 3in -->
2090 </P>
2091 <H3><A NAME="FontPath">FontPath</A></H3>
2092 <HR>
2093 <H4>Examples</H4>
2094 <UL>
2095 <PRE>
2096 FontPath /foo/bar/fonts
2097 FontPath /usr/share/cups/fonts:/foo/bar/fonts
2098 </PRE>
2099 </UL>
2100 <H4>Description</H4>
2101 <P>The <CODE>FontPath</CODE> directive specifies the font path to use
2102  when searching for fonts. The default font path is <CODE>
2103 /usr/share/cups/fonts</CODE>.
2104 <!-- NEED 3in -->
2105 </P>
2106 <H3><A NAME="Group">Group</A></H3>
2107 <HR>
2108 <H4>Examples</H4>
2109 <UL>
2110 <PRE>
2111 Group sys
2112 Group system
2113 Group root
2114 </PRE>
2115 </UL>
2116 <H4>Description</H4>
2117 <P>The <CODE>Group</CODE> directive specifies the UNIX group that filter
2118  and CGI programs run as. The default group is <CODE>sys</CODE>, <CODE>
2119 system</CODE>, or <CODE>root</CODE> depending on the operating system.
2120 <!-- NEED 3in -->
2121 </P>
2122 <H3><A NAME="HideImplicitMembers">HideImplicitMembers</A></H3>
2123 <HR>
2124 <H4>Examples</H4>
2125 <UL>
2126 <PRE>
2127 HideImplicitMembers Yes
2128 HideImplicitMembers No
2129 </PRE>
2130 </UL>
2131 <H4>Description</H4>
2132 <P>The <CODE>HideImplicitMembers</CODE> directive controls whether the
2133  individual printers in an implicit class are shown to the user. The
2134  default is <CODE>No</CODE>.</P>
2135 <P><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A> must be
2136  enabled for this directive to have any effect.</P>
2137
2138 <!-- NEED 3in -->
2139 <H3><A NAME="HostNameLookups">HostNameLookups</A></H3>
2140 <HR>
2141 <H4>Examples</H4>
2142 <UL>
2143 <PRE>
2144 HostNameLookups On
2145 HostNameLookups Off
2146 HostNameLookups Double
2147 </PRE>
2148 </UL>
2149 <H4>Description</H4>
2150 <P>The <CODE>HostNameLookups</CODE> directive controls whether or not
2151  CUPS looks up the hostname for connecting clients. The <CODE>Double</CODE>
2152  setting causes CUPS to verify that the hostname resolved from the
2153  address matches one of the addresses returned for that hostname. <CODE>
2154 Double</CODE> lookups also prevent clients with unregistered addresses
2155  from connecting to your server. The default is <CODE>Off</CODE> to
2156  avoid the potential server performance problems with hostname lookups.
2157  Set this option to <CODE>On</CODE> or <CODE>Double</CODE> only if
2158  absolutely required.
2159 <!-- NEED 3in -->
2160 </P>
2161 <H3><A NAME="ImplicitClasses">ImplicitClasses</A></H3>
2162 <HR>
2163 <H4>Examples</H4>
2164 <UL>
2165 <PRE>
2166 ImplicitClasses On
2167 ImplicitClasses Off
2168 </PRE>
2169 </UL>
2170 <H4>Description</H4>
2171 <P>The <CODE>ImplicitClasses</CODE> directive controls whether implicit
2172  classes are created based upon the available network printers and
2173  classes. The default setting is <CODE>On</CODE> but is automatically
2174  turned <CODE>Off</CODE> if<A HREF="#Browsing"> <CODE>Browsing</CODE></A>
2175  is turned <CODE>Off</CODE>.
2176 <!-- NEED 3in -->
2177 </P>
2178 <H3><A NAME="ImplicitAnyClasses">ImplicitAnyClasses</A></H3>
2179 <HR>
2180 <H4>Examples</H4>
2181 <UL>
2182 <PRE>
2183 ImplicitAnyClasses On
2184 ImplicitAnyClasses Off
2185 </PRE>
2186 </UL>
2187 <H4>Description</H4>
2188 <P>The <CODE>ImplicitAnyClasses</CODE> directive controls whether
2189  implicit classes for local and remote printers are created with the
2190  name <CODE>AnyPrinter</CODE>. The default setting is <CODE>Off</CODE>.</P>
2191 <P><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A> must be
2192  enabled for this directive to have any effect.</P>
2193
2194 <!-- NEED 3in -->
2195 <H3><A NAME="Include">Include</A></H3>
2196 <HR>
2197 <H4>Examples</H4>
2198 <UL>
2199 <PRE>
2200 Include filename
2201 Include /foo/bar/filename
2202 </PRE>
2203 </UL>
2204 <H4>Description</H4>
2205 <P>The <CODE>Include</CODE> directive includes the named file in the <CODE>
2206 cupsd.conf</CODE> file. If no leading path is provided, the file is
2207  assumed to be relative to the<A HREF="#ServerRoot"> <CODE>ServerRoot</CODE>
2208 </A> directory.</P>
2209
2210 <!-- NEED 3in -->
2211 <H3><A NAME="KeepAlive">KeepAlive</A></H3>
2212 <HR>
2213 <H4>Examples</H4>
2214 <UL>
2215 <PRE>
2216 KeepAlive On
2217 KeepAlive Off
2218 </PRE>
2219 </UL>
2220 <H4>Description</H4>
2221 <P>The <CODE>KeepAlive</CODE> directive controls whether or not to
2222  support persistent HTTP connections. The default is <CODE>On</CODE>.</P>
2223 <P>HTTP/1.1 clients automatically support persistent connections, while
2224  HTTP/1.0 clients must specifically request them using the <CODE>
2225 Keep-Alive</CODE> attribute in the <CODE>Connection:</CODE> field of
2226  each request.
2227 <!-- NEED 3in -->
2228 </P>
2229 <H3><A NAME="KeepAliveTimeout">KeepAliveTimeout</A></H3>
2230 <HR>
2231 <H4>Examples</H4>
2232 <UL>
2233 <PRE>
2234 KeepAliveTimeout 60
2235 KeepAliveTimeout 30
2236 </PRE>
2237 </UL>
2238 <H4>Description</H4>
2239 <P>The <CODE>KeepAliveTimeout</CODE> directive controls how long a
2240  persistent HTTP connection will remain open after the last request. The
2241  default is 60 seconds.
2242 <!-- NEED 3in -->
2243 </P>
2244 <H3><A NAME="Limit">Limit</A></H3>
2245 <HR>
2246 <H4>Examples</H4>
2247 <UL>
2248 <PRE>
2249 &lt;Limit GET POST&gt;
2250 ...
2251 &lt;/Limit&gt;
2252
2253 &lt;Limit ALL&gt;
2254 ...
2255 &lt;/Limit&gt;
2256 </PRE>
2257 </UL>
2258 <H4>Description</H4>
2259 <P>The <CODE>Limit</CODE> directive groups access control directives for
2260  specific types of HTTP requests and must appear inside a<A HREF="#Location">
2261  <CODE>Location</CODE></A> section. Access can be limited for individual
2262  request types (<CODE>DELETE</CODE>, <CODE>GET</CODE>, <CODE>HEAD</CODE>
2263 , <CODE>OPTIONS</CODE>, <CODE>POST</CODE>, <CODE>PUT</CODE>, and <CODE>
2264 TRACE</CODE>) or for all request types (<CODE>ALL</CODE>). The request
2265  type names are case-sensitive for compatibility with Apache.
2266 <!-- NEED 3in -->
2267 </P>
2268 <H3><A NAME="LimitExcept">LimitExcept</A></H3>
2269 <HR>
2270 <H4>Examples</H4>
2271 <UL>
2272 <PRE>
2273 &lt;LimitExcept GET POST&gt;
2274 ...
2275 &lt;/LimitExcept&gt;
2276 </PRE>
2277 </UL>
2278 <H4>Description</H4>
2279 <P>The <CODE>LimitExcept</CODE> directive groups access control
2280  directives for specific types of HTTP requests and must appear inside a<A
2281 HREF="#Location"> <CODE>Location</CODE></A> section. Unlike the<A HREF="#Limit">
2282  <CODE>Limit</CODE></A> directive, <CODE>LimitExcept</CODE> restricts
2283  access for all requests<I> except</I> those listed on the <CODE>
2284 LimitExcept</CODE> line.
2285 <!-- NEED 3in -->
2286 </P>
2287 <H3><A NAME="LimitRequestBody">LimitRequestBody</A></H3>
2288 <HR>
2289 <H4>Examples</H4>
2290 <UL>
2291 <PRE>
2292 LimitRequestBody 10485760
2293 LimitRequestBody 10m
2294 LimitRequestBody 0
2295 </PRE>
2296 </UL>
2297 <H4>Description</H4>
2298 <P>The <CODE>LimitRequestBody</CODE> directive controls the maximum size
2299  of print files, IPP requests, and HTML form data in HTTP POST requests.
2300  The default limit is 0 which disables the limit check.</P>
2301 <P>Also see the identical<A HREF="#MaxRequestSize"> <CODE>MaxRequestSize</CODE>
2302 </A> directive.
2303 <!-- NEED 3in -->
2304 </P>
2305 <H3><A NAME="Listen">Listen</A></H3>
2306 <HR>
2307 <H4>Examples</H4>
2308 <UL>
2309 <PRE>
2310 Listen 127.0.0.1:631
2311 Listen 192.0.2.1:631
2312 </PRE>
2313 </UL>
2314 <H4>Description</H4>
2315 <P>The <CODE>Listen</CODE> directive specifies a network address and
2316  port to listen for connections. Multiple <CODE>Listen</CODE> directives
2317  can be provided to listen on multiple addresses.</P>
2318 <P>The <CODE>Listen</CODE> directive is similar to the<A HREF="#Port"> <CODE>
2319 Port</CODE></A> directive but allows you to restrict access to specific
2320  interfaces or networks.
2321 <!-- NEED 3in -->
2322 </P>
2323 <H3><A NAME="Location">Location</A></H3>
2324 <HR>
2325 <H4>Examples</H4>
2326 <UL>
2327 <PRE>
2328 &lt;Location /&gt;
2329 ...
2330 &lt;/Location&gt;
2331
2332 &lt;Location /admin&gt;
2333 ...
2334 &lt;/Location&gt;
2335
2336 &lt;Location /printers&gt;
2337 ...
2338 &lt;/Location&gt;
2339
2340 &lt;Location /printers/name&gt;
2341 ...
2342 &lt;/Location&gt;
2343
2344 &lt;Location /classes&gt;
2345 ...
2346 &lt;/Location&gt;
2347
2348 &lt;Location /classes/name&gt;
2349 ...
2350 &lt;/Location&gt;
2351 </PRE>
2352 </UL>
2353 <H4>Description</H4>
2354 <P>The <CODE>Location</CODE> directive specifies access control and
2355  authentication options for the specified HTTP resource or path. The<A HREF="#Allow">
2356  <CODE>Allow</CODE></A>,<A HREF="#AuthClass"> <CODE>AuthClass</CODE></A>
2357 ,<A HREF="#AuthGroupName"> <CODE>AuthGroupName</CODE></A>,<A HREF="#AuthType">
2358  <CODE>AuthType</CODE></A>,<A HREF="#Deny"> <CODE>Deny</CODE></A>,<A HREF="#Encryption">
2359  <CODE>Encryption</CODE></A>,<A HREF="#Limit"> <CODE>Limit</CODE></A>,<A HREF="#LimitExcept">
2360  <CODE>LimitExcept</CODE></A>,<A HREF="#Order"> <CODE>Order</CODE></A>,<A
2361 HREF="#Require"> <CODE>Require</CODE></A>, and<A HREF="#Satisfy"> <CODE>
2362 Satisfy</CODE></A> directives may all appear inside a location.
2363 <CENTER>
2364 <TABLE BORDER="1"><CAPTION>Locations on the Server.</CAPTION>
2365 <TR><TH>Location</TH><TH>Description</TH></TR>
2366 <TR><TD>/</TD><TD>The path for all get operations (get-printers,
2367  get-jobs, etc.)</TD></TR>
2368 <TR><TD>/admin</TD><TD>The path for all administration operations
2369  (add-printer, delete-printer, start-printer, etc.)</TD></TR>
2370 <TR><TD>/admin/conf</TD><TD>The path for access to the CUPS
2371  configuration files (cupsd.conf, client.conf, etc.)</TD></TR>
2372 <TR><TD>/classes</TD><TD>The path for all classes</TD></TR>
2373 <TR><TD>/classes/name</TD><TD>The resource for class <CODE>name</CODE></TD>
2374 </TR>
2375 <TR><TD>/jobs</TD><TD>The path for all jobs (hold-job, release-job,
2376  etc.)</TD></TR>
2377 <TR><TD>/jobs/id</TD><TD>The resource for job <CODE>id</CODE></TD></TR>
2378 <TR><TD>/printers</TD><TD>The path for all printers</TD></TR>
2379 <TR><TD>/printers/name</TD><TD>The path for printer <CODE>name</CODE></TD>
2380 </TR>
2381 <TR><TD>/printers/name.ppd</TD><TD>The PPD file path for printer <CODE>
2382 name</CODE></TD></TR>
2383 </TABLE>
2384 </CENTER>
2385 </P>
2386 <P>Note that more specific resources override the less specific ones. So
2387  the directives inside the <CODE>/printers/name</CODE> location will
2388  override ones from <CODE>/printers</CODE>. Directives inside <CODE>
2389 /printers</CODE> will override ones from <CODE>/</CODE>. &nbsp; None of the
2390  directives are inherited. More information can be found in section<A HREF="#PRINTING_SECURITY">
2391  &quot;Printing System Security&quot;</A>.
2392 <!-- NEED 3in -->
2393 </P>
2394 <H3><A NAME="LogFilePerm">LogFilePerm</A></H3>
2395 <HR>
2396 <H4>Examples</H4>
2397 <UL>
2398 <PRE>
2399 LogFilePerm 0644
2400 LogFilePerm 0600
2401 </PRE>
2402 </UL>
2403 <H4>Description</H4>
2404 <P>The <CODE>LogFilePerm</CODE> directive specifies the permissions to
2405  use when writing configuration files. The default is 0644.
2406 <!-- NEED 3in -->
2407 </P>
2408 <H3><A NAME="LogLevel">LogLevel</A></H3>
2409 <HR>
2410 <H4>Examples</H4>
2411 <UL>
2412 <PRE>
2413 LogLevel none
2414 LogLevel emerg
2415 LogLevel alert
2416 LogLevel crit
2417 LogLevel error
2418 LogLevel warn
2419 LogLevel notice
2420 LogLevel info
2421 LogLevel debug
2422 LogLevel debug2
2423 </PRE>
2424 </UL>
2425 <H4>Description</H4>
2426 <P>The <CODE>LogLevel</CODE> directive specifies the level of logging
2427  for the<A HREF="#ErrorLog"> <CODE>ErrorLog</CODE></A> file. The
2428  following values are recognized (each level logs everything under the
2429  preceding levels):</P>
2430 <UL>
2431 <LI><CODE>none</CODE> - Log nothing.</LI>
2432 <LI><CODE>emerg</CODE> - Log emergency conditions that prevent the
2433  server from running.</LI>
2434 <LI><CODE>alert</CODE> - Log alerts that must be handled immediately.</LI>
2435 <LI><CODE>crit</CODE> - Log critical errors that don't prevent the
2436  server from running.</LI>
2437 <LI><CODE>error</CODE> - Log general errors.</LI>
2438 <LI><CODE>warn</CODE> - Log errors and warnings.</LI>
2439 <LI><CODE>notice</CODE> - Log temporary error conditions.</LI>
2440 <LI><CODE>info</CODE> - Log all requests and state changes (default).</LI>
2441 <LI><CODE>debug</CODE> - Log basic debugging information.</LI>
2442 <LI><CODE>debug2</CODE> - Log all debugging information.</LI>
2443 </UL>
2444
2445 <!-- NEED 3in -->
2446 <H3><A NAME="MaxClients">MaxClients</A></H3>
2447 <HR>
2448 <H4>Examples</H4>
2449 <UL>
2450 <PRE>
2451 MaxClients 100
2452 MaxClients 1024
2453 </PRE>
2454 </UL>
2455 <H4>Description</H4>
2456 <P>The <CODE>MaxClients</CODE> directive controls the maximum number of
2457  simultaneous clients that will be allowed by the server. The default is
2458  100 clients.</P>
2459 <CENTER>
2460 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
2461 <TR><TD><B> NOTE:</B>
2462 <P>Since each print job requires a file descriptor for the status pipe,
2463  the CUPS server internally limits the <CODE>MaxClients</CODE> value to
2464  1/3 of the available file descriptors to avoid possible problems when
2465  printing large numbers of jobs.</P>
2466 </TD></TR>
2467 </TABLE>
2468 </CENTER>
2469
2470 <!-- NEED 3in -->
2471 <H3><A NAME="MaxClientsPerHost">MaxClientsPerHost</A></H3>
2472 <HR>
2473 <H4>Examples</H4>
2474 <UL>
2475 <PRE>
2476 MaxClientsPerHost 0
2477 MaxClientsPerHost 10
2478 </PRE>
2479 </UL>
2480 <H4>Description</H4>
2481 <P>The <CODE>MaxClientsPerHost</CODE> directive controls the maximum
2482  number of simultaneous clients that will be allowed from a single host
2483  by the server. The default is 10 or 1/10th the <CODE>MaxClients</CODE>
2484  value, whichever is greater. A value of 0 uses the automatic setting
2485  based on the <CODE>MaxClients</CODE> value.</P>
2486 <P>This directive provides a small measure of protection against Denial
2487  of Service attacks from a single host.
2488 <!-- NEED 3in -->
2489 </P>
2490 <H3><A NAME="MaxCopies">MaxCopies</A></H3>
2491 <HR>
2492 <H4>Examples</H4>
2493 <UL>
2494 <PRE>
2495 MaxCopies 100
2496 MaxCopies 65535
2497 </PRE>
2498 </UL>
2499 <H4>Description</H4>
2500 <P>The <CODE>MaxCopies</CODE> directive controls the maximum number of
2501  copies that a user can print of a job. The default is 100 copies.</P>
2502 <CENTER>
2503 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
2504 <TR><TD><B> NOTE:</B>
2505 <P>Most HP PCL laser printers internally limit the number of copies to
2506  100.</P>
2507 </TD></TR>
2508 </TABLE>
2509 </CENTER>
2510
2511 <!-- NEED 3in -->
2512 <H3><A NAME="MaxJobs">MaxJobs</A></H3>
2513 <HR>
2514 <H4>Examples</H4>
2515 <UL>
2516 <PRE>
2517 MaxJobs 100
2518 MaxJobs 9999
2519 MaxJobs 0
2520 </PRE>
2521 </UL>
2522 <H4>Description</H4>
2523 <P>The <CODE>MaxJobs</CODE> directive controls the maximum number of
2524  jobs that are kept in memory. Once the number of jobs reaches the
2525  limit, the oldest completed job is automatically purged from the system
2526  to make room for the new one. If all of the known jobs are still
2527  pending or active then the new job will be rejected.</P>
2528 <P>Setting the maximum to 0 disables this functionality. The default
2529  setting is 0.
2530 <!-- NEED 3in -->
2531 </P>
2532 <H3><A NAME="MaxJobsPerPrinter">MaxJobsPerPrinter</A></H3>
2533 <HR>
2534 <H4>Examples</H4>
2535 <UL>
2536 <PRE>
2537 MaxJobsPerPrinter 100
2538 MaxJobsPerPrinter 9999
2539 MaxJobsPerPrinter 0
2540 </PRE>
2541 </UL>
2542 <H4>Description</H4>
2543 <P>The <CODE>MaxJobsPerPrinter</CODE> directive controls the maximum
2544  number of active jobs that are allowed for each printer or class. Once
2545  a printer or class reaches the limit, new jobs will be rejected until
2546  one of the active jobs is completed, stopped, aborted, or cancelled.</P>
2547 <P>Setting the maximum to 0 disables this functionality. The default
2548  setting is 0.
2549 <!-- NEED 3in -->
2550 </P>
2551 <H3><A NAME="MaxJobsPerUser">MaxJobsPerUser</A></H3>
2552 <HR>
2553 <H4>Examples</H4>
2554 <UL>
2555 <PRE>
2556 MaxJobsPerUser 100
2557 MaxJobsPerUser 9999
2558 MaxJobsPerUser 0
2559 </PRE>
2560 </UL>
2561 <H4>Description</H4>
2562 <P>The <CODE>MaxJobsPerUser</CODE> directive controls the maximum number
2563  of active jobs that are allowed for each user. Once a user reaches the
2564  limit, new jobs will be rejected until one of the active jobs is
2565  completed, stopped, aborted, or cancelled.</P>
2566 <P>Setting the maximum to 0 disables this functionality. The default
2567  setting is 0.
2568 <!-- NEED 3in -->
2569 </P>
2570 <H3><A NAME="MaxLogSize">MaxLogSize</A></H3>
2571 <HR>
2572 <H4>Examples</H4>
2573 <UL>
2574 <PRE>
2575 MaxLogSize 1048576
2576 MaxLogSize 1m
2577 MaxLogSize 0
2578 </PRE>
2579 </UL>
2580 <H4>Description</H4>
2581 <P>The <CODE>MaxLogSize</CODE> directive controls the maximum size of
2582  each log file. Once a log file reaches or exceeds the maximum size it
2583  is closed and renamed to<VAR> filename.O</VAR>. This allows you to
2584  rotate the logs automatically. The default size is 1048576 bytes (1MB).</P>
2585 <P>Setting the maximum size to 0 disables log rotation.
2586 <!-- NEED 3in -->
2587 </P>
2588 <H3><A NAME="MaxRequestSize">MaxRequestSize</A></H3>
2589 <HR>
2590 <H4>Examples</H4>
2591 <UL>
2592 <PRE>
2593 MaxRequestSize 10485760
2594 MaxRequestSize 10m
2595 MaxRequestSize 0
2596 </PRE>
2597 </UL>
2598 <H4>Description</H4>
2599 <P>The <CODE>MaxRequestSize</CODE> directive controls the maximum size
2600  of print files, IPP requests, and HTML form data in HTTP POST requests.
2601  The default limit is 0 which disables the limit check.</P>
2602 <P>Also see the identical<A HREF="#LimitRequestBody"> <CODE>
2603 LimitRequestBody</CODE></A> directive.
2604 <!-- NEED 3in -->
2605 </P>
2606 <H3><A NAME="Order">Order</A></H3>
2607 <HR>
2608 <H4>Examples</H4>
2609 <UL>
2610 <PRE>
2611 Order Allow,Deny
2612 Order Deny,Allow
2613 </PRE>
2614 </UL>
2615 <H4>Description</H4>
2616 <P>The <CODE>Order</CODE> directive defines the default access control.
2617  The following values are supported:</P>
2618 <UL>
2619 <LI><CODE>Allow,Deny</CODE> - Allow requests from all systems<I> except</I>
2620  for those listed in a <CODE>Deny</CODE> directive.</LI>
2621 <LI><CODE>Deny,Allow</CODE> - Allow requests only from those listed in
2622  an <CODE>Allow</CODE> directive.</LI>
2623 </UL>
2624 <P>The <CODE>Order</CODE> directive must appear inside a<A HREF="#Location">
2625  <CODE>Location</CODE></A> directive.
2626 <!-- NEED 3in -->
2627 </P>
2628 <H3><A NAME="PageLog">PageLog</A></H3>
2629 <HR>
2630 <H4>Examples</H4>
2631 <UL>
2632 <PRE>
2633 PageLog /var/log/cups/page_log
2634 PageLog /var/log/cups/page_log-%s
2635 PageLog syslog
2636 </PRE>
2637 </UL>
2638 <H4>Description</H4>
2639 <P>The <CODE>PageLog</CODE> directive sets the name of the page log
2640  file. If the filename is not absolute then it is assumed to be relative
2641  to the<A HREF="#ServerRoot"> <CODE>ServerRoot</CODE></A> directory. The
2642  default page log file is<VAR> /var/log/cups/page_log</VAR>.</P>
2643 <P>The server name can be included in the filename by using <CODE>%s</CODE>
2644  in the name.</P>
2645 <P>The special name &quot;syslog&quot; can be used to send the page information to
2646  the system log instead of a plain file.
2647 <!-- NEED 3in -->
2648 </P>
2649 <H3><A NAME="Port">Port</A></H3>
2650 <HR>
2651 <H4>Examples</H4>
2652 <UL>
2653 <PRE>
2654 Port 631
2655 Port 80
2656 </PRE>
2657 </UL>
2658 <H4>Description</H4>
2659 <P>The <CODE>Port</CODE> directive specifies a port to listen on.
2660  Multiple <CODE>Port</CODE> lines can be specified to listen on multiple
2661  ports. The default port is 631.
2662 <!-- NEED 3in -->
2663 </P>
2664 <H3><A NAME="PreserveJobHistory">PreserveJobHistory</A></H3>
2665 <HR>
2666 <H4>Examples</H4>
2667 <UL>
2668 <PRE>
2669 PreserveJobHistory On
2670 PreserveJobHistory Off
2671 </PRE>
2672 </UL>
2673 <H4>Description</H4>
2674 <P>The <CODE>PreserveJobHistory</CODE> directive controls whether the
2675  history of completed, cancelled, or aborted print jobs is stored on
2676  disk.</P>
2677 <P>A value of <CODE>On</CODE> (the default) preserves job information
2678  until the administrator purges it with the <CODE>cancel</CODE> command.</P>
2679 <P>A value of <CODE>Off</CODE> removes the job information as soon as
2680  each job is completed, cancelled, or aborted.
2681 <!-- NEED 3in -->
2682 </P>
2683 <H3><A NAME="PreserveJobFiles">PreserveJobFiles</A></H3>
2684 <HR>
2685 <H4>Examples</H4>
2686 <UL>
2687 <PRE>
2688 PreserveJobFiles On
2689 PreserveJobFiles Off
2690 </PRE>
2691 </UL>
2692 <H4>Description</H4>
2693 <P>The <CODE>PreserveJobFiles</CODE> directive controls whether the
2694  document files of completed, cancelled, or aborted print jobs are
2695  stored on disk.</P>
2696 <P>A value of <CODE>On</CODE> preserves job files until the
2697  administrator purges them with the <CODE>cancel</CODE> command. Jobs
2698  can be restarted (and reprinted) as desired until they are purged.</P>
2699 <P>A value of <CODE>Off</CODE> (the default) removes the job files as
2700  soon as each job is completed, cancelled, or aborted.
2701 <!-- NEED 3in -->
2702 </P>
2703 <H3><A NAME="Printcap">Printcap</A></H3>
2704 <HR>
2705 <H4>Examples</H4>
2706 <UL>
2707 <PRE>
2708 Printcap
2709 Printcap /etc/printcap
2710 Printcap /etc/printers.conf
2711 </PRE>
2712 </UL>
2713 <H4>Description</H4>
2714 <P>The <CODE>Printcap</CODE> directive controls whether or not a
2715  printcap file is automatically generated and updated with a list of
2716  available printers. If specified with no value, then no printcap file
2717  will be generated. The default is to generate a file named<VAR>
2718  /etc/printcap</VAR>.</P>
2719 <P>When a filename is specified (e.g.<VAR> /etc/printcap</VAR>), the
2720  printcap file is written whenever a printer is added or removed. The
2721  printcap file can then be used by applications that are hardcoded to
2722  look at the printcap file for the available printers.
2723 <!-- NEED 3in -->
2724 </P>
2725 <H3><A NAME="PrintcapFormat">PrintcapFormat</A></H3>
2726 <HR>
2727 <H4>Examples</H4>
2728 <UL>
2729 <PRE>
2730 PrintcapFormat BSD
2731 PrintcapFormat Solaris
2732 </PRE>
2733 </UL>
2734 <H4>Description</H4>
2735 <P>The <CODE>PrintcapFormat</CODE> directive controls the output format
2736  of the printcap file. The default is to generate a BSD printcap file.
2737 <!-- NEED 3in -->
2738 </P>
2739 <H3><A NAME="PrintcapGUI">PrintcapGUI</A></H3>
2740 <HR>
2741 <H4>Example</H4>
2742 <UL>
2743 <PRE>
2744 PrintcapGUI /usr/bin/glpoptions
2745 </PRE>
2746 </UL>
2747 <H4>Description</H4>
2748 <P>The <CODE>PrintcapGUI</CODE> directive sets the program to use when
2749  displaying an option panel from an IRIX application that uses the
2750  Impressario print API. The default program is the ESP Print Pro
2751  &quot;glpoptions&quot; GUI.</P>
2752 <P>The program must accept the <CODE>-d</CODE> option to specify a
2753  printer and the <CODE>-o</CODE> option to specify one or more options.
2754  After allowing the user to select/change options, the program must then
2755  write the list of printing options without the <CODE>-o</CODE> to the
2756  standard output.
2757 <!-- NEED 3in -->
2758 </P>
2759 <H3><A NAME="RemoteRoot">RemoteRoot</A></H3>
2760 <HR>
2761 <H4>Examples</H4>
2762 <UL>
2763 <PRE>
2764 RemoteRoot remroot
2765 RemoteRoot root
2766 </PRE>
2767 </UL>
2768 <H4>Description</H4>
2769 <P>The <CODE>RemoteRoot</CODE> directive sets the username for
2770  unauthenticated root requests from remote hosts. The default username
2771  is<VAR> remroot</VAR>. Setting <CODE>RemoteRoot</CODE> to<VAR> root</VAR>
2772  effectively disables this security mechanism.
2773 <!-- NEED 3in -->
2774 </P>
2775 <H3><A NAME="RequestRoot">RequestRoot</A></H3>
2776 <HR>
2777 <H4>Examples</H4>
2778 <UL>
2779 <PRE>
2780 RequestRoot /var/spool/cups
2781 RequestRoot /foo/bar/spool/cups
2782 </PRE>
2783 </UL>
2784 <H4>Description</H4>
2785 <P>The <CODE>RequestRoot</CODE> directive sets the directory for
2786  incoming IPP requests and HTML forms. If an absolute path is not
2787  provided then it is assumed to be relative to the<A HREF="#ServerRoot">
2788  <CODE>ServerRoot</CODE></A> directory. The default request directory is<VAR>
2789  /var/spool/cups</VAR>.
2790 <!-- NEED 4in -->
2791 </P>
2792 <H3><A NAME="Require">Require</A></H3>
2793 <HR>
2794 <H4>Examples</H4>
2795 <UL>
2796 <PRE>
2797 Require group foo bar
2798 Require user john mary
2799 Require valid-user
2800 </PRE>
2801 </UL>
2802 <H4>Description</H4>
2803 <P>The <CODE>Require</CODE> directive specifies that authentication is
2804  required for the resource. The <CODE>group</CODE> keyword specifies
2805  that the authenticated user must be a member of one or more of the
2806  named groups that follow.</P>
2807 <P>The <CODE>user</CODE> keyboard specifies that the authenticated user
2808  must be one of the named users that follow.</P>
2809 <P>The <CODE>valid-user</CODE> keyword specifies that any authenticated
2810  user may access the resource.</P>
2811 <P>The default is to do no authentication. This directive must appear
2812  inside a<A HREF="#Location"> <CODE>Location</CODE></A> directive.
2813 <!-- NEED 3in -->
2814 </P>
2815 <H3><A NAME="RIPCache">RIPCache</A></H3>
2816 <HR>
2817 <H4>Examples</H4>
2818 <UL>
2819 <PRE>
2820 RIPCache 8m
2821 RIPCache 1g
2822 RIPCache 2048k
2823 </PRE>
2824 </UL>
2825 <H4>Description</H4>
2826 <P>The <CODE>RIPCache</CODE> directive sets the size of the memory cache
2827  used by Raster Image Processor (&quot;RIP&quot;) filters such as <CODE>
2828 imagetoraster</CODE> and <CODE>pstoraster</CODE>. The size can be
2829  suffixed with a &quot;k&quot; for kilobytes, &quot;m&quot; for megabytes, or &quot;g&quot; for
2830  gigabytes. The default cache size is &quot;8m&quot;, or 8 megabytes.
2831 <!-- NEED 3in -->
2832 </P>
2833 <H3><A NAME="RootCertDuration">RootCertDuration</A></H3>
2834 <HR>
2835 <H4>Examples</H4>
2836 <UL>
2837 <PRE>
2838 RootCertDuration 300
2839 RootCertDuration 0
2840 </PRE>
2841 </UL>
2842 <H4>Description</H4>
2843 <P>The <CODE>RootCertDuration</CODE> directive controls the interval
2844  between updates of the root authentication certificate. The default is <CODE>
2845 300</CODE> seconds which updates the root certificate approximately once
2846  every 5 minutes. Set the interval to 0 to disable certificate updates
2847  entirely.
2848 <!-- NEED 3in -->
2849 </P>
2850 <H3><A NAME="RunAsUser">RunAsUser</A></H3>
2851 <HR>
2852 <H4>Examples</H4>
2853 <UL>
2854 <PRE>
2855 RunAsUser Yes
2856 RunAsUser No
2857 </PRE>
2858 </UL>
2859 <H4>Description</H4>
2860 <P>The <CODE>RunAsUser</CODE> directive controls whether the scheduler
2861  runs as the unpriviledged user account (usually <CODE>lp</CODE>). The
2862  default is <CODE>No</CODE> which leaves the scheduler running as the <CODE>
2863 root</CODE> user.</P>
2864 <P><B>Note:</B> Running as a non-priviledged user may prevent LPD and
2865  locally connected printers from working due to permission problems. The
2866  <CODE>lpd</CODE> backend will automatically use a non-priviledged mode
2867  that is not 100% compliant with RFC 1179. The <CODE>parallel</CODE>, <CODE>
2868 serial</CODE>, and <CODE>usb</CODE> backends will need write access to
2869  the corresponding device files.
2870 <!-- NEED 3in -->
2871 </P>
2872 <H3><A NAME="Satisfy">Satisfy</A></H3>
2873 <HR>
2874 <H4>Examples</H4>
2875 <UL>
2876 <PRE>
2877 Satisfy all
2878 Satisfy any
2879 </PRE>
2880 </UL>
2881 <H4>Description</H4>
2882 <P>The <CODE>Satisfy</CODE> directive specifies whether all conditions
2883  must be satisfied to allow access to the resource. If set to <CODE>all</CODE>
2884 , then all authentication and access control conditions must be satified
2885  to allow access.</P>
2886 <P>Setting <CODE>Satisfy</CODE> to <CODE>any</CODE> allows a user to
2887  gain access if the authentication or access control requirements are
2888  satisfied. For example, you might require authentication for remote
2889  access, but allow local access without authentication.</P>
2890 <P>The default is <CODE>all</CODE>. This directive must appear inside a<A
2891 HREF="#Location"> <CODE>Location</CODE></A> directive.
2892 <!-- NEED 3in -->
2893 </P>
2894 <H3><A NAME="ServerAdmin">ServerAdmin</A></H3>
2895 <HR>
2896 <H4>Examples</H4>
2897 <UL>
2898 <PRE>
2899 ServerAdmin user@host
2900 ServerAdmin root@foo.bar.com
2901 </PRE>
2902 </UL>
2903 <H4>Description</H4>
2904 <P>The <CODE>ServerAdmin</CODE> directive identifies the email address
2905  for the administrator on the system. By default the administrator email
2906  address is <CODE>root@server</CODE>, where <CODE>server</CODE> is the
2907  server name.
2908 <!-- NEED 3in -->
2909 </P>
2910 <H3><A NAME="ServerBin">ServerBin</A></H3>
2911 <HR>
2912 <H4>Examples</H4>
2913 <UL>
2914 <PRE>
2915 ServerBin /usr/lib/cups
2916 ServerBin /foo/bar/lib/cups
2917 </PRE>
2918 </UL>
2919 <H4>Description</H4>
2920 <P>The <CODE>ServerBin</CODE> directive sets the directory for
2921  server-run executables. If an absolute path is not provided then it is
2922  assumed to be relative to the<A HREF="#ServerRoot"> <CODE>ServerRoot</CODE>
2923 </A> directory. The default executable directory is<VAR> /usr/lib/cups</VAR>
2924 .
2925 <!-- NEED 3in -->
2926 </P>
2927 <H3><A NAME="ServerCertificate">ServerCertificate</A></H3>
2928 <HR>
2929 <H4>Examples</H4>
2930 <UL>
2931 <PRE>
2932 ServerCertificate /etc/cups/ssl/server.crt
2933 </PRE>
2934 </UL>
2935 <H4>Description</H4>
2936 <P>The <CODE>ServerCertificate</CODE> directive specifies the location
2937  of the SSL certificate file used by the server when negotiating
2938  encrypted connections. The certificate must not be encrypted (password
2939  protected) since the scheduler normally runs in the background and will
2940  be unable to ask for a password. The default certificate file is<VAR>
2941  /etc/cups/ssl/server.crt</VAR>.
2942 <!-- NEED 3in -->
2943 </P>
2944 <H3><A NAME="ServerKey">ServerKey</A></H3>
2945 <HR>
2946 <H4>Examples</H4>
2947 <UL>
2948 <PRE>
2949 ServerKey /etc/cups/ssl/server.key
2950 </PRE>
2951 </UL>
2952 <H4>Description</H4>
2953 <P>The <CODE>ServerKey</CODE> directive specifies the location of the
2954  SSL private key file used by the server when negotiating encrypted
2955  connections. The default key file is<VAR> /etc/cups/ssl/server.crt</VAR>
2956 .
2957 <!-- NEED 3in -->
2958 </P>
2959 <H3><A NAME="ServerName"></A>ServerName</H3>
2960 <HR>
2961 <H4>Examples</H4>
2962 <UL>
2963 <PRE>
2964 ServerName foo.domain.com
2965 ServerName myserver.domain.com
2966 </PRE>
2967 </UL>
2968 <H4>Description</H4>
2969 <P>The <CODE>ServerName</CODE> directive specifies the hostname that is
2970  reported to clients. By default the server name is the hostname.
2971 <!-- NEED 3in -->
2972 </P>
2973 <H3><A NAME="ServerRoot">ServerRoot</A></H3>
2974 <HR>
2975 <H4>Examples</H4>
2976 <UL>
2977 <PRE>
2978 ServerRoot /etc/cups
2979 ServerRoot /foo/bar/cups
2980 </PRE>
2981 </UL>
2982 <H4>Description</H4>
2983 <P>The <CODE>ServerRoot</CODE> directive specifies the absolute path to
2984  the server configuration and state files. It is also used to resolve
2985  relative paths in the<VAR> cupsd.conf</VAR> file. The default server
2986  directory is<VAR> /etc/cups</VAR>.
2987 <!-- NEED 3in -->
2988 </P>
2989 <H3><A NAME="SSLListen">SSLListen</A></H3>
2990 <HR>
2991 <H4>Examples</H4>
2992 <UL>
2993 <PRE>
2994 SSLListen 127.0.0.1:443
2995 SSLListen 192.0.2.1:443
2996 </PRE>
2997 </UL>
2998 <H4>Description</H4>
2999 <P>The <CODE>SSLListen</CODE> directive specifies a network address and
3000  port to listen for secure connections. Multiple <CODE>SSLListen</CODE>
3001  directives can be provided to listen on multiple addresses.</P>
3002 <P>The <CODE>SSLListen</CODE> directive is similar to the<A HREF="#SSLPort">
3003  <CODE>SSLPort</CODE></A> directive but allows you to restrict access to
3004  specific interfaces or networks.
3005 <!-- NEED 3in -->
3006 </P>
3007 <H3><A NAME="SSLPort">SSLPort</A></H3>
3008 <HR>
3009 <H4>Examples</H4>
3010 <UL>
3011 <PRE>
3012 SSLPort 443
3013 </PRE>
3014 </UL>
3015 <H4>Description</H4>
3016 <P>The <CODE>SSLPort</CODE> directive specifies a port to listen on for
3017  secure connections. Multiple <CODE>SSLPort</CODE> lines can be
3018  specified to listen on multiple ports.
3019 <!-- NEED 3in -->
3020 </P>
3021 <H3><A NAME="SystemGroup">SystemGroup</A></H3>
3022 <HR>
3023 <H4>Examples</H4>
3024 <UL>
3025 <PRE>
3026 SystemGroup sys
3027 SystemGroup system
3028 SystemGroup root
3029 </PRE>
3030 </UL>
3031 <H4>Description</H4>
3032 <P>The <CODE>SystemGroup</CODE> directive specifies the system
3033  administration group for <CODE>System</CODE> authentication. More
3034  information can be found later in this chapter in<A HREF="#PRINTING_SECURITY">
3035  &quot;Printing System Security&quot;</A>.
3036 <!-- NEED 3in -->
3037 </P>
3038 <H3><A NAME="TempDir">TempDir</A></H3>
3039 <HR>
3040 <H4>Examples</H4>
3041 <UL>
3042 <PRE>
3043 TempDir /var/tmp
3044 TempDir /foo/bar/tmp
3045 </PRE>
3046 </UL>
3047 <H4>Description</H4>
3048 <P>The <CODE>TempDir</CODE> directive specifies an absolute path for the
3049  directory to use for temporary files. The default directory is<VAR>
3050  /var/tmp</VAR>.</P>
3051 <P>Temporary directories must be world-writable and should have the
3052  &quot;sticky&quot; permission bit enabled so that other users cannot delete
3053  filter temporary files. The following commands will create an
3054  appropriate temporary directory called<VAR> /foo/bar/tmp</VAR>:</P>
3055 <UL>
3056 <PRE>
3057 <B>mkdir /foo/bar/tmp ENTER</B>
3058 <B>chmod a+rwxt /foo/bar/tmp ENTER</B>
3059 </PRE>
3060 </UL>
3061
3062 <!-- NEED 3in -->
3063 <H3><A NAME="Timeout">Timeout</A></H3>
3064 <HR>
3065 <H4>Examples</H4>
3066 <UL>
3067 <PRE>
3068 Timeout 300
3069 Timeout 90
3070 </PRE>
3071 </UL>
3072 <H4>Description</H4>
3073 <P>The <CODE>Timeout</CODE> directive controls the amount of time to
3074  wait before an active HTTP or IPP request times out. The default
3075  timeout is 300 seconds.
3076 <!-- NEED 3in -->
3077 </P>
3078 <H3><A NAME="User">User</A></H3>
3079 <HR>
3080 <H4>Examples</H4>
3081 <UL>
3082 <PRE>
3083 User lp
3084 User guest
3085 </PRE>
3086 </UL>
3087 <H4>Description</H4>
3088 <P>The <CODE>User</CODE> directive specifies the UNIX user that filter
3089  and CGI programs run as. The default user is <CODE>lp</CODE>.</P>
3090 <H2><A NAME="7_5">Changing the Client Configuration</A></H2>
3091 <P>The CUPS client application (<CODE>lp</CODE>, <CODE>lpr</CODE>, and
3092  so forth) use the<VAR> /etc/cups/client.conf</VAR> file for default
3093  settings. The client application also look in the user's home directory
3094  for a file called<VAR> .cupsrc</VAR>. Each directive is listed on a
3095  line by itself followed by its value. Comments are introduced using the
3096  number sign (&quot;#&quot;) character at the beginning of a line.</P>
3097 <P>Since the client configuration file consists of plain text, you can
3098  use your favorite text editor to make changes to it.
3099 <!-- NEED 4in -->
3100 </P>
3101 <H2><A NAME="7_6">Client Directives</A></H2>
3102 <P>The<VAR> client.conf</VAR> file contains many directives that
3103  determine how the client behaves:</P>
3104 <UL>
3105 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0">
3106 <TR><TD VALIGN="TOP">
3107 <LI><A HREF="#Encryption"><CODE>Encryption</CODE></A></LI>
3108 <LI><A HREF="#ServerName"><CODE>ServerName</CODE></A></LI>
3109 </TD></TR>
3110 </TABLE>
3111 </UL>
3112
3113 <!-- NEED 3in -->
3114 <H3><A NAME="Encryption">Encryption</A></H3>
3115 <HR>
3116 <H4>Examples</H4>
3117 <UL>
3118 <PRE>
3119 Encryption Never
3120 Encryption IfRequested
3121 Encryption Required
3122 Encryption Always
3123 </PRE>
3124 </UL>
3125 <H4>Description</H4>
3126 <P>The <CODE>Encryption</CODE> directive specifies the default
3127  encryption settings for the client. The default setting is<VAR>
3128  IfRequested</VAR>.
3129 <!-- NEED 3in -->
3130 </P>
3131 <H3><A NAME="ServerName">ServerName</A></H3>
3132 <HR>
3133 <H4>Examples</H4>
3134 <UL>
3135 <PRE>
3136 ServerName foo.bar.com
3137 ServerName 11.22.33.44
3138 </PRE>
3139 </UL>
3140 <H4>Description</H4>
3141 <P>The <CODE>ServerName</CODE> directive specifies sets the remote
3142  server that is to be used for all client operations. That is, it
3143  redirects all client requests to the remote server. The default is to
3144  use the local server (&quot;<VAR>localhost</VAR>&quot;).</P>
3145 <H2><A NAME="7_7">Changing the Printer Configuration</A></H2>
3146 <P>The CUPS scheduler (cupsd) uses the<VAR> /etc/cups/printers.conf</VAR>
3147  file to store the list of available printers. This file contains only
3148  locally defined printers, but not remote printers that are created
3149  automatically. Each directive is listed on a line by itself followed by
3150  its value. Comments are introduced using the number sign (&quot;#&quot;)
3151  character at the beginning of a line.</P>
3152 <P>Since the printer configuration file consists of plain text, you can
3153  use your favorite text editor to make changes to it.
3154 <!-- NEED 4in -->
3155 </P>
3156 <H2><A NAME="7_8">Printer Directives</A></H2>
3157 <P>The<VAR> printers.conf</VAR> file contains many directives that
3158  determine how the printer behaves:</P>
3159 <UL>
3160 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0">
3161 <TR><TD VALIGN="TOP">
3162 <LI><A HREF="#Accepting"><CODE>Accepting</CODE></A></LI>
3163 <LI><A HREF="#AllowUser"><CODE>AllowUser</CODE></A></LI>
3164 <LI><A HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A></LI>
3165 <LI><A HREF="#DenyUser"><CODE>DenyUser</CODE></A></LI>
3166 <LI><A HREF="#DeviceURI"><CODE>DeviceURI</CODE></A></LI>
3167 </TD><TD VALIGN="TOP"> &nbsp;&nbsp;&nbsp;</TD><TD VALIGN="TOP">
3168 <LI><A HREF="#Info"><CODE>Info</CODE></A></LI>
3169 <LI><A HREF="#JobSheets"><CODE>JobSheets</CODE></A></LI>
3170 <LI><A HREF="#KLimit"><CODE>KLimit</CODE></A></LI>
3171 <LI><A HREF="#PrinterLocation"><CODE>Location</CODE></A></LI>
3172 <LI><A HREF="#PageLimit"><CODE>PageLimit</CODE></A></LI>
3173 </TD><TD VALIGN="TOP"> &nbsp;&nbsp;&nbsp;</TD><TD VALIGN="TOP">
3174 <LI><A HREF="#Printer"><CODE>Printer</CODE></A></LI>
3175 <LI><A HREF="#QuotaPeriod"><CODE>QuotaPeriod</CODE></A></LI>
3176 <LI><A HREF="#State"><CODE>State</CODE></A></LI>
3177 <LI><A HREF="#StateMessage"><CODE>StateMessage</CODE></A></LI>
3178 </TD></TR>
3179 </TABLE>
3180 </UL>
3181
3182 <!-- NEED 3in -->
3183 <H3><A NAME="Accepting">Accepting</A></H3>
3184 <HR>
3185 <H4>Examples</H4>
3186 <UL>
3187 <PRE>
3188 Accepting yes
3189
3190 Accepting no
3191 </PRE>
3192 </UL>
3193 <H4>Description</H4>
3194 <P>The <CODE>Accepting</CODE> directive defines the initial Boolean
3195  value for the<VAR> printer-is-accepting-job</VAR> attribute which can
3196  be set by the <CODE>accept</CODE> and <CODE>reject</CODE> commands.</P>
3197 <P>This directive must appear inside a<A HREF="#Printer"> <CODE>Printer</CODE>
3198 </A> or<A HREF="#DefaultPrinter"> <CODE>DefaultPrinter</CODE></A>
3199  directive.
3200 <!-- NEED 3in -->
3201 </P>
3202 <H3><A NAME="AllowUser">AllowUser</A></H3>
3203 <HR>
3204 <H4>Examples</H4>
3205 <UL>
3206 <PRE>
3207 AllowUser foo_user
3208 AllowUser bar_user
3209 </PRE>
3210 </UL>
3211 <H4>Description</H4>
3212 <P>The <CODE>AllowUser</CODE> directive adds a username to the<VAR>
3213  requesting-user-name-allowed</VAR> attribute which can be set by the <CODE>
3214 lpadmin -u</CODE> command.</P>
3215 <P>This directive must appear inside a<A HREF="#Printer"> <CODE>Printer</CODE>
3216 </A> or<A HREF="#DefaultPrinter"> <CODE>DefaultPrinter</CODE></A>
3217  directive.
3218 <!-- NEED 3in -->
3219 </P>
3220 <H3><A NAME="DefaultPrinter">DefaultPrinter</A></H3>
3221 <HR>
3222 <H4>Examples</H4>
3223 <UL>
3224 <PRE>
3225 &lt;DefaultPrinter name/&gt;
3226 ...
3227 &lt;/Printer&gt;
3228 </PRE>
3229 </UL>
3230 <H4>Description</H4>
3231 <P>The <CODE>DefaultPrinter</CODE> directive begins a printer definition
3232  for the default server destination. It can be added by the <CODE>
3233 lpadmin</CODE> command or if already defined, set as default by the <CODE>
3234 lpoptions -d</CODE> command.</P>
3235
3236 <!-- NEED 3in -->
3237 <H3><A NAME="DenyUser">DenyUser</A></H3>
3238 <HR>
3239 <H4>Examples</H4>
3240 <UL>
3241 <PRE>
3242 DenyUser foo_user
3243 DenyUser bar_user
3244 </PRE>
3245 </UL>
3246 <H4>Description</H4>
3247 <P>The <CODE>DenyUser</CODE> directive adds a username to the<VAR>
3248  requesting-user-name-allowed</VAR> attribute which can be set by the <CODE>
3249 lpadmin -u</CODE> command.</P>
3250 <P>This directive must appear inside a<A HREF="#Printer"> <CODE>Printer</CODE>
3251 </A> or<A HREF="#DefaultPrinter"> <CODE>DefaultPrinter</CODE></A>
3252  directive.</P>
3253
3254 <!-- NEED 3in -->
3255 <H3><A NAME="DeviceURI">DeviceURI</A></H3>
3256 <HR>
3257 <H4>Examples</H4>
3258 <UL>
3259 <PRE>
3260 DeviceURI socket://foo.bar.com:9100
3261 </PRE>
3262 </UL>
3263 <H4>Description</H4>
3264 <P>The <CODE>DeviceURI</CODE> directive defines the value of the<VAR>
3265  device-uri-attribute</VAR> attribute which can be set by the <CODE>
3266 lpadmin -v</CODE> command.</P>
3267 <P>This directive must appear inside a<A HREF="#Printer"> <CODE>Printer</CODE>
3268 </A> or<A HREF="#DefaultPrinter"> <CODE>DefaultPrinter</CODE></A>
3269  directive.
3270 <!-- NEED 3in -->
3271 </P>
3272 <H3><A NAME="Info">Info</A></H3>
3273 <HR>
3274 <H4>Examples</H4>
3275 <UL>
3276 <PRE>
3277 Info My Printer
3278 </PRE>
3279 </UL>
3280 <H4>Description</H4>
3281 <P>The <CODE>Info</CODE> directive defines the string for the<VAR>
3282  printer-info</VAR> attribute which can be set by the <CODE>lpadmin -D</CODE>
3283  command.</P>
3284 <P>This directive must appear inside a<A HREF="#Printer"> <CODE>Printer</CODE>
3285 </A> or<A HREF="#DefaultPrinter"> <CODE>DefaultPrinter</CODE></A>
3286  directive.</P>
3287
3288 <!-- NEED 6in -->
3289 <H3><A NAME="JobSheets">JobSheets</A></H3>
3290 <HR>
3291 <H4>Examples</H4>
3292 <UL>
3293 <PRE>
3294 JobSheets none,standard
3295 </PRE>
3296 </UL>
3297 <H4>Description</H4>
3298 <P>The <CODE>JobSheets</CODE> directive specifies the default banner
3299  pages to print before and after a print job. In the above example, only
3300  a<VAR> standard</VAR> banner will print after each job.</P>
3301 <P>The <CODE>lpoptions -o job-sheets=</CODE> command can be used to set
3302  banners. For example, the following command would produce the same
3303  results of a<VAR> standard</VAR> banner at the end of each print job
3304  for the default printer.</P>
3305 <UL><B> lpoptions -o job-sheets=none,standard</B></UL>
3306 <P>If only one banner file is specified, it will be printed before the
3307  files in the job. If a second banner file is specified, it is printed
3308  after the files in the job.</P>
3309 <P>The available banner pages depend on the local system configuration;
3310  CUPS includes the following banner files:</P>
3311 <UL>
3312 <LI><CODE>none</CODE> - Do not produce a banner page.</LI>
3313 <LI><CODE>classified</CODE> - A banner page with a &quot;classified&quot; label at
3314  the top and bottom.</LI>
3315 <LI><CODE>confidential</CODE> - A banner page with a &quot;confidential&quot;
3316  label at the top and bottom.</LI>
3317 <LI><CODE>secret</CODE> - A banner page with a &quot;secret&quot; label at the top
3318  and bottom.</LI>
3319 <LI><CODE>standard</CODE> - A banner page with no label at the top and
3320  bottom.</LI>
3321 <LI><CODE>topsecret</CODE> - A banner page with a &quot;top secret&quot; label at
3322  the top and bottom.</LI>
3323 <LI><CODE>unclassified</CODE> - A banner page with an &quot;unclassified&quot;
3324  label at the top and bottom.</LI>
3325 </UL>
3326 <P>This directive must appear inside a<A HREF="#Printer"> <CODE>Printer</CODE>
3327 </A> or<A HREF="#DefaultPrinter"> <CODE>DefaultPrinter</CODE></A>
3328  directive.
3329 <!-- NEED 3in -->
3330 </P>
3331 <H3><A NAME="KLimit">KLimit</A></H3>
3332 <HR>
3333 <H4>Examples</H4>
3334 <UL>
3335 <PRE>
3336 KLimit 1234
3337 </PRE>
3338 </UL>
3339 <H4>Description</H4>
3340 <P>The <CODE>KLimit</CODE> directive defines the value of the<VAR>
3341  job-k-limit</VAR> attribute which can be set by the <CODE>lpadmin -o
3342  job-k-limit=</CODE> command.</P>
3343 <P>This directive must appear inside a<A HREF="#Printer"> <CODE>Printer</CODE>
3344 </A> or<A HREF="#DefaultPrinter"> <CODE>DefaultPrinter</CODE></A>
3345  directive.</P>
3346
3347 <!-- NEED 6in -->
3348 <H3><A NAME="PrinterLocation">Location</A></H3>
3349 <HR>
3350 <H4>Examples</H4>
3351 <UL>
3352 <PRE>
3353 Location Building 3321
3354 </PRE>
3355 </UL>
3356 <H4>Description</H4>
3357 <P>The <CODE>Location</CODE> directive defines the string for the<VAR>
3358  printer-location</VAR> attribute which can be set by the <CODE>lpadmin
3359  -L</CODE> command.</P>
3360 <CENTER>
3361 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
3362 <TR><TD><B> NOTE:</B>
3363 <P>Do not confuse this <CODE>Location</CODE> directive with the one for
3364  cupsd.conf. They are completely different.</P>
3365 </TD></TR>
3366 </TABLE>
3367 </CENTER>
3368 <P>This directive must appear inside a<A HREF="#Printer"> <CODE>Printer</CODE>
3369 </A> or<A HREF="#DefaultPrinter"> <CODE>DefaultPrinter</CODE></A>
3370  directive.</P>
3371
3372 <!-- NEED 3in -->
3373 <H3><A NAME="PageLimit">PageLimit</A></H3>
3374 <HR>
3375 <H4>Examples</H4>
3376 <UL>
3377 <PRE>
3378 PageLimit 1234
3379 </PRE>
3380 </UL>
3381 <H4>Description</H4>
3382 <P>The <CODE>PageLimit</CODE> directive defines the value of the<VAR>
3383  job-page-limit</VAR> attribute which can be set by the <CODE>lpadmin -o
3384  job-page-limit=</CODE> command.</P>
3385 <P>This directive must appear inside a<A HREF="#Printer"> <CODE>Printer</CODE>
3386 </A> or<A HREF="#DefaultPrinter"> <CODE>DefaultPrinter</CODE></A>
3387  directive.</P>
3388
3389 <!-- NEED 3in -->
3390 <H3><A NAME="Printer">Printer</A></H3>
3391 <HR>
3392 <H4>Examples</H4>
3393 <UL>
3394 <PRE>
3395 &lt;Printer name/&gt;
3396 ...
3397 &lt;/Printer&gt;
3398 </PRE>
3399 </UL>
3400 <H4>Description</H4>
3401 <P>The <CODE>Printer</CODE> directive begins a printer definition. It
3402  can be added by the <CODE>lpadmin</CODE> command.
3403 <!-- NEED 3in -->
3404 </P>
3405 <H3><A NAME="QuotaPeriod">QuotaPeriod</A></H3>
3406 <HR>
3407 <H4>Examples</H4>
3408 <UL>
3409 <PRE>
3410 QuotaPeriod 604800
3411 </PRE>
3412 </UL>
3413 <H4>Description</H4>
3414 <P>The <CODE>QuotaPeriod</CODE> directive defines the value of the<VAR>
3415  job-quota-period</VAR> attribute which can be set by the <CODE>lpadmin
3416  -o job-quota-period=</CODE> command.</P>
3417 <P>This directive must appear inside a<A HREF="#Printer"> <CODE>Printer</CODE>
3418 </A> or<A HREF="#DefaultPrinter"> <CODE>DefaultPrinter</CODE></A>
3419  directive.</P>
3420
3421 <!-- NEED 3in -->
3422 <H3><A NAME="State">State</A></H3>
3423 <HR>
3424 <H4>Examples</H4>
3425 <UL>
3426 <PRE>
3427 State stopped
3428 </PRE>
3429 </UL>
3430 <H4>Description</H4>
3431 <P>The <CODE>State</CODE> directive defines the initial value of the<VAR>
3432  printer-state</VAR> attribute. The strings<VAR> idle</VAR> and<VAR>
3433  stopped</VAR> correspond to the IPP enumeration values.</P>
3434 <P>This directive must appear inside a<A HREF="#Printer"> <CODE>Printer</CODE>
3435 </A> or<A HREF="#DefaultPrinter"> <CODE>DefaultPrinter</CODE></A>
3436  directive.</P>
3437
3438 <!-- NEED 6in -->
3439 <H3><A NAME="StateMessage">StateMessage</A></H3>
3440 <HR>
3441 <H4>Examples</H4>
3442 <UL>
3443 <PRE>
3444 StateMessage Ready to print.
3445 </PRE>
3446 </UL>
3447 <H4>Description</H4>
3448 <P>The <CODE>StateMessage</CODE> directive defines the initial string
3449  for the<VAR> printer-state-message</VAR> attribute. The following are
3450  some example messages:</P>
3451 <UL>
3452 <LI>Connected to<VAR> host_name</VAR>...</LI>
3453 <LI>Connecting to<VAR> printer_queue</VAR> on port<VAR> port_number</VAR>
3454 ...</LI>
3455 <LI>Network host<VAR> host_name</VAR> is busy; will retry in 30
3456  seconds...</LI>
3457 <LI>Printer busy; will retry in 10 seconds...</LI>
3458 <LI>Printer is busy; retrying print job...</LI>
3459 <LI>Print file accepted - job ID<VAR> id_number</VAR>.</LI>
3460 <LI>Ready to print.</LI>
3461 <LI>Waiting for job to complete</LI>
3462 </UL>
3463 <P>This directive must appear inside a<A HREF="#Printer"> <CODE>Printer</CODE>
3464 </A> or<A HREF="#DefaultPrinter"> <CODE>DefaultPrinter</CODE></A>
3465  directive.</P>
3466 <H2><A NAME="7_9">Changing the Classes Configuration</A></H2>
3467 <P>The CUPS scheduler (cupsd) uses the<VAR> /etc/cups/classes.conf</VAR>
3468  file to store the list of available classes. This file contains only
3469  locally defined classes, but not remote or implicit classes that are
3470  created automatically. Each directive is listed on a line by itself
3471  followed by its value. Comments are introduced using the number sign
3472  (&quot;#&quot;) character at the beginning of a line.</P>
3473 <P>Since the classes configuration file consists of plain text, you can
3474  use your favorite text editor to make changes to it.
3475 <!-- NEED 4in -->
3476 </P>
3477 <H2><A NAME="7_10">Classes Directives</A></H2>
3478 <P>The<VAR> classes.conf</VAR> file contains many directives that
3479  determine how the classes behaves:</P>
3480 <UL>
3481 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0">
3482 <TR><TD VALIGN="TOP">
3483 <LI><A HREF="#ClassAccepting"><CODE>Accepting</CODE></A></LI>
3484 <LI><A HREF="#ClassAllowUser"><CODE>AllowUser</CODE></A></LI>
3485 <LI><A HREF="#Class"><CODE>Class</CODE></A></LI>
3486 <LI><A HREF="#DefaultClass"><CODE>DefaultClass</CODE></A></LI>
3487 <LI><A HREF="#ClassDenyUser"><CODE>DenyUser</CODE></A></LI>
3488 </TD><TD VALIGN="TOP"> &nbsp;&nbsp;&nbsp;</TD><TD VALIGN="TOP">
3489 <LI><A HREF="#ClassInfo"><CODE>Info</CODE></A></LI>
3490 <LI><A HREF="#ClassJobSheets"><CODE>JobSheets</CODE></A></LI>
3491 <LI><A HREF="#ClassKLimit"><CODE>KLimit</CODE></A></LI>
3492 <LI><A HREF="#ClassLocation"><CODE>Location</CODE></A></LI>
3493 <LI><A HREF="#ClassPageLimit"><CODE>PageLimit</CODE></A></LI>
3494 </TD><TD VALIGN="TOP"> &nbsp;&nbsp;&nbsp;</TD><TD VALIGN="TOP">
3495 <LI><A HREF="#ClassPrinter"><CODE>Printer</CODE></A></LI>
3496 <LI><A HREF="#ClassQuotaPeriod"><CODE>QuotaPeriod</CODE></A></LI>
3497 <LI><A HREF="#ClassState"><CODE>State</CODE></A></LI>
3498 <LI><A HREF="#ClassStateMessage"><CODE>StateMessage</CODE></A></LI>
3499 </TD></TR>
3500 </TABLE>
3501 </UL>
3502
3503 <!-- NEED 3in -->
3504 <H3><A NAME="ClassAccepting">Accepting</A></H3>
3505 <HR>
3506 <H4>Examples</H4>
3507 <UL>
3508 <PRE>
3509 Accepting yes
3510
3511 Accepting no
3512 </PRE>
3513 </UL>
3514 <H4>Description</H4>
3515 <P>The <CODE>Accepting</CODE> directive defines the initial Boolean
3516  value for the<VAR> printer-is-accepting-job</VAR> attribute which can
3517  be set by the <CODE>accept</CODE> and <CODE>reject</CODE> commands.</P>
3518 <P>This directive must appear inside a<A HREF="#Class"> <CODE>Class</CODE>
3519 </A> or<A HREF="#DefaultClass"> <CODE>DefaultClass</CODE></A> directive.
3520 <!-- NEED 3in -->
3521 </P>
3522 <H3><A NAME="ClassAllowUser">AllowUser</A></H3>
3523 <HR>
3524 <H4>Examples</H4>
3525 <UL>
3526 <PRE>
3527 AllowUser foo_user
3528 AllowUser bar_user
3529 </PRE>
3530 </UL>
3531 <H4>Description</H4>
3532 <P>The <CODE>AllowUser</CODE> directive adds a username to the<VAR>
3533  requesting-user-name-allowed</VAR> attribute which can be set by the <CODE>
3534 lpadmin -u</CODE> command.</P>
3535 <P>This directive must appear inside a<A HREF="#Class"> <CODE>Class</CODE>
3536 </A> or<A HREF="#DefaultClass"> <CODE>DefaultClass</CODE></A> directive.
3537 <!-- NEED 3in -->
3538 </P>
3539 <H3><A NAME="Class">Class</A></H3>
3540 <HR>
3541 <H4>Examples</H4>
3542 <UL>
3543 <PRE>
3544 &lt;Class name/&gt;
3545 ...
3546 &lt;/Class&gt;
3547 </PRE>
3548 </UL>
3549 <H4>Description</H4>
3550 <P>The <CODE>Class</CODE> directive begins a class definition. It can be
3551  added by the <CODE>lpadmin -c</CODE> command.</P>
3552
3553 <!-- NEED 3in -->
3554 <H3><A NAME="DefaultClass">DefaultClass</A></H3>
3555 <HR>
3556 <H4>Examples</H4>
3557 <UL>
3558 <PRE>
3559 &lt;DefaultClass name/&gt;
3560 ...
3561 &lt;/DefaultClass&gt;
3562 </PRE>
3563 </UL>
3564 <H4>Description</H4>
3565 <P>The <CODE>DefaultClass</CODE> directive begins a class definition for
3566  the default server destination. It can be added by the <CODE>lpadmin -c</CODE>
3567  command or if already defined, set as default by the <CODE>lpoptions -d</CODE>
3568  command.</P>
3569
3570 <!-- NEED 3in -->
3571 <H3><A NAME="ClassDenyUser">DenyUser</A></H3>
3572 <HR>
3573 <H4>Examples</H4>
3574 <UL>
3575 <PRE>
3576 DenyUser foo_user
3577 DenyUser bar_user
3578 </PRE>
3579 </UL>
3580 <H4>Description</H4>
3581 <P>The <CODE>DenyUser</CODE> directive adds a username to the<VAR>
3582  requesting-user-name-allowed</VAR> attribute which can be set by the <CODE>
3583 lpadmin -u</CODE> command.</P>
3584 <P>This directive must appear inside a<A HREF="#Class"> <CODE>Class</CODE>
3585 </A> or<A HREF="#DefaultClass"> <CODE>DefaultClass</CODE></A> directive.
3586 <!-- NEED 3in -->
3587 </P>
3588 <H3><A NAME="ClassInfo">Info</A></H3>
3589 <HR>
3590 <H4>Examples</H4>
3591 <UL>
3592 <PRE>
3593 Info My Printer
3594 </PRE>
3595 </UL>
3596 <H4>Description</H4>
3597 <P>The <CODE>Info</CODE> directive defines the string for the<VAR>
3598  printer-info</VAR> attribute which can be set by the <CODE>lpadmin -D</CODE>
3599  command.</P>
3600 <P>This directive must appear inside a<A HREF="#Class"> <CODE>Class</CODE>
3601 </A> or<A HREF="#DefaultClass"> <CODE>DefaultClass</CODE></A> directive.
3602 <!-- NEED 6in -->
3603 </P>
3604 <H3><A NAME="ClassJobSheets">JobSheets</A></H3>
3605 <HR>
3606 <H4>Examples</H4>
3607 <UL>
3608 <PRE>
3609 JobSheets none,standard
3610 </PRE>
3611 </UL>
3612 <H4>Description</H4>
3613 <P>The <CODE>JobSheets</CODE> directive specifies the default banner
3614  pages to print before and after a print job. In the above example, only
3615  a<VAR> standard</VAR> banner will print after each job.</P>
3616 <P>The <CODE>lpoptions -o job-sheets=</CODE> command can be used to set
3617  banners. For example, the following command would produce the same
3618  results of a<VAR> standard</VAR> banner at the end of each print job
3619  for the default class.</P>
3620 <UL><B> lpoptions -o job-sheets=none,standard</B></UL>
3621 <P>If only one banner file is specified, it will be printed before the
3622  files in the job. If a second banner file is specified, it is printed
3623  after the files in the job.</P>
3624 <P>The available banner pages depend on the local system configuration;
3625  CUPS includes the following banner files:</P>
3626 <UL>
3627 <LI><CODE>none</CODE> - Do not produce a banner page.</LI>
3628 <LI><CODE>classified</CODE> - A banner page with a &quot;classified&quot; label at
3629  the top and bottom.</LI>
3630 <LI><CODE>confidential</CODE> - A banner page with a &quot;confidential&quot;
3631  label at the top and bottom.</LI>
3632 <LI><CODE>secret</CODE> - A banner page with a &quot;secret&quot; label at the top
3633  and bottom.</LI>
3634 <LI><CODE>standard</CODE> - A banner page with no label at the top and
3635  bottom.</LI>
3636 <LI><CODE>topsecret</CODE> - A banner page with a &quot;top secret&quot; label at
3637  the top and bottom.</LI>
3638 <LI><CODE>unclassified</CODE> - A banner page with an &quot;unclassified&quot;
3639  label at the top and bottom.</LI>
3640 </UL>
3641 <P>This directive must appear inside a<A HREF="#Class"> <CODE>Class</CODE>
3642 </A> or<A HREF="#DefaultClass"> <CODE>DefaultClass</CODE></A> directive.
3643 <!-- NEED 3in -->
3644 </P>
3645 <H3><A NAME="ClassKLimit">KLimit</A></H3>
3646 <HR>
3647 <H4>Examples</H4>
3648 <UL>
3649 <PRE>
3650 KLimit 1234
3651 </PRE>
3652 </UL>
3653 <H4>Description</H4>
3654 <P>The <CODE>KLimit</CODE> directive defines the value of the<VAR>
3655  job-k-limit</VAR> attribute which can be set by the <CODE>lpadmin -o
3656  job-k-limit=</CODE> command.</P>
3657 <P>This directive must appear inside a<A HREF="#Class"> <CODE>Class</CODE>
3658 </A> or<A HREF="#DefaultClass"> <CODE>DefaultClass</CODE></A> directive.
3659 <!-- NEED 6in -->
3660 </P>
3661 <H3><A NAME="ClassLocation">Location</A></H3>
3662 <HR>
3663 <H4>Examples</H4>
3664 <UL>
3665 <PRE>
3666 Location Building 3321
3667 </PRE>
3668 </UL>
3669 <H4>Description</H4>
3670 <P>The <CODE>Location</CODE> directive defines the string for the<VAR>
3671  printer-location</VAR> attribute which can be set by the <CODE>lpadmin
3672  -L</CODE> command.</P>
3673 <CENTER>
3674 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
3675 <TR><TD><B> NOTE:</B>
3676 <P>Do not confuse this <CODE>Location</CODE> directive with the one for
3677  cupsd.conf. They are completely different.</P>
3678 </TD></TR>
3679 </TABLE>
3680 </CENTER>
3681 <P>This directive must appear inside a<A HREF="#Class"> <CODE>Class</CODE>
3682 </A> or<A HREF="#DefaultClass"> <CODE>DefaultClass</CODE></A> directive.
3683 <!-- NEED 3in -->
3684 </P>
3685 <H3><A NAME="ClassPageLimit">PageLimit</A></H3>
3686 <HR>
3687 <H4>Examples</H4>
3688 <UL>
3689 <PRE>
3690 PageLimit 1234
3691 </PRE>
3692 </UL>
3693 <H4>Description</H4>
3694 <P>The <CODE>PageLimit</CODE> directive defines the value of the<VAR>
3695  job-page-limit</VAR> attribute which can be set by the <CODE>lpadmin -o
3696  job-page-limit=</CODE> command.</P>
3697 <P>This directive must appear inside a<A HREF="#Class"> <CODE>Class</CODE>
3698 </A> or<A HREF="#DefaultClass"> <CODE>DefaultClass</CODE></A> directive.
3699 <!-- NEED 3in -->
3700 </P>
3701 <H3><A NAME="ClassPrinter">Printer</A></H3>
3702 <HR>
3703 <H4>Examples</H4>
3704 <UL>
3705 <PRE>
3706 Printer foo
3707 Printer bar
3708 Printer foo@bar
3709 </PRE>
3710 </UL>
3711 <H4>Description</H4>
3712 <P>The <CODE>Printer</CODE> directive adds a printer to the class. It
3713  can be added by the <CODE>lpadmin -c</CODE> command.</P>
3714 <CENTER>
3715 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
3716 <TR><TD><B> NOTE:</B>
3717 <P>Do not confuse this <CODE>Printer</CODE> directive with the one for
3718  printers.conf. They are completely different.</P>
3719 </TD></TR>
3720 </TABLE>
3721 </CENTER>
3722 <P>This directive must appear inside a<A HREF="#Class"> <CODE>Class</CODE>
3723 </A> or<A HREF="#DefaultClass"> <CODE>DefaultClass</CODE></A> directive.</P>
3724
3725 <!-- NEED 3in -->
3726 <H3><A NAME="ClassQuotaPeriod">QuotaPeriod</A></H3>
3727 <HR>
3728 <H4>Examples</H4>
3729 <UL>
3730 <PRE>
3731 QuotaPeriod 604800
3732 </PRE>
3733 </UL>
3734 <H4>Description</H4>
3735 <P>The <CODE>QuotaPeriod</CODE> directive defines the value of the<VAR>
3736  job-quota-period</VAR> attribute which can be set by the <CODE>lpadmin
3737  -o job-quota-period=</CODE> command.</P>
3738 <P>This directive must appear inside a<A HREF="#Class"> <CODE>Class</CODE>
3739 </A> or<A HREF="#DefaultClass"> <CODE>DefaultClass</CODE></A> directive.
3740 <!-- NEED 3in -->
3741 </P>
3742 <H3><A NAME="ClassState">State</A></H3>
3743 <HR>
3744 <H4>Examples</H4>
3745 <UL>
3746 <PRE>
3747 State stopped
3748 </PRE>
3749 </UL>
3750 <H4>Description</H4>
3751 <P>The <CODE>State</CODE> directive defines the initial value of the<VAR>
3752  printer-state</VAR> attribute. The strings<VAR> idle</VAR> and<VAR>
3753  stopped</VAR> correspond to the IPP enumeration values.</P>
3754 <P>This directive must appear inside a<A HREF="#Class"> <CODE>Class</CODE>
3755 </A> or<A HREF="#DefaultClass"> <CODE>DefaultClass</CODE></A> directive.
3756 <!-- NEED 6in -->
3757 </P>
3758 <H3><A NAME="ClassStateMessage">StateMessage</A></H3>
3759 <HR>
3760 <H4>Examples</H4>
3761 <UL>
3762 <PRE>
3763 StateMessage Ready to print.
3764 </PRE>
3765 </UL>
3766 <H4>Description</H4>
3767 <P>The <CODE>StateMessage</CODE> directive defines the initial string
3768  for the<VAR> printer-state-message</VAR> attribute. The following are
3769  some example messages:</P>
3770 <UL>
3771 <LI>Connected to<VAR> host_name</VAR>...</LI>
3772 <LI>Connecting to<VAR> class_queue</VAR> on port<VAR> port_number</VAR>
3773 ...</LI>
3774 <LI>Network host<VAR> host_name</VAR> is busy; will retry in 30
3775  seconds...</LI>
3776 <LI>Printer busy; will retry in 10 seconds...</LI>
3777 <LI>Printer is busy; retrying print job...</LI>
3778 <LI>Print file accepted - job ID<VAR> id_number</VAR>.</LI>
3779 <LI>Ready to print.</LI>
3780 <LI>Waiting for job to complete</LI>
3781 </UL>
3782 <P>This directive must appear inside a<A HREF="#Class"> <CODE>Class</CODE>
3783 </A> or<A HREF="#DefaultClass"> <CODE>DefaultClass</CODE></A> directive.</P>
3784
3785 <!-- NEW PAGE -->
3786 <H2><A NAME="PRINTING_SECURITY">Printing System Security</A></H2>
3787 <P>CUPS provides support for address, certificate, and password (Basic
3788  and Digest) based authentication and access control. Certificate and
3789  password authentication provide ways to limit access to individual
3790  people or groups.</P>
3791 <P>Address based access control allows you to limit access to specific
3792  systems, networks, or domains. While this does not provide
3793  authentication, it does allow you to limit the potential users of your
3794  system efficiently.</P>
3795 <P>CUPS maintains a list of locations that have access control and/or
3796  authentication enabled. Locations are specified using the<A HREF="#Location">
3797  <CODE>Location</CODE></A> directive:</P>
3798 <UL>
3799 <PRE>
3800 &lt;Location /resource&gt;
3801 <A HREF="#AuthClass">AuthClass</A> ...
3802 <A HREF="#AuthGroupName">AuthGroupName</A> ...
3803 <A HREF="#AuthType">AuthType</A> ...
3804
3805 <A HREF="#Order">Order</A> ...
3806 <A HREF="#Allow">Allow</A> from ...
3807 <A HREF="#Deny">Deny</A> from ...
3808 &lt;/Location&gt;
3809 </PRE>
3810 </UL>
3811 <P>Locations generally follow the directory structure of the<A HREF="#DocumentRoot">
3812  <CODE>DocumentRoot</CODE></A> directory, however CUPS does have several
3813  virtual locations for administration, classes, jobs, and printers:
3814 <CENTER>
3815 <TABLE BORDER="1">
3816 <TR><TH>Location</TH><TH>Description</TH></TR>
3817 <TR><TD>/admin</TD><TD>The path for all administration operations.</TD></TR>
3818 <TR><TD>/classes</TD><TD>The path for all classes.</TD></TR>
3819 <TR><TD>/classes/name</TD><TD>The resource for class <CODE>name</CODE>.</TD>
3820 </TR>
3821 <TR><TD>/jobs</TD><TD>The path for all jobs.</TD></TR>
3822 <TR><TD>/jobs/id</TD><TD>The resource for job <CODE>id</CODE>.</TD></TR>
3823 <TR><TD>/printers</TD><TD>The path for all printers.</TD></TR>
3824 <TR><TD>/printers/name</TD><TD>The path for printer <CODE>name</CODE>.</TD>
3825 </TR>
3826 <TR><TD>/printers/name.ppd</TD><TD>The PPD file path for printer <CODE>
3827 name</CODE>.</TD></TR>
3828 </TABLE>
3829 </CENTER>
3830 </P>
3831 <H3><A NAME="CERTIFICATES">Authentication Using Certificates</A></H3>
3832 <P>CUPS supports a local certificate-based authentication scheme that
3833  can be used in place of <CODE>Basic</CODE> or <CODE>Digest</CODE>
3834  authentication by clients connecting through the <CODE>localhost</CODE>
3835  interface. Certificate authentication is not supported or allowed from
3836  clients on any other interface.</P>
3837 <P>Certificates are 128-bit random numbers that refer to an internal
3838  authentication record in the server. A client connecting via the <CODE>
3839 localhost</CODE> interface sends a request with an authorization header
3840  of:</P>
3841 <UL>
3842 <PRE>
3843 Authorization: Local 0123456789ABCDEF0123456789ABCDEF
3844 </PRE>
3845 </UL>
3846 <P>The server then looks up the local certificate and authenticates
3847  using the username associated with it.</P>
3848 <P>Certificates are generated by the server automatically and stored in
3849  the<VAR> /etc/cups/certs</VAR> directory using the process ID of the
3850  CGI program started by the server. Certificate files are only readable
3851  by the<A HREF="#User"> <CODE>User</CODE></A> and<A HREF="#Group"> <CODE>
3852 Group</CODE></A> defined in the<VAR> cupsd.conf</VAR> file. When the CGI
3853  program ends the certificate is removed and invalidated automatically.</P>
3854 <P>The special file<VAR> /etc/cups/certs/0</VAR> defines the<I> root
3855  certificate</I> which can be used by any client running as the
3856  super-user or another user that is part of the group defined by the<A HREF="#SystemGroup">
3857  <CODE>SystemGroup</CODE></A> directive. The root certificate is
3858  automatically regenerated every 5 minutes.</P>
3859 <H3><A NAME="7_11_2">Using Basic Authentication</A></H3>
3860 <P>Basic authentication uses UNIX users and passwords to authenticate
3861  access to resources such as printers and classes, and to limit access
3862  to administrative functions.</P>
3863 <CENTER>
3864 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
3865 <TR><TD><B> NOTE:</B>
3866 <P>Basic authentication sends the username and password Base64 encoded
3867  from the client to the server, so it offers no protection against
3868  eavesdropping. This means that a malicious user can monitor network
3869  packets and discover valid users and passwords that could result in a
3870  serious compromise in network security. Use Basic authentication with
3871  extreme care.</P>
3872 </TD></TR>
3873 </TABLE>
3874 </CENTER>
3875 <P>The CUPS implementation of Basic authentication does not allow access
3876  through user accounts without a password. If you try to authenticate
3877  using an account without a password, your access will be immediately
3878  blocked.</P>
3879 <P>Once a valid username and password is authenticated by CUPS, any
3880  additional group membership requirements are checked.</P>
3881 <CENTER>
3882 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
3883 <TR><TD><B> NOTE:</B>
3884 <P>The root user is considered by CUPS to be a member of every group.</P>
3885 </TD></TR>
3886 </TABLE>
3887 </CENTER>
3888
3889 <!-- NEED 1in -->
3890 <P>Use the <CODE>AuthType</CODE> directive to enable Basic
3891  authentication:</P>
3892 <UL>
3893 <PRE>
3894 AuthType Basic
3895 </PRE>
3896 </UL>
3897
3898 <!-- NEED 7in -->
3899 <H3><A NAME="7_11_3">Using Digest Authentication</A></H3>
3900 <P>Digest authentication uses users and passwords defined in the<VAR>
3901  /etc/cups/passwd.md5</VAR> file to authenticate access to resources
3902  such as printers and classes, and to limit access to administrative
3903  functions.</P>
3904 <CENTER>
3905 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
3906 <TR><TD><B> NOTE:</B>
3907 <P>Unlike Basic authentication, Digest passes the MD5 sum (basically a
3908  complicated checksum) of the username and password instead of the
3909  strings themselves. Also, Digest authentication does not use the UNIX
3910  password file, so if an attacker does discover the original password it
3911  is less likely to result in a serious security problem so long as you
3912  use a different UNIX password than the corresponding Digest password.</P>
3913 <P>The current CUPS implementation of Digest authentication uses the
3914  client's hostname or IP address for the &quot;nonce&quot; value. The nonce value
3915  is an additional string added to the username and password to make
3916  guessing the password more difficult. The server checks that the nonce
3917  value matches the client's hostname or address and rejects the MD5 sum
3918  if it doesn't. Future versions of CUPS will support Digest &quot;session&quot;
3919  authentication which adds the request data to the MD5 sum, providing
3920  even better authentication and security.</P>
3921 <P>Digest authentication does not guarantee that an attacker cannot gain
3922  unauthorized access, but it is safer than Basic authentication and
3923  should be used in place of Basic authentication whenever possible.<B>
3924  Support for Digest authentication in web browsers is not yet
3925  universally available.</B></P>
3926 </TD></TR>
3927 </TABLE>
3928 </CENTER>
3929
3930 <!-- NEED 2in -->
3931 <P>The <CODE>lppasswd(1)</CODE> command is used to add, change, or
3932  remove accounts from the<VAR> passwd.md5</VAR> file. To add a user to
3933  the default system group, type:</P>
3934 <UL>
3935 <PRE>
3936 <B>lppasswd -a user ENTER</B>
3937 Password: <B>(password) ENTER</B> [password is not echoed]
3938 Password again: <B>(password) ENTER</B> [password is not echoed]
3939 </PRE>
3940 </UL>
3941
3942 <!-- NEED 2in -->
3943 <P>Once added, a user can change his/her password by typing:</P>
3944 <UL>
3945 <PRE>
3946 <B>lppasswd ENTER</B>
3947 Old password: <B>(password) ENTER</B> [password is not echoed]
3948 Password: <B>(password) ENTER</B> [password is not echoed]
3949 Password again: <B>(password) ENTER</B> [password is not echoed]
3950 </PRE>
3951 </UL>
3952
3953 <!-- NEED 1in -->
3954 <P>To remove a user from the password file, type:</P>
3955 <UL>
3956 <PRE>
3957 <B>lppasswd -x user ENTER</B>
3958 </PRE>
3959 </UL>
3960 <P>Once a valid username and password is authenticated by CUPS, any
3961  additional group membership requirements are checked.</P>
3962 <CENTER>
3963 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
3964 <TR><TD><B> NOTE:</B>
3965 <P>The root user is considered by CUPS to be a member of every group.</P>
3966 </TD></TR>
3967 </TABLE>
3968 </CENTER>
3969 <P>Use the <CODE>AuthType</CODE> directive to enable Digest
3970  authentication:</P>
3971 <UL>
3972 <PRE>
3973 AuthType Digest
3974 </PRE>
3975 </UL>
3976 <H3><A NAME="7_11_4">System and Group Authentication</A></H3>
3977 <P>The<A HREF="#AuthClass"> <CODE>AuthClass</CODE></A> directive
3978  controls the level of authentication to perform. <CODE>System</CODE>
3979  and <CODE>Group</CODE> authentication extend the normal user-based
3980  authentication to require membership in a UNIX group. For <CODE>System</CODE>
3981  authentication each user must belong to the <CODE>sys</CODE>, <CODE>
3982 system</CODE>, or <CODE>root</CODE> group; the actual group depends on
3983  the operating system.</P>
3984 <P>For <CODE>Group</CODE> authentication each user must belong to the
3985  group named by the<A HREF="#AuthGroupName"> <CODE>AuthGroupName</CODE></A>
3986  directive:</P>
3987 <UL>
3988 <PRE>
3989 &lt;Location /path&gt;
3990 AuthType Digest
3991 AuthClass Group
3992 AuthGroupName mygroup
3993 &lt;/Location&gt;
3994 </PRE>
3995 </UL>
3996 <P>The named group must be a valid UNIX user group, usually defined in
3997  the<VAR> /etc/group</VAR> or<VAR> /etc/netgroup</VAR> files.
3998  Additionally, when using Digest authentication you need to create user
3999  accounts with the named group:</P>
4000 <UL>
4001 <PRE>
4002 <B>lppasswd -g mygroup -a user ENTER</B>
4003 Password: <B>(password) ENTER</B> [password is not echoed]
4004 Password again: <B>(password) ENTER</B> [password is not echoed]
4005 </PRE>
4006 </UL>
4007
4008 <!-- NEW PAGE -->
4009 <H2><A NAME="PRINTER_ACCOUNTING">Printer Accounting</A></H2>
4010 <P>CUPS maintains a log of all accesses, errors, and pages that are
4011  printed. The log files are normally stored in the<VAR> /var/log/cups</VAR>
4012  directory. You can change this by editing the<VAR> /etc/cups/cupsd.conf</VAR>
4013  configuration file.</P>
4014 <H3><A NAME="7_12_1">The access_log File</A></H3>
4015 <P>The<VAR> access_log</VAR> file lists each HTTP resource that is
4016  accessed by a web browser or CUPS/IPP client. Each line is in the
4017  so-called &quot;Common Log Format&quot; used by many web servers and web
4018  reporting tools:</P>
4019 <UL>
4020 <PRE>
4021 host group user date-time \&quot;method resource version\&quot; status bytes
4022
4023 127.0.0.1 - - [20/May/1999:19:20:29 +0000] &quot;POST /admin/ HTTP/1.1&quot; 401 0
4024 127.0.0.1 - mike [20/May/1999:19:20:31 +0000] &quot;POST /admin/ HTTP/1.1&quot; 200 0
4025 </PRE>
4026 </UL>
4027 <P>The<I> host</I> field will normally only be an IP address unless you
4028  have enabled the<A HREF="#HostNameLookups"> <CODE>HostNameLookups</CODE>
4029 </A> directive in the<VAR> cupsd.conf</VAR> file.</P>
4030 <P>The<I> group</I> field always contains &quot;-&quot; in CUPS.</P>
4031 <P>The<I> user</I> field is the authenticated username of the requesting
4032  user. If no username and password is supplied for the request then this
4033  field contains &quot;-&quot;.</P>
4034 <P>The<I> date-time</I> field is the date and time of the request in
4035  local time and is in the format:</P>
4036 <UL>
4037 <PRE>
4038 [DD/MON/YYYY:HH:MM:SS +ZZZZ]
4039 </PRE>
4040 </UL>
4041 <P>where<I> ZZZZ</I> is the timezone offset in hours and minutes from
4042  coordinated universal time (UTC). UTC may sometimes be referred to as
4043  GMT or ZULU on legacy systems.</P>
4044 <P>The<I> method</I> field is the HTTP method used (&quot;GET&quot;, &quot;PUT&quot;,
4045  &quot;POST&quot;, etc.)</P>
4046 <P>The<I> resource</I> field is the filename of the requested resource.</P>
4047 <P>The<I> version</I> field is the HTTP specification version used by
4048  the client. For CUPS clients this will always be &quot;HTTP/1.1&quot;.</P>
4049 <P>The<I> status</I> field contains the HTTP result status of the
4050  request. Usually it is &quot;200&quot;, but other HTTP status codes are possible.
4051  For example, 401 is the &quot;unauthorized access&quot; status in the example
4052  above.</P>
4053 <P>The<I> bytes</I> field contains the number of bytes in the request.
4054  For POST requests the<I> bytes</I> field contains the number of bytes
4055  that was received from the client.</P>
4056 <H3><A NAME="7_12_2">The error_log File</A></H3>
4057 <P>The<VAR> error_log</VAR> file lists messages from the scheduler
4058  (errors, warnings, etc.):</P>
4059 <UL>
4060 <PRE>
4061 level date-time message
4062
4063 I [20/May/1999:19:18:28 +0000] Job 1 queued on 'DeskJet' by 'mike'.
4064 I [20/May/1999:19:21:02 +0000] Job 2 queued on 'DeskJet' by 'mike'.
4065 I [20/May/1999:19:22:24 +0000] Job 2 was cancelled by 'mike'.
4066 </PRE>
4067 </UL>
4068 <P>The<I> level</I> field contains the type of message:</P>
4069 <UL>
4070 <LI><CODE>E</CODE> - An error occurred.</LI>
4071 <LI><CODE>W</CODE> - The server was unable to perform some action.</LI>
4072 <LI><CODE>I</CODE> - Informational message.</LI>
4073 <LI><CODE>D</CODE> - Debugging message.</LI>
4074 </UL>
4075 <P>The<I> date-time</I> field contains the date and time of when the
4076  page started printing. The format of this field is identical to the<I>
4077  data-time</I> field in the<VAR> access_log</VAR> file.</P>
4078 <P>The<I> message</I> fields contains a free-form textual message.</P>
4079 <H3><A NAME="7_12_3">The page_log File</A></H3>
4080 <P>The<VAR> page_log</VAR> file lists each page that is sent to a
4081  printer. Each line contains the following information:</P>
4082 <UL>
4083 <PRE>
4084 printer user job-id date-time page-number num-copies job-billing
4085
4086 DeskJet root 2 [20/May/1999:19:21:05 +0000] 1 0 acme-123
4087 </PRE>
4088 </UL>
4089 <P>The<I> printer</I> field contains the name of the printer that
4090  printed the page. If you send a job to a printer class, this field will
4091  contain the name of the printer that was assigned the job.</P>
4092 <P>The<I> user</I> field contains the name of the user (the IPP <CODE>
4093 requesting-user-name</CODE> attribute) that submitted this file for
4094  printing.</P>
4095 <P>The<I> job-id</I> field contains the job number of the page being
4096  printed. Job numbers are reset to 1 whenever the CUPS server is
4097  started, so don't depend on this number being unique!</P>
4098 <P>The<I> date-time</I> field contains the date and time of when the
4099  page started printing. The format of this field is identical to the<I>
4100  data-time</I> field in the<VAR> access_log</VAR> file.</P>
4101 <P>The<I> page-number</I> and<I> num-pages</I> fields contain the page
4102  number and number of copies being printed of that page. For printer
4103  that can not produce copies on their own, the<I> num-pages</I> field
4104  will always be 1.</P>
4105 <P>The<I> job-billing</I> field contains a copy of the <CODE>job-billing</CODE>
4106  attribute provided with the IPP <CODE>create-job</CODE> or <CODE>
4107 print-job</CODE> requests or &quot;-&quot; if none was provided.
4108 <!-- NEW PAGE -->
4109 </P>
4110 <H2><A NAME="FILE_TYPING_FILTERING">File Typing and Filtering</A></H2>
4111 <P>CUPS provides a MIME-based file typing and filtering mechanism to
4112  convert files to a printable format for each printer. On startup the
4113  CUPS server reads MIME database files from the<VAR> /etc/cups</VAR>
4114  directory (or a directory specified by the<A HREF="#ServerRoot"> <CODE>
4115 ServerRoot</CODE></A> directive) to build a file type and conversion
4116  database in memory. These database files are plain ASCII text and can
4117  be edited with your favorite text editor.</P>
4118 <P>The<VAR> mime.types</VAR> and<VAR> mime.convs</VAR> files define the
4119  standard file types and filters that are available on the system.</P>
4120 <H3><A NAME="7_13_1">mime.types</A></H3>
4121 <P>The<VAR> mime.types</VAR> file defines the known file types. Each
4122  line of the file starts with the MIME type and may be followed by one
4123  or more file type recognition rules. For example, the <CODE>text/html</CODE>
4124  file type is defined as:</P>
4125 <UL>
4126 <PRE>
4127 text/html       html htm \
4128         printable(0,1024) + \
4129         (string(0,&quot;&lt;HTML&gt;&quot;) string(0,&quot;&lt;!DOCTYPE&quot;))
4130 </PRE>
4131 </UL>
4132 <P>The first two rules say that any file with an extension of<VAR> .html</VAR>
4133  or<VAR> .htm</VAR> is a HTML file. The third rule says that any file
4134  whose first 1024 characters are printable text and starts with the
4135  strings <CODE>&lt;HTML&gt;</CODE> or <CODE>&lt;!DOCTYPE</CODE> is a HTML file as
4136  well.</P>
4137 <P>The first two rules deal solely with the name of the file being
4138  typed. This is useful when the original filename is known, however for
4139  print files the server doesn't have a filename to work with. The third
4140  rule takes care of this possibility and automatically figures out the
4141  file type based upon the contents of the file instead.</P>
4142 <P>The available tests are:</P>
4143 <UL>
4144 <LI><CODE>( expr )</CODE> - Parenthesis for expression grouping</LI>
4145 <LI><CODE>+</CODE> - Logical AND</LI>
4146 <LI><CODE>,</CODE> or whitespace - Logical OR</LI>
4147 <LI><CODE>!</CODE> - Logical NOT</LI>
4148 <LI><CODE>match(&quot;pattern&quot;)</CODE> - Pattern match on filename</LI>
4149 <LI><CODE>extension</CODE> - Pattern match on &quot;*.extension&quot;</LI>
4150 <LI><CODE>ascii(offset,length)</CODE> - True if bytes are valid
4151  printable ASCII (CR, NL, TAB, BS, 32-126)</LI>
4152 <LI><CODE>printable(offset,length)</CODE> - True if bytes are printable
4153  8-bit chars (CR, NL, TAB, BS, 32-126, 160-254)</LI>
4154 <LI><CODE>string(offset,&quot;string&quot;)</CODE> - True if bytes are identical
4155  to string</LI>
4156 <LI><CODE>contains(offset,range,&quot;string&quot;)</CODE> - True if the range of
4157  bytes contains the string</LI>
4158 <LI><CODE>char(offset,value)</CODE> - True if byte is identical</LI>
4159 <LI><CODE>short(offset,value)</CODE> - True if 16-bit integer is
4160  identical (network or &quot;big-endian&quot; byte order)</LI>
4161 <LI><CODE>int(offset,value)</CODE> - True if 32-bit integer is identical
4162  (network or &quot;big-endian&quot; byte order)</LI>
4163 <LI><CODE>locale(&quot;string&quot;)</CODE> - True if current locale matches
4164  string</LI>
4165 </UL>
4166 <P>All numeric values can be in decimal (123), octal (0123), or
4167  hexadecimal (0x123) as desired.
4168 <!-- NEED 2.5in -->
4169 </P>
4170 <P>Strings can be in quotes, all by themselves, as a string of
4171  hexadecimal values, or some combination:</P>
4172 <UL>
4173 <PRE>
4174 &quot;string&quot;
4175 'string'
4176 string
4177 &lt;737472696e67&gt;
4178 &lt;7374&gt;ring
4179 </PRE>
4180 </UL>
4181 <P>As shown in the <CODE>text/html</CODE> example, rules can continue on
4182  multiple lines using the backslash (\) character. A more complex
4183  example is the <CODE>image/jpeg</CODE> rules:</P>
4184 <UL>
4185 <PRE>
4186 image/jpeg      jpeg jpg jpe string(0,&lt;FFD8FF&gt;) &amp;&amp;\
4187         (char(3,0xe0) char(3,0xe1) char(3,0xe2) char(3,0xe3)\
4188          char(3,0xe4) char(3,0xe5) char(3,0xe6) char(3,0xe7)\
4189          char(3,0xe8) char(3,0xe9) char(3,0xea) char(3,0xeb)\
4190          char(3,0xec) char(3,0xed) char(3,0xee) char(3,0xef))
4191 </PRE>
4192 </UL>
4193 <P>This rule states that any file with an extension of<VAR> .jpeg</VAR>,<VAR>
4194  .jpg</VAR>, or<VAR> .jpe</VAR> is a JPEG file. In addition, any file
4195  starting with the hexadecimal string <CODE>&lt;FFD8FF&gt;</CODE> (JPEG
4196  Start-Of-Image) followed by a character between and including <CODE>
4197 0xe0</CODE> and <CODE>0xef</CODE> (JPEG APPn markers) is also a JPEG
4198  file.</P>
4199 <H3><A NAME="7_13_2">mime.convs</A></H3>
4200 <P>The<VAR> mime.convs</VAR> file defines all of the filter programs
4201  that are known to the system. Each line consists of:</P>
4202 <UL>
4203 <PRE>
4204 source destination cost program
4205
4206 text/plain application/postscript 50 texttops
4207 application/vnd.cups-postscript application/vnd.cups-raster 50 pstoraster
4208 image/* application/vnd.cups-postscript 50 imagetops
4209 image/* application/vnd.cups-raster 50 imagetoraster
4210 </PRE>
4211 </UL>
4212 <P>The<I> source</I> field is a MIME type, optionally using a wildcard
4213  for the super-type or sub-type (e.g. &quot;text/plain&quot;, &quot;image/*&quot;,
4214  &quot;*/postscript&quot;).</P>
4215 <P>The<I> destination</I> field is a MIME type defined in the<VAR>
4216  mime.types</VAR> file.</P>
4217 <P>The<I> cost</I> field defines a relative cost for the filtering
4218  operation from 1 to 100. The cost is used to choose between two
4219  different sets of filters when converting a file. For example, to
4220  convert from <CODE>image/jpeg</CODE> to <CODE>
4221 application/vnd.cups-raster</CODE>, you could use the <CODE>imagetops</CODE>
4222  and <CODE>pstoraster</CODE> filters for a total cost of 100, or the <CODE>
4223 imagetoraster</CODE> filter for a total cost of 50.</P>
4224 <P>The<I> program</I> field defines the filter program to run; the
4225  special program &quot;-&quot; can be used to make two file types equivalent. The
4226  program must accept the standard filter arguments and environment
4227  variables described in the CUPS Interface Design Description and CUPS
4228  Software Programmers Manual:</P>
4229 <UL>
4230 <PRE>
4231 program job user title options [filename]
4232 </PRE>
4233 </UL>
4234 <P>If specified, the<I> filename</I> argument defines a file to read
4235  when filtering, otherwise the filter must read from the standard input.
4236  All filtered output must go to the standard output.
4237 <!-- NEED 4in -->
4238 </P>
4239 <H3><A NAME="7_13_3">Adding Filetypes and Filters</A></H3>
4240 <P>Adding a new file type or filter is fairly straight-forward. Rather
4241  than adding the new type and filter to the<VAR> mime.types</VAR> and<VAR>
4242  mime.convs</VAR> files which are overwritten when you upgrade to a new
4243  version of CUPS, you simple need to create new files with<VAR> .types</VAR>
4244  and<VAR> .convs</VAR> extensions in the<VAR> /etc/cups</VAR> directory.
4245  We recommend that you use the product or format name, e.g.:</P>
4246 <UL>
4247 <PRE>
4248 myproduct.types
4249 myproduct.convs
4250 </PRE>
4251 </UL>
4252 <P>If you are providing a filter for a common file format or printer,
4253  add the company or author name:</P>
4254 <UL>
4255 <PRE>
4256 acme-msword.types
4257 acme.msword.convs
4258 </PRE>
4259 </UL>
4260 <P>This will help to prevent name collisions if you install many
4261  different file types and filters.</P>
4262 <P>Once you choose the names for these files, create them using your
4263  favorite text editor as described earlier in this chapter. Once you
4264  have created the files, restart the <CODE>cupsd</CODE> process as
4265  described earlier in<A HREF="#RESTARTING"> &quot;Restarting the CUPS Server&quot;</A>
4266 .</P>
4267 <H3><A NAME="7_13_4">Printer Drivers and PPD Files</A></H3>
4268 <P>Most CUPS printer drivers utilize one or more printer-specific
4269  filters and a PPD file for each printer model. Printer driver filters
4270  are registered via the PPD file using <CODE>cupsFilter</CODE>
4271  attributes:</P>
4272 <UL>
4273 <PRE>
4274 *cupsFilter: &quot;application/vnd.cups-raster 0 rastertohp&quot;
4275 </PRE>
4276 </UL>
4277 <P>The filter is specified using the source file type only; the
4278  destination file type is assumed to be <CODE>printer/name</CODE> -
4279  suitable for sending to the printer.</P>
4280 <H3><A NAME="7_13_5">Writing Your Own Filter or Printer Driver</A></H3>
4281 <P>CUPS supports an unlimited number of file formats and filters, and
4282  can handle any printer. If you'd like to write a filter or printer
4283  driver for your favorite file format or printer, consult the CUPS
4284  Software Programmers Manual for step-by-step instructions.</P>
4285 <H1 ALIGN="RIGHT"><A NAME="PRINTING_OTHER">7 - Printing with Other
4286  Systems</A></H1>
4287 <P>This chapter describes how to print from client systems that use the
4288  LPD, Mac OS, or Windows printing protocols.</P>
4289 <H2><A NAME="8_1">The Basics</A></H2>
4290 <P>CUPS is based on the IPP protocol, so any system that supports IPP
4291  can send jobs to and receive jobs from CUPS automatically. However, not
4292  all systems support IPP yet. This chapter will show you how to connect
4293  these systems to your CUPS server, either to accept jobs from your
4294  server for printing, or to send jobs to your server.</P>
4295 <H2><A NAME="8_2">Printing from LPD Clients</A></H2>
4296 <P>CUPS supports limited functionality for LPD-based clients. With LPD
4297  you can print files to specific printers, list the queue status, and so
4298  forth. However, the automatic client configuration and printer options
4299  are not supported by the LPD protocol, so you must manually configure
4300  each client for the printers it needs to access.</P>
4301 <P>The <CODE>cups-lpd(8)</CODE> program provides support for LPD clients
4302  and can be used from either the <CODE>inetd(8)</CODE> or <CODE>
4303 xinetd(8)</CODE> programs. Add the following line to the<VAR>
4304  /etc/inetd.conf</VAR> file to enable LPD support on your server through
4305  the <CODE>inetd</CODE> program:</P>
4306 <UL>
4307 <PRE>
4308 printer stream tcp nowait lp /usr/lib/cups/daemon/cups-lpd cups-lpd
4309 </PRE>
4310 </UL>
4311 <P>The path to the <CODE>cups-lpd</CODE> may vary depending on your
4312  installation.</P>
4313 <P>Once you have added this line, send the <CODE>inetd</CODE> process a <CODE>
4314 HUP</CODE> signal or reboot the system:</P>
4315 <UL>
4316 <PRE>
4317 <B>killall -HUP inetd ENTER</B> [IRIX and some versions of Linux]
4318 <B>kill -HUP <I>pid</I> ENTER [Others]</B>
4319 <B>reboot ENTER [For all systems if the HUP signal fails]</B>
4320 </PRE>
4321 </UL>
4322 <P>If you are using the <CODE>xinetd</CODE> program, create a file named<VAR>
4323  /etc/xinetd.d/printer</VAR> containing the following lines:</P>
4324 <UL>
4325 <PRE>
4326 service printer
4327 {
4328 socket_type = stream
4329 protocol = tcp
4330 wait = no
4331 user = lp
4332 server = /usr/lib/cups/daemon/cups-lpd
4333 }
4334 </PRE>
4335 </UL>
4336 <P>The <CODE>xinetd</CODE> program automatically reads the new
4337  configuration file and enables LPD printing support.
4338 <CENTER>
4339 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
4340 <TR><TD><B>Warning:</B>
4341 <P><CODE>cups-lpd</CODE> currently does not perform any access control
4342  based on the settings in<VAR> cupsd.conf</VAR> or in the<VAR>
4343  hosts.allow</VAR> or<VAR> hosts.deny</VAR> files used by TCP wrappers.
4344  Therefore, running <CODE>cups-lpd</CODE> on your server will allow any
4345  computer on your network (and perhaps the entire Internet) to print to
4346  your server.</P>
4347 <P>While <CODE>xinetd</CODE> has built-in access control support, you
4348  should use the TCP wrappers package with <CODE>inetd</CODE> to limit
4349  access to only those computers that should be able to print through
4350  your server.</P>
4351 </TD></TR>
4352 </TABLE>
4353 </CENTER>
4354 </P>
4355 <H2><A NAME="8_3">Printing to LPD Servers</A></H2>
4356 <P>CUPS provides the <CODE>lpd</CODE> backend for printing to LPD-based
4357  servers and printers. Use a device URI of <CODE>lpd://server/name</CODE>
4358  to print to a printer on an LPD server, where <CODE>server</CODE> is
4359  the hostname or IP address of the server and <CODE>name</CODE> is the
4360  queue name.</P>
4361 <P>Microsoft Windows NT provides an LPD service under the name &quot;TCP/IP
4362  Printing Services&quot;. To enable LPD printing on NT, open the &quot;Services&quot;
4363  control panel, select the &quot;TCP/IP Printing Services&quot; service, and click
4364  on the &quot;Start&quot; button. Any shared printer will then be available via
4365  the LPD protocol.</P>
4366 <H2><A NAME="8_4">Printing from Mac OS Clients</A></H2>
4367 <P>CUPS does not provide Mac OS support directly. However, there are
4368  several free and commercial software packages that do.</P>
4369 <H3><A NAME="8_4_1">Columbia Appletalk Package (CAP)</A></H3>
4370 <P>Because the CAP LaserWriter server (<CODE>lwsrv(8)</CODE>) does not
4371  support specification of PPD files, we do not recommend that you use
4372  CAP with CUPS. However, you can run the <CODE>lpsrv</CODE> program for
4373  limited printing with the command:</P>
4374 <UL>
4375 <PRE>
4376 lwsrv -n &quot;<I>Name</I>&quot; -p <I>printer</I> -a /usr/lib/adicts -f /usr/lib/LW+Fonts
4377 </PRE>
4378 </UL>
4379 <P>where <CODE>Name</CODE> is the name you want to use when sharing the
4380  printer, and <CODE>printer</CODE> is the name of the CUPS print queue.
4381 <!-- NEED 3in -->
4382 </P>
4383 <H3><A NAME="8_4_2">XINET KA/Spool</A></H3>
4384 <P>To use your system as a print server for Mac OS clients, configure
4385  each printer using a <CODE>papserver(8)</CODE> in the<VAR>
4386  /usr/adm/appletalk/services</VAR> file, specifying the corresponding
4387  PPD file in the<VAR> /etc/cups/ppd</VAR> directory for each printer.
4388  For a printer named <CODE>MyPrinter</CODE> the entry would look like:</P>
4389 <UL>
4390 <PRE>
4391 /usr/etc/appletalk/papserver -I -L -P /etc/cups/ppd/MyPrinter.ppd \
4392 &quot;Printer Description&quot; MyPrinter
4393 </PRE>
4394 </UL>
4395 <CENTER>
4396 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
4397 <TR><TD><B> NOTE:</B>
4398 <P>Enter the text above on a single line without the backslash (\)
4399  character.</P>
4400 </TD></TR>
4401 </TABLE>
4402 </CENTER>
4403 <H3><A NAME="8_4_3">NetATalk</A></H3>
4404 <P>To use your system as a print server for Mac OS clients, configure
4405  each printer in the<VAR> papd.conf</VAR> file, specifying the
4406  corresponding PPD file in the<VAR> /etc/cups/ppd</VAR> directory for
4407  each printer. For a printer named <CODE>MyPrinter</CODE> the entry
4408  would look like:</P>
4409 <UL>
4410 <PRE>
4411 Printer Description:MyPrinter@MyServer:\
4412 :pr=|/usr/bin/lp -d MyPrinter:\
4413 :op=daemon:\
4414 :pd=/etc/cups/ppd/MyPrinter.ppd:
4415 </PRE>
4416 </UL>
4417
4418 <!-- NEED 2in -->
4419 <H2><A NAME="8_5">Printing to Mac OS Servers</A></H2>
4420 <P>CUPS currently does not provide a backend to communicate with a Mac
4421  OS server. However, you can write and install a short shell script in
4422  the<VAR> /usr/lib/cups/backend</VAR> directory that sends a print file
4423  using the appropriate command. The following is a short script that
4424  will run the <CODE>papif</CODE> command provided with CAP.</P>
4425 <P>After copying this script to<VAR> /usr/lib/cups/backend/cap</VAR>,
4426  specify a device URI of <CODE>cap://server/printer</CODE> to use this
4427  backend with a print queue.
4428 <!-- NEED 8in -->
4429 </P>
4430 <UL>
4431 <PRE>
4432 <I>&quot;/usr/lib/cups/backend/cap&quot;</I>
4433 #!/bin/sh
4434 #
4435 # Usage: cap job user title copies options [filename]
4436 #
4437
4438 # No arguments means show available devices...
4439
4440 if test ${#argv} = 0; then
4441 echo &quot;network cap \&quot;Unknown\&quot; \&quot;Mac OS Printer via CAP\&quot;&quot;
4442 exit 0
4443 fi
4444
4445 # Collect arguments...
4446
4447 user=$2
4448 copies=$4
4449
4450 if test ${#argv} = 5; then
4451 # Get print file from stdin; copies have already been handled...
4452 file=/var/tmp/$$.prn
4453 copies=1
4454 cat &gt; $file
4455 else
4456 # Print file is on command-line...
4457 file=$6
4458 fi
4459
4460 # Create a dummy cap.printers file for this printer based
4461 # upon a device URI of &quot;cap://server/printer&quot;...
4462
4463 echo $PRINTER/$DEVICE_URI | \
4464 awk -F/ '{print $1 &quot;=&quot; $5 &quot;:LaserWriter@&quot; $4}' &gt; /var/tmp/$$.cap
4465
4466 CAPPRINTERS=/var/tmp/$$.cap; export CAPPRINTERS
4467
4468 # Send the file to the printer, once for each copy. This assumes that you
4469 # have properly initialized the cap.printers file...
4470
4471 while [ $copies -gt 0 ]; do
4472 papif -n $user &lt; $file
4473
4474 copies=`expr $copies - 1`
4475 done
4476
4477 # Remove any temporary files...
4478 if test ${#argv} = 5; then
4479 /bin/rm -f $file
4480 fi
4481
4482 /bin/rm -f /var/tmp/$$.cap
4483
4484 exit 0
4485 </PRE>
4486 </UL>
4487
4488 <!-- NEED 2in -->
4489 <H2><A NAME="8_6">Printing from Windows Clients</A></H2>
4490 <P>While CUPS does not provide Windows support directly, the free SAMBA
4491  software package does. SAMBA version 2.0.6 is the first release of
4492  SAMBA that supports CUPS. You can download SAMBA from:</P>
4493 <UL>
4494 <PRE>
4495 <A HREF="http://www.samba.org">http://www.samba.org</A>
4496 </PRE>
4497 </UL>
4498 <P>To configure SAMBA for CUPS, edit the<VAR> smb.conf</VAR> file and
4499  replace the existing printing commands and options with the line:</P>
4500 <UL>
4501 <PRE>
4502 printing = cups
4503 printcap name = cups
4504 </PRE>
4505 </UL>
4506 <P>That's all there is to it! Remote users will now be able to browse
4507  and print to printers on your system.</P>
4508 <H3><A NAME="8_6_1">Exporting Printer Drivers</A></H3>
4509 <P>You can optionally export printer drivers from your CUPS server using
4510  the <CODE>cupsaddsmb</CODE> command and the SAMBA 2.2.0 or higher
4511  software.</P>
4512 <P>Before you can export the printers you must download the current
4513  Adobe PostScript printer drivers from the Adobe web site (<A HREF="http://www.adobe.com/">
4514 http://www.adobe.com/</A>). Use the free <CODE>unzip</CODE> software to
4515  extract the files from the self-extracting ZIP file containing the
4516  drivers; you will need the following files:</P>
4517 <UL>
4518 <PRE>
4519 ADFONTS.MFM
4520 ADOBEPS4.DRV
4521 ADOBEPS4.HLP
4522 ADOBEPS5.DLL
4523 ADOBEPSU.DLL
4524 ADOBEPSU.HLP
4525 DEFPRTR2.PPD
4526 ICONLIB.DLL
4527 PSMON.DLL
4528 </PRE>
4529 </UL>
4530 <P>Copy these files to the<VAR> /usr/share/cups/drivers</VAR> directory
4531  - you may need to rename some of the files so the filenames are all
4532  UPPERCASE.</P>
4533 <P>Next, configure SAMBA (via the<VAR> smb.conf</VAR> file) to support
4534  printing through CUPS and provide a printer driver download share, as
4535  follows:</P>
4536 <UL>
4537 <PRE>
4538 [global]
4539 load printers = yes
4540 printing = cups
4541 printcap name = cups
4542
4543 [printers]
4544 comment = All Printers
4545 path = /var/spool/samba
4546 browseable = no
4547 public = yes
4548 guest ok = yes
4549 writable = no
4550 printable = yes
4551 printer admin = root
4552
4553 [print$]
4554 comment = Printer Drivers
4555 path = /etc/samba/drivers
4556 browseable = yes
4557 guest ok = no
4558 read only = yes
4559 write list = root
4560 </PRE>
4561 </UL>
4562 <P>This configuration assumes a FHS-compliant installation of SAMBA;
4563  adjust the [printers] and [print$] share paths accordingly on your
4564  system as needed. That is, the directory for your printer drivers can
4565  be anywhere on the system; just make sure it is writable by the users
4566  specified by the <CODE>write list</CODE> directive plus readable and
4567  executable by all users. Also, make sure that you have SAMBA passwords
4568  defined for each user in the <CODE>write list</CODE> using SAMBA's <CODE>
4569 smbpasswd(1)</CODE> command. Otherwise you will not be able to
4570  authenticate.</P>
4571 <P>Finally, run the <CODE>cupsaddsmb</CODE> command to export the
4572  printer drivers for one or more queues:</P>
4573 <UL>
4574 <PRE>
4575 <B>cupsaddsmb -U root printer1 ... printerN <I>ENTER</I></B>
4576 </PRE>
4577 </UL>
4578 <P>Running <CODE>cupsaddsmb</CODE> with the <CODE>-a</CODE> option will
4579  export all printers:</P>
4580 <UL>
4581 <PRE>
4582 <B>cupsaddsmb -U root -a <I>ENTER</I></B>
4583 </PRE>
4584 </UL>
4585 <P>Notice in the above examples that the user <CODE>root</CODE> was used
4586  which was defined in the <CODE>write list</CODE> of the<VAR> smb.conf</VAR>
4587  file.</P>
4588 <H2><A NAME="8_7">Printing to Windows Servers</A></H2>
4589 <P>CUPS can print to Windows servers in one of two ways. The first way
4590  uses the LPD protocol on the CUPS system and the &quot;TCP/IP Printing
4591  Services&quot; on the Windows system. You can find out more about this
4592  configuration in the<A HREF="#LPD"> LPD</A> section earlier in this
4593  chapter.</P>
4594 <P>The second way is through the Microsoft Server Message Block (&quot;SMB&quot;)
4595  protocol. Support for this protocol is provided with the free SAMBA
4596  software package. You can download SAMBA from:</P>
4597 <UL>
4598 <PRE>
4599 <A HREF="http://www.samba.org">http://www.samba.org</A>
4600 </PRE>
4601 </UL>
4602 <P>To configure CUPS for SAMBA, run the following command:</P>
4603 <UL>
4604 <PRE>
4605 <B>ln -s `which smbspool` /usr/lib/cups/backend/smb ENTER</B>
4606 </PRE>
4607 </UL>
4608 <P>The <CODE>smbspool(1)</CODE> program is provided with SAMBA starting
4609  with SAMBA 2.0.6. Once you have made the link you can configure your
4610  printers with one of the following device URIs:</P>
4611 <UL>
4612 <PRE>
4613 smb://workgroup/server/sharename
4614 smb://server/sharename
4615 smb://user:pass@workgroup/server/sharename
4616 smb://user:pass@server/sharename
4617 </PRE>
4618 </UL>
4619 <P>The <CODE>workgroup</CODE> name need only be specified if your system
4620  is using a different workgroup. The <CODE>user:pass</CODE> strings are
4621  required when printing to Windows NT servers or to shares with
4622  passwords enabled under Windows 95 and 98.</P>
4623 <H1 ALIGN="RIGHT"><A NAME="LICENSE">A - Software License Agreement</A></H1>
4624 <H2 ALIGN="CENTER"><A NAME="9_1">Common UNIX Printing System License
4625  Agreement</A></H2>
4626 <P ALIGN="CENTER">Copyright 1997-2002 by Easy Software Products
4627 <BR> 44141 AIRPORT VIEW DR STE 204
4628 <BR> HOLLYWOOD, MARYLAND 20636-3111 USA
4629 <BR>
4630 <BR> Voice: +1.301.373.9600
4631 <BR> Email:<A HREF="mailto:cups-info@cups.org"> cups-info@cups.org</A>
4632 <BR> WWW:<A HREF="http://www.cups.org"> http://www.cups.org</A></P>
4633 <H3><A NAME="9_1_1">Introduction</A></H3>
4634 <P>The Common UNIX Printing System<SUP>TM</SUP>, (&quot;CUPS<SUP>TM</SUP>&quot;),
4635  is provided under the GNU General Public License (&quot;GPL&quot;) and GNU
4636  Library General Public License (&quot;LGPL&quot;), Version 2, with exceptions for
4637  Apple operating systems and the OpenSSL toolkit. A copy of the
4638  exceptions and licenses follow this introduction.</P>
4639 <P>The GNU LGPL applies to the CUPS API library, located in the &quot;cups&quot;
4640  subdirectory of the CUPS source distribution and in the &quot;cups&quot; include
4641  directory and library files in the binary distributions. The GNU GPL
4642  applies to the remainder of the CUPS distribution, including the
4643  &quot;pdftops&quot; filter which is based upon Xpdf and the CUPS imaging library.</P>
4644 <P>For those not familiar with the GNU GPL, the license basically allows
4645  you to:</P>
4646 <UL>
4647 <LI>Use the CUPS software at no charge.</LI>
4648 <LI>Distribute verbatim copies of the software in source or binary form.</LI>
4649 <LI>Sell verbatim copies of the software for a media fee, or sell
4650  support for the software.</LI>
4651 <LI>Distribute or sell printer drivers and filters that use CUPS so long
4652  as source code is made available under the GPL.</LI>
4653 </UL>
4654 <P>What this license<B> does not</B> allow you to do is make changes or
4655  add features to CUPS and then sell a binary distribution without source
4656  code. You must provide source for any new drivers, changes, or
4657  additions to the software, and all code must be provided under the GPL
4658  or LGPL as appropriate. The only exceptions to this are the portions of
4659  the CUPS software covered by the Apple operating system license
4660  exceptions outlined later in this license agreement.</P>
4661 <P>The GNU LGPL relaxes the &quot;link-to&quot; restriction, allowing you to
4662  develop applications that use the CUPS API library under other licenses
4663  and/or conditions as appropriate for your application.</P>
4664 <H3><A NAME="9_1_2">License Exceptions</A></H3>
4665 <P>In addition, as the copyright holder of CUPS, Easy Software Products
4666  grants the following special exceptions:</P>
4667 <OL>
4668 <LI><B>Apple Operating System Development License Exception</B>;
4669 <OL TYPE="a">
4670 <LI>Software that is developed by any person or entity for an Apple
4671  Operating System (&quot;Apple OS-Developed Software&quot;), including but not
4672  limited to Apple and third party printer drivers, filters, and backends
4673  for an Apple Operating System, that is linked to the CUPS imaging
4674  library or based on any sample filters or backends provided with CUPS
4675  shall not be considered to be a derivative work or collective work
4676  based on the CUPS program and is exempt from the mandatory source code
4677  release clauses of the GNU GPL. You may therefore distribute linked
4678  combinations of the CUPS imaging library with Apple OS-Developed
4679  Software without releasing the source code of the Apple OS-Developed
4680  Software. You may also use sample filters and backends provided with
4681  CUPS to develop Apple OS-Developed Software without releasing the
4682  source code of the Apple OS-Developed Software.</LI>
4683 <LI>An Apple Operating System means any operating system software
4684  developed and/or marketed by Apple Computer, Inc., including but not
4685  limited to all existing releases and versions of Apple's Darwin, Mac OS
4686  X, and Mac OS X Server products and all follow-on releases and future
4687  versions thereof.</LI>
4688 <LI>This exception is only available for Apple OS-Developed Software and
4689  does not apply to software that is distributed for use on other
4690  operating systems.</LI>
4691 <LI>All CUPS software that falls under this license exception have the
4692  following text at the top of each source file:<BLOCKQUOTE>This file is
4693  subject to the Apple OS-Developed Software exception.</BLOCKQUOTE></LI>
4694 </OL>
4695 </LI>
4696 <LI><B>OpenSSL Toolkit License Exception</B>;
4697 <OL TYPE="a">
4698 <LI>Easy Software Products explicitly allows the compilation and
4699  distribution of the CUPS software with the OpenSSL Toolkit.</LI>
4700 </OL>
4701 </LI>
4702 </OL>
4703 <P>No developer is required to provide these exceptions in a derived
4704  work.</P>
4705 <H3><A NAME="9_1_3">Trademarks</A></H3>
4706 <P>Easy Software Products has trademarked the Common UNIX Printing
4707  System, CUPS, and CUPS logo. These names and logos may be used freely
4708  in any direct port or binary distribution of CUPS. Please contract Easy
4709  Software Products for written permission to use them in derivative
4710  products. Our intention is to protect the value of these trademarks and
4711  ensure that any derivative product meets the same high-quality
4712  standards as the original.</P>
4713 <H3><A NAME="9_1_4">Binary Distribution Rights</A></H3>
4714 <P>Easy Software Products also sells rights to the CUPS source code
4715  under a binary distribution license for vendors that are unable to
4716  release source code for their drivers, additions, and modifications to
4717  CUPS under the GNU GPL and LGPL. For information please contact us at
4718  the address shown above.</P>
4719 <P>The Common UNIX Printing System provides a &quot;pdftops&quot; filter that is
4720  based on the Xpdf software. For binary distribution licensing of this
4721  software, please contact:<BLOCKQUOTE> Derek B. Noonburg
4722 <BR> Email:<A HREF="mailto:derekn@foolabs.com"> derekn@foolabs.com</A>
4723 <BR> WWW:<A HREF="http://www.foolabs.com/xpdf/">
4724  http://www.foolabs.com/xpdf/</A></BLOCKQUOTE></P>
4725 <H3><A NAME="9_1_5">Support</A></H3>
4726 <P>Easy Software Products sells software support for CUPS as well as a
4727  commercial printing product based on CUPS called ESP Print Pro. You can
4728  find out more at our web site:</P>
4729 <UL>
4730 <PRE>
4731 <A HREF="http://www.easysw.com/">http://www.easysw.com/</A>
4732 </PRE>
4733 </UL>
4734
4735 <!-- NEW PAGE -->
4736 <H2><A NAME="9_2">GNU GENERAL PUBLIC LICENSE</A></H2>
4737 <P>Version 2, June 1991</P>
4738 <PRE>
4739 Copyright 1989, 1991 Free Software Foundation, Inc.
4740 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
4741
4742 Everyone is permitted to copy and distribute verbatim
4743 copies of this license document, but changing it is not allowed.
4744 </PRE>
4745 <H4>Preamble</H4>
4746 <P>The licenses for most software are designed to take away your freedom
4747  to share and change it. By contrast, the GNU General Public License is
4748  intended to guarantee your freedom to share and change free
4749  software--to make sure the software is free for all its users. This
4750  General Public License applies to most of the Free Software
4751  Foundation's software and to any other program whose authors commit to
4752  using it. (Some other Free Software Foundation software is covered by
4753  the GNU Library General Public License instead.) You can apply it to
4754  your programs, too.</P>
4755 <P>When we speak of free software, we are referring to freedom, not
4756  price. Our General Public Licenses are designed to make sure that you
4757  have the freedom to distribute copies of free software (and charge for
4758  this service if you wish), that you receive source code or can get it
4759  if you want it, that you can change the software or use pieces of it in
4760  new free programs; and that you know you can do these things.</P>
4761 <P>To protect your rights, we need to make restrictions that forbid
4762  anyone to deny you these rights or to ask you to surrender the rights.
4763  These restrictions translate to certain responsibilities for you if you
4764  distribute copies of the software, or if you modify it.</P>
4765 <P>For example, if you distribute copies of such a program, whether
4766  gratis or for a fee, you must give the recipients all the rights that
4767  you have. You must make sure that they, too, receive or can get the
4768  source code. And you must show them these terms so they know their
4769  rights.</P>
4770 <P>We protect your rights with two steps: (1) copyright the software,
4771  and (2) offer you this license which gives you legal permission to
4772  copy, distribute and/or modify the software.</P>
4773 <P>Also, for each author's protection and ours, we want to make certain
4774  that everyone understands that there is no warranty for this free
4775  software. If the software is modified by someone else and passed on, we
4776  want its recipients to know that what they have is not the original, so
4777  that any problems introduced by others will not reflect on the original
4778  authors' reputations.</P>
4779 <P>Finally, any free program is threatened constantly by software
4780  patents. We wish to avoid the danger that redistributors of a free
4781  program will individually obtain patent licenses, in effect making the
4782  program proprietary. To prevent this, we have made it clear that any
4783  patent must be licensed for everyone's free use or not licensed at all.</P>
4784 <P>The precise terms and conditions for copying, distribution and
4785  modification follow.</P>
4786 <H4>GNU GENERAL PUBLIC LICENSE
4787 <BR> TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</H4>
4788 <OL START="0">
4789 <LI>This License applies to any program or other work which contains a
4790  notice placed by the copyright holder saying it may be distributed
4791  under the terms of this General Public License. The &quot;Program&quot;, below,
4792  refers to any such program or work, and a &quot;work based on the Program&quot;
4793  means either the Program or any derivative work under copyright law:
4794  that is to say, a work containing the Program or a portion of it,
4795  either verbatim or with modifications and/or translated into another
4796  language. (Hereinafter, translation is included without limitation in
4797  the term &quot;modification&quot;.) Each licensee is addressed as &quot;you&quot;.
4798 <P>Activities other than copying, distribution and modification are not
4799  covered by this License; they are outside its scope. The act of running
4800  the Program is not restricted, and the output from the Program is
4801  covered only if its contents constitute a work based on the Program
4802  (independent of having been made by running the Program). Whether that
4803  is true depends on what the Program does.</P>
4804 <LI>You may copy and distribute verbatim copies of the Program's source
4805  code as you receive it, in any medium, provided that you conspicuously
4806  and appropriately publish on each copy an appropriate copyright notice
4807  and disclaimer of warranty; keep intact all the notices that refer to
4808  this License and to the absence of any warranty; and give any other
4809  recipients of the Program a copy of this License along with the
4810  Program.
4811 <P>You may charge a fee for the physical act of transferring a copy, and
4812  you may at your option offer warranty protection in exchange for a fee.</P>
4813 <LI>You may modify your copy or copies of the Program or any portion of
4814  it, thus forming a work based on the Program, and copy and distribute
4815  such modifications or work under the terms of Section 1 above, provided
4816  that you also meet all of these conditions:
4817 <OL TYPE="a">
4818 <LI>You must cause the modified files to carry prominent notices stating
4819  that you changed the files and the date of any change.</LI>
4820 <LI>You must cause any work that you distribute or publish, that in
4821  whole or in part contains or is derived from the Program or any part
4822  thereof, to be licensed as a whole at no charge to all third parties
4823  under the terms of this License.</LI>
4824 <LI>if the modified program normally reads commands interactively when
4825  run, you must cause it, when started running for such interactive use
4826  in the most ordinary way, to print or display an announcement including
4827  an appropriate copyright notice and a notice that there is no warranty
4828  (or else, saying that you provide a warranty) and that users may
4829  redistribute the program under these conditions, and telling the user
4830  how to view a copy of this License. (Exception: if the Program itself
4831  is interactive but does not normally print such an announcement, your
4832  work based on the Program is not required to print an announcement.)</LI>
4833 </OL>
4834 <P>These requirements apply to the modified work as a whole. If
4835  identifiable sections of that work are not derived from the Program,
4836  and can be reasonably considered independent and separate works in
4837  themselves, then this License, and its terms, do not apply to those
4838  sections when you distribute them as separate works. But when you
4839  distribute the same sections as part of a whole which is a work based
4840  on the Program, the distribution of the whole must be on the terms of
4841  this License, whose permissions for other licensees extend to the
4842  entire whole, and thus to each and every part regardless of who wrote
4843  it.</P>
4844 <P>Thus, it is not the intent of this section to claim rights or contest
4845  your rights to work written entirely by you; rather, the intent is to
4846  exercise the right to control the distribution of derivative or
4847  collective works based on the Program.</P>
4848 <P>In addition, mere aggregation of another work not based on the
4849  Program with the Program (or with a work based on the Program) on a
4850  volume of a storage or distribution medium does not bring the other
4851  work under the scope of this License.</P>
4852 <LI>You may copy and distribute the Program (or a work based on it,
4853  under Section 2) in object code or executable form under the terms of
4854  Sections 1 and 2 above provided that you also do one of the following:
4855 <OL TYPE="a">
4856 <LI>Accompany it with the complete corresponding machine-readable source
4857  code, which must be distributed under the terms of Sections 1 and 2
4858  above on a medium customarily used for software interchange; or,</LI>
4859 <LI>Accompany it with a written offer, valid for at least three years,
4860  to give any third party, for a charge no more than your cost of
4861  physically performing source distribution, a complete machine-readable
4862  copy of the corresponding source code, to be distributed under the
4863  terms of Sections 1 and 2 above on a medium customarily used for
4864  software interchange; or,</LI>
4865 <LI>Accompany it with the information you received as to the offer to
4866  distribute corresponding source code. (This alternative is allowed only
4867  for noncommercial distribution and only if you received the program in
4868  object code or executable form with such an offer, in accord with
4869  Subsection b above.)</LI>
4870 </OL>
4871 <P>The source code for a work means the preferred form of the work for
4872  making modifications to it. For an executable work, complete source
4873  code means all the source code for all modules it contains, plus any
4874  associated interface definition files, plus the scripts used to control
4875  compilation and installation of the executable. However, as a special
4876  exception, the source code distributed need not include anything that
4877  is normally distributed (in either source or binary form) with the
4878  major components (compiler, kernel, and so on) of the operating system
4879  on which the executable runs, unless that component itself accompanies
4880  the executable.</P>
4881 <P>If distribution of executable or object code is made by offering
4882  access to copy from a designated place, then offering equivalent access
4883  to copy the source code from the same place counts as distribution of
4884  the source code, even though third parties are not compelled to copy
4885  the source along with the object code.</P>
4886 <LI>You may not copy, modify, sublicense, or distribute the Program
4887  except as expressly provided under this License. Any attempt otherwise
4888  to copy, modify, sublicense or distribute the Program is void, and will
4889  automatically terminate your rights under this License. However,
4890  parties who have received copies, or rights, from you under this
4891  License will not have their licenses terminated so long as such parties
4892  remain in full compliance.</LI>
4893 <LI>You are not required to accept this License, since you have not
4894  signed it. However, nothing else grants you permission to modify or
4895  distribute the Program or its derivative works. These actions are
4896  prohibited by law if you do not accept this License. Therefore, by
4897  modifying or distributing the Program (or any work based on the
4898  Program), you indicate your acceptance of this License to do so, and
4899  all its terms and conditions for copying, distributing or modifying the
4900  Program or works based on it.</LI>
4901 <LI>Each time you redistribute the Program (or any work based on the
4902  Program), the recipient automatically receives a license from the
4903  original licensor to copy, distribute or modify the Program subject to
4904  these terms and conditions. You may not impose any further restrictions
4905  on the recipients' exercise of the rights granted herein. You are not
4906  responsible for enforcing compliance by third parties to this License.</LI>
4907 <LI>If, as a consequence of a court judgment or allegation of patent
4908  infringement or for any other reason (not limited to patent issues),
4909  conditions are imposed on you (whether by court order, agreement or
4910  otherwise) that contradict the conditions of this License, they do not
4911  excuse you from the conditions of this License. If you cannot
4912  distribute so as to satisfy simultaneously your obligations under this
4913  License and any other pertinent obligations, then as a consequence you
4914  may not distribute the Program at all. For example, if a patent license
4915  would not permit royalty-free redistribution of the Program by all
4916  those who receive copies directly or indirectly through you, then the
4917  only way you could satisfy both it and this License would be to refrain
4918  entirely from distribution of the Program.
4919 <P>If any portion of this section is held invalid or unenforceable under
4920  any particular circumstance, the balance of the section is intended to
4921  apply and the section as a whole is intended to apply in other
4922  circumstances.</P>
4923 <P>It is not the purpose of this section to induce you to infringe any
4924  patents or other property right claims or to contest validity of any
4925  such claims; this section has the sole purpose of protecting the
4926  integrity of the free software distribution system, which is
4927  implemented by public license practices. Many people have made generous
4928  contributions to the wide range of software distributed through that
4929  system in reliance on consistent application of that system; it is up
4930  to the author/donor to decide if he or she is willing to distribute
4931  software through any other system and a licensee cannot impose that
4932  choice.</P>
4933 <P>This section is intended to make thoroughly clear what is believed to
4934  be a consequence of the rest of this License.</P>
4935 <LI>If the distribution and/or use of the Program is restricted in
4936  certain countries either by patents or by copyrighted interfaces, the
4937  original copyright holder who places the Program under this License may
4938  add an explicit geographical distribution limitation excluding those
4939  countries, so that distribution is permitted only in or among countries
4940  not thus excluded. In such case, this License incorporates the
4941  limitation as if written in the body of this License.</LI>
4942 <LI>The Free Software Foundation may publish revised and/or new versions
4943  of the General Public License from time to time. Such new versions will
4944  be similar in spirit to the present version, but may differ in detail
4945  to address new problems or concerns.
4946 <P>Each version is given a distinguishing version number. If the Program
4947  specifies a version number of this License which applies to it and &quot;any
4948  later version&quot;, you have the option of following the terms and
4949  conditions either of that version or of any later version published by
4950  the Free Software Foundation. If the Program does not specify a version
4951  number of this License, you may choose any version ever published by
4952  the Free Software Foundation.</P>
4953 <LI>If you wish to incorporate parts of the Program into other free
4954  programs whose distribution conditions are different, write to the
4955  author to ask for permission. For software which is copyrighted by the
4956  Free Software Foundation, write to the Free Software Foundation; we
4957  sometimes make exceptions for this. Our decision will be guided by the
4958  two goals of preserving the free status of all derivatives of our free
4959  software and of promoting the sharing and reuse of software generally.</LI>
4960 </LI>
4961 </LI>
4962 </LI>
4963 </LI>
4964 </LI>
4965 </LI>
4966 </OL>
4967 <H4>NO WARRANTY</H4>
4968 <OL START="11">
4969 <LI>BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
4970  FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
4971  OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
4972  PROVIDE THE PROGRAM &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER
4973  EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
4974  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
4975  ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
4976  YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
4977  NECESSARY SERVICING, REPAIR OR CORRECTION.</LI>
4978 <LI>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
4979  WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
4980  AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
4981  FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
4982  CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
4983  PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
4984  RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
4985  FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
4986  SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
4987  DAMAGES.</LI>
4988 </OL>
4989 <H4>END OF TERMS AND CONDITIONS</H4>
4990
4991 <!-- NEW PAGE -->
4992 <H2><A NAME="9_3">GNU LIBRARY GENERAL PUBLIC LICENSE</A></H2>
4993 <P>Version 2, June 1991</P>
4994 <PRE>
4995 Copyright (C) 1991 Free Software Foundation, Inc.
4996 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
4997 Everyone is permitted to copy and distribute verbatim copies
4998 of this license document, but changing it is not allowed.
4999
5000 [This is the first released version of the library GPL.  It is
5001  numbered 2 because it goes with version 2 of the ordinary GPL.]
5002 </PRE>
5003 <H4>Preamble</H4>
5004 <P>The licenses for most software are designed to take away your freedom
5005  to share and change it. By contrast, the GNU General Public Licenses
5006  are intended to guarantee your freedom to share and change free
5007  software--to make sure the software is free for all its users.</P>
5008 <P>This license, the Library General Public License, applies to some
5009  specially designated Free Software Foundation software, and to any
5010  other libraries whose authors decide to use it. You can use it for your
5011  libraries, too.</P>
5012 <P>When we speak of free software, we are referring to freedom, not
5013  price. Our General Public Licenses are designed to make sure that you
5014  have the freedom to distribute copies of free software (and charge for
5015  this service if you wish), that you receive source code or can get it
5016  if you want it, that you can change the software or use pieces of it in
5017  new free programs; and that you know you can do these things.</P>
5018 <P>To protect your rights, we need to make restrictions that forbid
5019  anyone to deny you these rights or to ask you to surrender the rights.
5020  These restrictions translate to certain responsibilities for you if you
5021  distribute copies of the library, or if you modify it.</P>
5022 <P>For example, if you distribute copies of the library, whether gratis
5023  or for a fee, you must give the recipients all the rights that we gave
5024  you. You must make sure that they, too, receive or can get the source
5025  code. If you link a program with the library, you must provide complete
5026  object files to the recipients so that they can relink them with the
5027  library, after making changes to the library and recompiling it. And
5028  you must show them these terms so they know their rights.</P>
5029 <P>Our method of protecting your rights has two steps: (1) copyright the
5030  library, and (2) offer you this license which gives you legal
5031  permission to copy, distribute and/or modify the library.</P>
5032 <P>Also, for each distributor's protection, we want to make certain that
5033  everyone understands that there is no warranty for this free library.
5034  If the library is modified by someone else and passed on, we want its
5035  recipients to know that what they have is not the original version, so
5036  that any problems introduced by others will not reflect on the original
5037  authors' reputations.</P>
5038 <P>Finally, any free program is threatened constantly by software
5039  patents. We wish to avoid the danger that companies distributing free
5040  software will individually obtain patent licenses, thus in effect
5041  transforming the program into proprietary software. To prevent this, we
5042  have made it clear that any patent must be licensed for everyone's free
5043  use or not licensed at all.</P>
5044 <P>Most GNU software, including some libraries, is covered by the
5045  ordinary GNU General Public License, which was designed for utility
5046  programs. This license, the GNU Library General Public License, applies
5047  to certain designated libraries. This license is quite different from
5048  the ordinary one; be sure to read it in full, and don't assume that
5049  anything in it is the same as in the ordinary license.</P>
5050 <P>The reason we have a separate public license for some libraries is
5051  that they blur the distinction we usually make between modifying or
5052  adding to a program and simply using it. Linking a program with a
5053  library, without changing the library, is in some sense simply using
5054  the library, and is analogous to running a utility program or
5055  application program. However, in a textual and legal sense, the linked
5056  executable is a combined work, a derivative of the original library,
5057  and the ordinary General Public License treats it as such.</P>
5058 <P>Because of this blurred distinction, using the ordinary General
5059  Public License for libraries did not effectively promote software
5060  sharing, because most developers did not use the libraries. We
5061  concluded that weaker conditions might promote sharing better.</P>
5062 <P>However, unrestricted linking of non-free programs would deprive the
5063  users of those programs of all benefit from the free status of the
5064  libraries themselves. This Library General Public License is intended
5065  to permit developers of non-free programs to use free libraries, while
5066  preserving your freedom as a user of such programs to change the free
5067  libraries that are incorporated in them. (We have not seen how to
5068  achieve this as regards changes in header files, but we have achieved
5069  it as regards changes in the actual functions of the Library.) The hope
5070  is that this will lead to faster development of free libraries.</P>
5071 <P>The precise terms and conditions for copying, distribution and
5072  modification follow. Pay close attention to the difference between a
5073  &quot;work based on the library&quot; and a &quot;work that uses the library&quot;. The
5074  former contains code derived from the library, while the latter only
5075  works together with the library.</P>
5076 <P>Note that it is possible for a library to be covered by the ordinary
5077  General Public License rather than by this special one.</P>
5078 <H4>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</H4>
5079 <P><STRONG>0.</STRONG> This License Agreement applies to any software
5080  library which contains a notice placed by the copyright holder or other
5081  authorized party saying it may be distributed under the terms of this
5082  Library General Public License (also called &quot;this License&quot;). Each
5083  licensee is addressed as &quot;you&quot;.</P>
5084 <P>A &quot;library&quot; means a collection of software functions and/or data
5085  prepared so as to be conveniently linked with application programs
5086  (which use some of those functions and data) to form executables.</P>
5087 <P>The &quot;Library&quot;, below, refers to any such software library or work
5088  which has been distributed under these terms. A &quot;work based on the
5089  Library&quot; means either the Library or any derivative work under
5090  copyright law: that is to say, a work containing the Library or a
5091  portion of it, either verbatim or with modifications and/or translated
5092  straightforwardly into another language. (Hereinafter, translation is
5093  included without limitation in the term &quot;modification&quot;.)</P>
5094 <P>&quot;Source code&quot; for a work means the preferred form of the work for
5095  making modifications to it. For a library, complete source code means
5096  all the source code for all modules it contains, plus any associated
5097  interface definition files, plus the scripts used to control
5098  compilation and installation of the library.</P>
5099 <P>Activities other than copying, distribution and modification are not
5100  covered by this License; they are outside its scope. The act of running
5101  a program using the Library is not restricted, and output from such a
5102  program is covered only if its contents constitute a work based on the
5103  Library (independent of the use of the Library in a tool for writing
5104  it). Whether that is true depends on what the Library does and what the
5105  program that uses the Library does.</P>
5106 <P><STRONG>1.</STRONG> You may copy and distribute verbatim copies of
5107  the Library's complete source code as you receive it, in any medium,
5108  provided that you conspicuously and appropriately publish on each copy
5109  an appropriate copyright notice and disclaimer of warranty; keep intact
5110  all the notices that refer to this License and to the absence of any
5111  warranty; and distribute a copy of this License along with the Library.</P>
5112 <P>You may charge a fee for the physical act of transferring a copy, and
5113  you may at your option offer warranty protection in exchange for a fee.</P>
5114 <P><STRONG>2.</STRONG> You may modify your copy or copies of the Library
5115  or any portion of it, thus forming a work based on the Library, and
5116  copy and distribute such modifications or work under the terms of
5117  Section 1 above, provided that you also meet all of these conditions:</P>
5118 <OL TYPE="a">
5119 <LI>The modified work must itself be a software library.
5120 <P></P>
5121 <LI>You must cause the files modified to carry prominent notices stating
5122  that you changed the files and the date of any change.
5123 <P></P>
5124 <LI>You must cause the whole of the work to be licensed at no charge to
5125  all third parties under the terms of this License.
5126 <P></P>
5127 <LI>If a facility in the modified Library refers to a function or a
5128  table of data to be supplied by an application program that uses the
5129  facility, other than as an argument passed when the facility is
5130  invoked, then you must make a good faith effort to ensure that, in the
5131  event an application does not supply such function or table, the
5132  facility still operates, and performs whatever part of its purpose
5133  remains meaningful.
5134 <P>(For example, a function in a library to compute square roots has a
5135  purpose that is entirely well-defined independent of the application.
5136  Therefore, Subsection 2d requires that any application-supplied
5137  function or table used by this function must be optional: if the
5138  application does not supply it, the square root function must still
5139  compute square roots.)</P>
5140 </LI>
5141 </LI>
5142 </LI>
5143 </LI>
5144 </OL>
5145 <P>These requirements apply to the modified work as a whole. If
5146  identifiable sections of that work are not derived from the Library,
5147  and can be reasonably considered independent and separate works in
5148  themselves, then this License, and its terms, do not apply to those
5149  sections when you distribute them as separate works. But when you
5150  distribute the same sections as part of a whole which is a work based
5151  on the Library, the distribution of the whole must be on the terms of
5152  this License, whose permissions for other licensees extend to the
5153  entire whole, and thus to each and every part regardless of who wrote
5154  it.</P>
5155 <P>Thus, it is not the intent of this section to claim rights or contest
5156  your rights to work written entirely by you; rather, the intent is to
5157  exercise the right to control the distribution of derivative or
5158  collective works based on the Library.</P>
5159 <P>In addition, mere aggregation of another work not based on the
5160  Library with the Library (or with a work based on the Library) on a
5161  volume of a storage or distribution medium does not bring the other
5162  work under the scope of this License.</P>
5163 <P><STRONG>3.</STRONG> You may opt to apply the terms of the ordinary
5164  GNU General Public License instead of this License to a given copy of
5165  the Library. To do this, you must alter all the notices that refer to
5166  this License, so that they refer to the ordinary GNU General Public
5167  License, version 2, instead of to this License. (If a newer version
5168  than version 2 of the ordinary GNU General Public License has appeared,
5169  then you can specify that version instead if you wish.) Do not make any
5170  other change in these notices.</P>
5171 <P>Once this change is made in a given copy, it is irreversible for that
5172  copy, so the ordinary GNU General Public License applies to all
5173  subsequent copies and derivative works made from that copy.</P>
5174 <P>This option is useful when you wish to copy part of the code of the
5175  Library into a program that is not a library.</P>
5176 <P><STRONG>4.</STRONG> You may copy and distribute the Library (or a
5177  portion or derivative of it, under Section 2) in object code or
5178  executable form under the terms of Sections 1 and 2 above provided that
5179  you accompany it with the complete corresponding machine-readable
5180  source code, which must be distributed under the terms of Sections 1
5181  and 2 above on a medium customarily used for software interchange.</P>
5182 <P>If distribution of object code is made by offering access to copy
5183  from a designated place, then offering equivalent access to copy the
5184  source code from the same place satisfies the requirement to distribute
5185  the source code, even though third parties are not compelled to copy
5186  the source along with the object code.</P>
5187 <P><STRONG>5.</STRONG> A program that contains no derivative of any
5188  portion of the Library, but is designed to work with the Library by
5189  being compiled or linked with it, is called a &quot;work that uses the
5190  Library&quot;. Such a work, in isolation, is not a derivative work of the
5191  Library, and therefore falls outside the scope of this License.</P>
5192 <P>However, linking a &quot;work that uses the Library&quot; with the Library
5193  creates an executable that is a derivative of the Library (because it
5194  contains portions of the Library), rather than a &quot;work that uses the
5195  library&quot;. The executable is therefore covered by this License. Section
5196  6 states terms for distribution of such executables.</P>
5197 <P>When a &quot;work that uses the Library&quot; uses material from a header file
5198  that is part of the Library, the object code for the work may be a
5199  derivative work of the Library even though the source code is not.
5200  Whether this is true is especially significant if the work can be
5201  linked without the Library, or if the work is itself a library. The
5202  threshold for this to be true is not precisely defined by law.</P>
5203 <P>If such an object file uses only numerical parameters, data structure
5204  layouts and accessors, and small macros and small inline functions (ten
5205  lines or less in length), then the use of the object file is
5206  unrestricted, regardless of whether it is legally a derivative work.
5207  (Executables containing this object code plus portions of the Library
5208  will still fall under Section 6.)</P>
5209 <P>Otherwise, if the work is a derivative of the Library, you may
5210  distribute the object code for the work under the terms of Section 6.
5211  Any executables containing that work also fall under Section 6, whether
5212  or not they are linked directly with the Library itself.</P>
5213 <P><STRONG>6.</STRONG> As an exception to the Sections above, you may
5214  also compile or link a &quot;work that uses the Library&quot; with the Library to
5215  produce a work containing portions of the Library, and distribute that
5216  work under terms of your choice, provided that the terms permit
5217  modification of the work for the customer's own use and reverse
5218  engineering for debugging such modifications.</P>
5219 <P>You must give prominent notice with each copy of the work that the
5220  Library is used in it and that the Library and its use are covered by
5221  this License. You must supply a copy of this License. If the work
5222  during execution displays copyright notices, you must include the
5223  copyright notice for the Library among them, as well as a reference
5224  directing the user to the copy of this License. Also, you must do one
5225  of these things:</P>
5226 <OL TYPE="a">
5227 <LI>Accompany the work with the complete corresponding machine-readable
5228  source code for the Library including whatever changes were used in the
5229  work (which must be distributed under Sections 1 and 2 above); and, if
5230  the work is an executable linked with the Library, with the complete
5231  machine-readable &quot;work that uses the Library&quot;, as object code and/or
5232  source code, so that the user can modify the Library and then relink to
5233  produce a modified executable containing the modified Library. (It is
5234  understood that the user who changes the contents of definitions files
5235  in the Library will not necessarily be able to recompile the
5236  application to use the modified definitions.)
5237 <P></P>
5238 <LI>Accompany the work with a written offer, valid for at least three
5239  years, to give the same user the materials specified in Subsection 6a,
5240  above, for a charge no more than the cost of performing this
5241  distribution.
5242 <P></P>
5243 <LI>If distribution of the work is made by offering access to copy from
5244  a designated place, offer equivalent access to copy the above specified
5245  materials from the same place.
5246 <P></P>
5247 <LI>Verify that the user has already received a copy of these materials
5248  or that you have already sent this user a copy.</LI>
5249 </LI>
5250 </LI>
5251 </LI>
5252 </OL>
5253 <P>For an executable, the required form of the &quot;work that uses the
5254  Library&quot; must include any data and utility programs needed for
5255  reproducing the executable from it. However, as a special exception,
5256  the source code distributed need not include anything that is normally
5257  distributed (in either source or binary form) with the major components
5258  (compiler, kernel, and so on) of the operating system on which the
5259  executable runs, unless that component itself accompanies the
5260  executable.</P>
5261 <P>It may happen that this requirement contradicts the license
5262  restrictions of other proprietary libraries that do not normally
5263  accompany the operating system. Such a contradiction means you cannot
5264  use both them and the Library together in an executable that you
5265  distribute.</P>
5266 <P><STRONG>7.</STRONG> You may place library facilities that are a work
5267  based on the Library side-by-side in a single library together with
5268  other library facilities not covered by this License, and distribute
5269  such a combined library, provided that the separate distribution of the
5270  work based on the Library and of the other library facilities is
5271  otherwise permitted, and provided that you do these two things:</P>
5272 <OL TYPE="a">
5273 <LI>Accompany the combined library with a copy of the same work based on
5274  the Library, uncombined with any other library facilities. This must be
5275  distributed under the terms of the Sections above.
5276 <P></P>
5277 <LI>Give prominent notice with the combined library of the fact that
5278  part of it is a work based on the Library, and explaining where to find
5279  the accompanying uncombined form of the same work.</LI>
5280 </LI>
5281 </OL>
5282 <P><STRONG>8.</STRONG> You may not copy, modify, sublicense, link with,
5283  or distribute the Library except as expressly provided under this
5284  License. Any attempt otherwise to copy, modify, sublicense, link with,
5285  or distribute the Library is void, and will automatically terminate
5286  your rights under this License. However, parties who have received
5287  copies, or rights, from you under this License will not have their
5288  licenses terminated so long as such parties remain in full compliance.</P>
5289 <P><STRONG>9.</STRONG> You are not required to accept this License,
5290  since you have not signed it. However, nothing else grants you
5291  permission to modify or distribute the Library or its derivative works.
5292  These actions are prohibited by law if you do not accept this License.
5293  Therefore, by modifying or distributing the Library (or any work based
5294  on the Library), you indicate your acceptance of this License to do so,
5295  and all its terms and conditions for copying, distributing or modifying
5296  the Library or works based on it.</P>
5297 <P><STRONG>10.</STRONG> Each time you redistribute the Library (or any
5298  work based on the Library), the recipient automatically receives a
5299  license from the original licensor to copy, distribute, link with or
5300  modify the Library subject to these terms and conditions. You may not
5301  impose any further restrictions on the recipients' exercise of the
5302  rights granted herein. You are not responsible for enforcing compliance
5303  by third parties to this License.</P>
5304 <P><STRONG>11.</STRONG> If, as a consequence of a court judgment or
5305  allegation of patent infringement or for any other reason (not limited
5306  to patent issues), conditions are imposed on you (whether by court
5307  order, agreement or otherwise) that contradict the conditions of this
5308  License, they do not excuse you from the conditions of this License. If
5309  you cannot distribute so as to satisfy simultaneously your obligations
5310  under this License and any other pertinent obligations, then as a
5311  consequence you may not distribute the Library at all. For example, if
5312  a patent license would not permit royalty-free redistribution of the
5313  Library by all those who receive copies directly or indirectly through
5314  you, then the only way you could satisfy both it and this License would
5315  be to refrain entirely from distribution of the Library.</P>
5316 <P>If any portion of this section is held invalid or unenforceable under
5317  any particular circumstance, the balance of the section is intended to
5318  apply, and the section as a whole is intended to apply in other
5319  circumstances.</P>
5320 <P>It is not the purpose of this section to induce you to infringe any
5321  patents or other property right claims or to contest validity of any
5322  such claims; this section has the sole purpose of protecting the
5323  integrity of the free software distribution system which is implemented
5324  by public license practices. Many people have made generous
5325  contributions to the wide range of software distributed through that
5326  system in reliance on consistent application of that system; it is up
5327  to the author/donor to decide if he or she is willing to distribute
5328  software through any other system and a licensee cannot impose that
5329  choice.</P>
5330 <P>This section is intended to make thoroughly clear what is believed to
5331  be a consequence of the rest of this License.</P>
5332 <P><STRONG>12.</STRONG> If the distribution and/or use of the Library is
5333  restricted in certain countries either by patents or by copyrighted
5334  interfaces, the original copyright holder who places the Library under
5335  this License may add an explicit geographical distribution limitation
5336  excluding those countries, so that distribution is permitted only in or
5337  among countries not thus excluded. In such case, this License
5338  incorporates the limitation as if written in the body of this License.</P>
5339 <P><STRONG>13.</STRONG> The Free Software Foundation may publish revised
5340  and/or new versions of the Library General Public License from time to
5341  time. Such new versions will be similar in spirit to the present
5342  version, but may differ in detail to address new problems or concerns.</P>
5343 <P>Each version is given a distinguishing version number. If the Library
5344  specifies a version number of this License which applies to it and &quot;any
5345  later version&quot;, you have the option of following the terms and
5346  conditions either of that version or of any later version published by
5347  the Free Software Foundation. If the Library does not specify a license
5348  version number, you may choose any version ever published by the Free
5349  Software Foundation.</P>
5350 <P><STRONG>14.</STRONG> If you wish to incorporate parts of the Library
5351  into other free programs whose distribution conditions are incompatible
5352  with these, write to the author to ask for permission. For software
5353  which is copyrighted by the Free Software Foundation, write to the Free
5354  Software Foundation; we sometimes make exceptions for this. Our
5355  decision will be guided by the two goals of preserving the free status
5356  of all derivatives of our free software and of promoting the sharing
5357  and reuse of software generally.</P>
5358 <P><STRONG>NO WARRANTY</STRONG></P>
5359 <P><STRONG>15.</STRONG> BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE,
5360  THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY
5361  APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
5362  HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY &quot;AS IS&quot; WITHOUT
5363  WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
5364  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
5365  PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
5366  OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU
5367  ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.</P>
5368 <P><STRONG>16.</STRONG> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR
5369  AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO
5370  MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
5371  LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL
5372  OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
5373  LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
5374  RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
5375  FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
5376  SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
5377  DAMAGES.</P>
5378 <H4>END OF TERMS AND CONDITIONS</H4>
5379 <H1 ALIGN="RIGHT"><A NAME="COMMON_NETWORK">B - Common Network Settings</A>
5380 </H1>
5381 <P>This appendix covers many of the popular TCP/IP network interfaces
5382  and printer servers available on the market today.</P>
5383 <H2><A NAME="10_1">Configuring a Network Interface</A></H2>
5384 <P>When you first install a network printer or print server on your LAN,
5385  you need to set the Internet Protocol (&quot;IP&quot;) address. On most
5386  higher-end &quot;workgroup&quot; printers, you can set the address through the
5387  printer control panel. However, in most cases you will want to assign
5388  the addresses remotely from your workstation. This makes administration
5389  a bit easier and avoids assigning duplicate addresses accidentally.</P>
5390 <P>To setup your printer or print server for remote address assignment,
5391  you'll need the Ethernet Media Access Control (&quot;MAC&quot;) address, also
5392  sometimes called a node address, and the IP address you want to use for
5393  the device. The Ethernet MAC address can often be found on the printer
5394  test page or bottom of the print server.
5395 <!-- NEED 3in -->
5396 </P>
5397 <H3><A NAME="10_1_1">Configuring the IP Address Using ARP</A></H3>
5398 <P>The easiest way to set the IP address of a network device is to use
5399  the <CODE>arp(8)</CODE> command. The <CODE>arp</CODE> sends an Address
5400  Resolution Protocol (&quot;ARP&quot;) packet to the specified Ethernet MAC
5401  address, setting the network device's IP address:</P>
5402 <UL>
5403 <PRE>
5404 <B>arp -s ip-address ethernet-address ENTER</B>
5405 <B>arp -s host.domain.com 08:00:69:00:12:34 ENTER</B>
5406 <B>arp -s 192.0.2.2 08:00:69:00:12:34 ENTER</B>
5407 </PRE>
5408 </UL>
5409 <H3><A NAME="10_1_2">Configuring the IP Address Using RARP</A></H3>
5410 <P>The most flexible way to remotely assign IP addresses under UNIX is
5411  through the Reverse Address Resolution Protocol (&quot;RARP&quot;). RARP allows a
5412  network device to request an IP address using its Ethernet MAC address,
5413  and one or more RARP servers on the network will respond with an ARP
5414  packet with the IP address the device can use.</P>
5415 <P>RARP should be used when you have to manage many printers or print
5416  servers, or when you have a network device that does not remember its
5417  IP address after a power cycle. If you just have a single printer or
5418  print server, the <CODE>arp</CODE> command is the way to go.</P>
5419 <P>Some UNIX operating systems use a program called <CODE>rarpd(8)</CODE>
5420  to manage RARP. Others, like Linux, support this protocol in the
5421  kernel. For systems that provide the <CODE>rarpd</CODE> program you
5422  will need to start it before RARP lookups will work:</P>
5423 <UL>
5424 <PRE>
5425 <B>rarpd ENTER</B>
5426 </PRE>
5427 </UL>
5428 <P>Under IRIX you can enable this functionality by default using:</P>
5429 <UL>
5430 <PRE>
5431 <B>chkconfig rarpd on ENTER</B>
5432 </PRE>
5433 </UL>
5434 <P>Both the <CODE>rarpd</CODE> program and kernel RARP support read a
5435  list of Ethernet and IP addresses from the file<VAR> /etc/ethers</VAR>.
5436  Each line contains the Ethernet address (colon delimited) followed by
5437  an IP address or hostname like:</P>
5438 <UL>
5439 <PRE>
5440 08:00:69:00:12:34 myprinter.mydomain.com
5441 08:00:69:00:12:34 192.0.2.2
5442 </PRE>
5443 </UL>
5444 <P>Add a line to this file and cycle the power on the printer or print
5445  server to set its address.
5446 <!-- NEED 2in -->
5447 </P>
5448 <H3><A NAME="10_1_3">Configuring the IP Address Using BOOTP</A></H3>
5449 <P>The BOOTP protocol is used when you need to provide additional
5450  information such as the location of a configuration file to the network
5451  interface. Using the standard <CODE>bootpd(8)</CODE> program supplied
5452  with UNIX you simply need to add a line to the<VAR> /etc/bootptab</VAR>
5453  file; for IRIX:</P>
5454 <UL>
5455 <PRE>
5456 myprinter 08:00:69:00:12:34 192.0.2.2 <VAR>myprinter.boot</VAR>
5457 </PRE>
5458 </UL>
5459
5460 <!-- NEED 1in -->
5461 <P>Newer versions of <CODE>bootpd</CODE> use a different format:</P>
5462 <UL>
5463 <PRE>
5464 myprinter:ha=080069001234:ip=192.0.2.2:<VAR>t144=myprinter.boot</VAR>
5465 </PRE>
5466 </UL>
5467 <P>The<VAR> myprinter.boot</VAR> file resides in the<VAR>
5468  /usr/local/boot</VAR> directory by default. If you do not need to
5469  provide a boot file you may leave the last part of the line blank.</P>
5470
5471 <!-- NEED 2in -->
5472 <CENTER>
5473 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
5474 <TR><TD><B> NOTE:</B>
5475 <P>Some versions of UNIX do not enable the BOOTP service by default. The<VAR>
5476  /etc/inetd.conf</VAR> usually contains a line for the BOOTP service
5477  that can be uncommented if needed.</P>
5478 </TD></TR>
5479 </TABLE>
5480 </CENTER>
5481 <H2><A NAME="10_2">Verifying the Printer Connection</A></H2>
5482 <P>To test that the IP address has been successfully assigned and that
5483  the printer is properly connected to your LAN, type:</P>
5484 <UL>
5485 <PRE>
5486 <B>ping ip-address ENTER</B>
5487 </PRE>
5488 </UL>
5489 <P>If the connection is working properly you will see something like:</P>
5490 <UL>
5491 <PRE>
5492 <B>ping myprinter ENTER</B>
5493 PING myprinter (192.0.2.2): 56 data bytes
5494 64 bytes from 192.0.2.2: icmp_seq=0 ttl=15 time=5 ms
5495 64 bytes from 192.0.2.2: icmp_seq=1 ttl=15 time=3 ms
5496 64 bytes from 192.0.2.2: icmp_seq=2 ttl=15 time=3 ms
5497 64 bytes from 192.0.2.2: icmp_seq=3 ttl=15 time=3 ms
5498 </PRE>
5499 </UL>
5500 <P>If not, verify that the printer or print server is connected to the
5501  LAN, it is powered on, the LAN cabling is good, and the IP address is
5502  set correctly. You can usually see the current IP address and network
5503  status by printing a configuration or test page on the device.
5504 <!-- NEED 4in -->
5505 </P>
5506 <H2><A NAME="10_3">Common Network Interface Settings</A></H2>
5507 <P>Once you have set the IP address you can access the printer or print
5508  server using the <CODE>ipp</CODE>, <CODE>lpd</CODE>, or <CODE>socket</CODE>
5509  backends. The following is a list of common network interfaces and
5510  printer servers and the settings you should use with CUPS:
5511 <CENTER>
5512 <TABLE BORDER="1">
5513 <TR ALIGN="LEFT" VALIGN="TOP"><TH>Model/Manufacturer</TH><TH>Device
5514  URI(s)</TH></TR>
5515 <TR ALIGN="LEFT" VALIGN="TOP"><TD>Apple LaserWriter</TD><TD>lpd://<I>
5516 address</I>/PASSTHRU</TD></TR>
5517
5518 <!-- NEED 1in -->
5519 <TR ALIGN="LEFT" VALIGN="TOP"><TD>Axis w/o IPP
5520 <BR><A HREF="#AXIS"> (see directions)</A></TD><TD>socket://<I>address</I>
5521 :9100
5522 <BR> socket://<I>address</I>:9101
5523 <BR> socket://<I>address</I>:9102</TD></TR>
5524
5525 <!-- NEED 1in -->
5526 <TR ALIGN="LEFT" VALIGN="TOP"><TD>Axis w/IPP</TD><TD>ipp://<I>address</I>
5527 /LPT1
5528 <BR> ipp://<I>address</I>/LPT2
5529 <BR> ipp://<I>address</I>/COM1</TD></TR>
5530
5531 <!-- NEED 1in -->
5532 <TR ALIGN="LEFT" VALIGN="TOP"><TD>Castelle LANpress<SUP>TM</SUP></TD><TD>
5533 lpd://<I>address</I>/pr1
5534 <BR> lpd://<I>address</I>/pr2
5535 <BR> lpd://<I>address</I>/pr3</TD></TR>
5536
5537 <!-- NEED 1in -->
5538 <TR ALIGN="LEFT" VALIGN="TOP"><TD>DPI NETPrint</TD><TD>lpd://<I>address</I>
5539 /pr1
5540 <BR> lpd://<I>address</I>/pr2
5541 <BR> lpd://<I>address</I>/pr3</TD></TR>
5542 <TR ALIGN="LEFT" VALIGN="TOP"><TD>EFI&reg; Fiery&reg; RIP</TD><TD>lpd://<I>
5543 address</I>/print</TD></TR>
5544 <TR ALIGN="LEFT" VALIGN="TOP"><TD>EPSON&reg; Multiprotocol Ethernet
5545  Interface Board</TD><TD>socket://<I>address</I></TD></TR>
5546
5547 <!-- NEED 1in -->
5548 <TR ALIGN="LEFT" VALIGN="TOP"><TD>Extended System ExtendNET</TD><TD>
5549 lpd://<I>address</I>/pr1
5550 <BR> lpd://<I>address</I>/pr2
5551 <BR> lpd://<I>address</I>/pr3</TD></TR>
5552
5553 <!-- NEED 1in -->
5554 <TR ALIGN="LEFT" VALIGN="TOP"><TD>Hewlett Packard JetDirect w/o IPP</TD><TD>
5555 socket://<I>address</I>:9100
5556 <BR> socket://<I>address</I>:9101
5557 <BR> socket://<I>address</I>:9102</TD></TR>
5558
5559 <!-- NEED 1in -->
5560 <TR ALIGN="LEFT" VALIGN="TOP"><TD>Hewlett Packard JetDirect w/IPP</TD><TD>
5561 ipp://<I>address</I>/ipp
5562 <BR> ipp://<I>address</I>/ipp/port1
5563 <BR> ipp://<I>address</I>/ipp/port2
5564 <BR> ipp://<I>address</I>/ipp/port3</TD></TR>
5565
5566 <!-- NEED 1in -->
5567 <TR ALIGN="LEFT" VALIGN="TOP"><TD>Intel&reg; NetportExpress XL, PRO/100</TD><TD>
5568 lpd://<I>address</I>/LPT1_PASSTHRU
5569 <BR> lpd://<I>address</I>/LPT2_PASSTHRU
5570 <BR> lpd://<I>address</I>/COM1_PASSTHRU</TD></TR>
5571 <TR ALIGN="LEFT" VALIGN="TOP"><TD>Lexmark<SUP>TM</SUP> MarkNet</TD><TD>
5572 lpd://<I>address</I>/ps</TD></TR>
5573
5574 <!-- NEED 1in -->
5575 <TR ALIGN="LEFT" VALIGN="TOP"><TD>Linksys EtherFast&reg;
5576 <BR><A HREF="#LINKSYS"> (see directions)</A></TD><TD>socket://<I>address</I>
5577 :4010
5578 <BR> socket://<I>address</I>:4020
5579 <BR> socket://<I>address</I>:4030</TD></TR>
5580 <TR ALIGN="LEFT" VALIGN="TOP"><TD>Kodak&reg;</TD><TD>lpd://<I>address</I>/ps</TD>
5581 </TR>
5582 <TR ALIGN="LEFT" VALIGN="TOP"><TD>QMS&reg; CrownNet<SUP>TM</SUP></TD><TD>
5583 lpd://<I>address</I>/ps</TD></TR>
5584 <TR ALIGN="LEFT" VALIGN="TOP"><TD>Tektronix&reg; PhaserShare<SUP>TM</SUP></TD><TD>
5585 socket://<I>address</I>:9100</TD></TR>
5586 <TR ALIGN="LEFT" VALIGN="TOP"><TD>XEROX&reg; 4512 NIC</TD><TD>lpd://<I>
5587 address</I>/PORT1</TD></TR>
5588 <TR ALIGN="LEFT" VALIGN="TOP"><TD>XEROX&reg; XNIC</TD><TD>lpd://<I>address</I>
5589 /PASSTHRU</TD></TR>
5590 <TR ALIGN="LEFT" VALIGN="TOP"><TD>XEROX&reg; (most others)</TD><TD>socket://<I>
5591 address</I>:5503</TD></TR>
5592 </TABLE>
5593 </CENTER>
5594 </P>
5595 <H2><A NAME="AXIS">Configuring Axis Print Servers</A></H2>
5596 <P>The Axis print servers can be configured using ARP, RARP, or BOOTP.
5597  However, on models that do not provide IPP support an additional step
5598  must be performed to configure the TCP/IP portion of the print server
5599  for use with CUPS.
5600 <!-- NEED 3in -->
5601 </P>
5602 <P>Each print server contains a configuration file named<VAR> config</VAR>
5603  that contains a list of network parameters used by the server. To
5604  modify this file you must first download it from the print server using
5605  the <CODE>ftp(1)</CODE> program:</P>
5606 <UL>
5607 <PRE>
5608 <B>ftp ip-address ENTER</B>
5609 Connected to ip-address.
5610 220 Axis NPS ### FTP Printer Server V#.## MON DD YEAR ready.
5611 ftp&gt; <B>user root ENTER</B>
5612 331 User name ok, need password
5613 Password: <B>pass ENTER</B> <I>(this is not echoed)</I>
5614 230 User logged in
5615 ftp&gt; <B>get config ENTER</B>
5616 local: config remote: config
5617 200 PORT command successful.
5618 150 Opening data connection for config (192,0,2,2),
5619 (mode ascii).
5620 226 Transfer complete.
5621 ##### bytes received in #.## seconds (##### Kbytes/s)
5622 ftp&gt; <B>quit ENTER</B>
5623 221 Goodbye.
5624 </PRE>
5625 </UL>
5626
5627 <!-- NEED 2in -->
5628 <P>Next, edit the file with your favorite text editor and locate the
5629  lines beginning with:</P>
5630 <UL>
5631 <PRE>
5632 RTN_OPT.     : YES
5633 RTEL_PR1.    : 0
5634 RTEL_PR2.    : 0
5635 RTEL_PR3.    : 0
5636 RTEL_PR4.    : 0
5637 RTEL_PR5.    : 0
5638 RTEL_PR6.    : 0
5639 RTEL_PR7.    : 0
5640 RTEL_PR8.    : 0
5641 </PRE>
5642 </UL>
5643
5644 <!-- NEED 1in -->
5645  Change the <CODE>RTN_OPT</CODE> line to read:
5646 <UL>
5647 <PRE>
5648 RTN_OPT.     : <B>NO</B>
5649 </PRE>
5650 </UL>
5651
5652 <!-- NEED 2in -->
5653 <P>This disables the Reverse TELNET protocol and enables the standard
5654  TELNET protocol on the print server. Next, assign a port number for
5655  each parallel and serial port on the server as follows:</P>
5656 <UL>
5657 <PRE>
5658 RTEL_PR1.    : <B>9100</B>
5659 RTEL_PR2.    : <B>9101</B>
5660 RTEL_PR3.    : <B>9102</B>
5661 RTEL_PR4.    : <B>9103</B>
5662 RTEL_PR5.    : <B>9104</B>
5663 RTEL_PR6.    : <B>9105</B>
5664 RTEL_PR7.    : <B>9106</B>
5665 RTEL_PR8.    : <B>9107</B>
5666 </PRE>
5667 </UL>
5668
5669 <!-- NEED 4in -->
5670 <P>This essentially makes the Axis print server look like a Hewlett
5671  Packard JetDirect EX print server. Save the file and then upload the
5672  new<VAR> config</VAR> file using the <CODE>ftp</CODE> command:</P>
5673 <UL>
5674 <PRE>
5675 <B>ftp ip-address ENTER</B>
5676 Connected to ip-address.
5677 220 Axis NPS ### FTP Printer Server V#.## MON DD YEAR ready.
5678 ftp&gt; <B>user root ENTER</B>
5679 331 User name ok, need password
5680 Password: <B>pass ENTER</B> <I>(this is not echoed)</I>
5681 230 User logged in
5682 ftp&gt; <B>put config CONFIG ENTER</B>
5683 local: config remote: CONFIG
5684 200 PORT command successful.
5685 150 Opening data connection for config (192,0,2,2), (mode ascii).
5686 226 Transfer complete.
5687 ##### bytes received in #.## seconds (##### Kbytes/s)
5688 ftp&gt; <B>get hardreset ENTER</B>
5689 local: hardreset remote: hardreset
5690 200 PORT command successful.
5691 421 Axis NPS ### hard reset, closing connection.
5692 ftp&gt; <B>quit ENTER</B>
5693 221 Goodbye.
5694 </PRE>
5695 </UL>
5696 <P>Your Axis print server is now ready for use!</P>
5697 <H2><A NAME="LINKSYS">Configuring Linksys Print Servers</A></H2>
5698 <P>The Linksys print servers can be configured using ARP, RARP, or
5699  BOOTP. Like older Axis print servers, an additional step must be
5700  performed to configure the TCP/IP portion of the print server for use
5701  with CUPS.
5702 <!-- NEED 3in -->
5703 </P>
5704 <P>Each print server contains a configuration file named<VAR> CONFIG</VAR>
5705  that contains a list of network parameters used by the server. To
5706  modify this file you must first download it from the print server using
5707  the <CODE>ftp(1)</CODE> program:</P>
5708 <UL>
5709 <PRE>
5710 <B>ftp -n ip-address ENTER</B>
5711 Connected to ip-address.
5712 220 Print Server Ready.
5713 Remote system type is Print.
5714 ftp&gt; <B>get CONFIG ENTER</B>
5715 local: CONFIG remote: CONFIG
5716 200 Command OK.
5717 150 Open ASCII Mode Connection.
5718 WARNING! 68 bare linefeeds received in ASCII mode
5719 File may not have transferred correctly.
5720 226 Transfer complete.
5721 ##### bytes received in #.## seconds (##### Kbytes/s)
5722 ftp&gt; <B>quit ENTER</B>
5723 221 Goodbye.
5724 </PRE>
5725 </UL>
5726
5727 <!-- NEED 2in -->
5728 <P>Next, edit the file with your favorite text editor and locate the
5729  lines beginning with:</P>
5730 <UL>
5731 <PRE>
5732 0100 L1_PROUT:P1
5733 0120 L2_PROUT:P1
5734 0140 L3_PROUT:P1
5735 </PRE>
5736 </UL>
5737 <P>Change the port number for each parallel and serial port on the
5738  server as follows:</P>
5739 <UL>
5740 <PRE>
5741 0100 L1_PROUT:<B>P1</B>
5742 0120 L2_PROUT:<B>P2</B>
5743 0140 L3_PROUT:<B>P3</B>
5744 </PRE>
5745 </UL>
5746
5747 <!-- NEED 4in -->
5748 <P>This maps each virtual printer with a physical port. Save the file
5749  and then upload the new<VAR> CONFIG</VAR> file using the <CODE>ftp</CODE>
5750  command:</P>
5751 <UL>
5752 <PRE>
5753 <B>ftp -n ip-address ENTER</B>
5754 Connected to ip-address.
5755 220 Print Server Ready.
5756 Remote system type is Print.
5757 ftp&gt; <B>put CONFIG ENTER</B>
5758 local: CONFIG remote: CONFIG
5759 200 Command OK.
5760 150 Open ASCII Mode Connection.
5761 226 Transfer complete.
5762 ##### bytes received in #.## seconds (##### Kbytes/s)
5763 ftp&gt; <B>quit ENTER</B>
5764 221 Goodbye.
5765 </PRE>
5766 </UL>
5767 <P>Your Linksys print server is now ready for use!</P>
5768 <H1 ALIGN="RIGHT"><A NAME="PRINTER_DRIVERS">C - Printer Drivers</A></H1>
5769 <P>This appendix lists the printer drivers that are provided with CUPS.</P>
5770 <H2><A NAME="11_1">Printer Drivers</A></H2>
5771 <P>CUPS includes the following printer drivers:</P>
5772 <UL>
5773 <LI><A HREF="#EPSON9">EPSON 9-pin Dot Matrix</A>,<VAR> epson9.ppd</VAR></LI>
5774 <LI><A HREF="#EPSON24">EPSON 24-pin Dot Matrix</A>,<VAR> epson24.ppd</VAR>
5775 </LI>
5776 <LI><A HREF="#STCOLOR">EPSON Stylus Color</A>,<VAR> stcolor.ppd</VAR></LI>
5777 <LI><A HREF="#STPHOTO">EPSON Stylus Photo</A>,<VAR> stphoto.ppd</VAR></LI>
5778 <LI><A HREF="#DESKJET">HP DeskJet</A>,<VAR> deskjet.ppd</VAR></LI>
5779 <LI><A HREF="#LASERJET">HP LaserJet</A>,<VAR> laserjet.ppd</VAR></LI>
5780 </UL>
5781 <H2><A NAME="EPSON9">EPSON 9-pin Dot Matrix</A></H2>
5782 <P>The EPSON 9-pin Dot Matrix driver (<VAR>epson9.ppd</VAR>) supports
5783  9-pin dot matrix printers that implement the ESC/P command set. It
5784  provides 60x72, 120x72, and 240x72 DPI output in black only.</P>
5785 <H2><A NAME="EPSON24">EPSON 24-pin Dot Matrix</A></H2>
5786 <P>The EPSON 24-pin Dot Matrix driver (<VAR>epson9.ppd</VAR>) supports
5787  24-pin dot matrix printers that implement the ESC/P command set. It
5788  provides 120x180, 180x180, 360x180, and 360x360 DPI output in black
5789  only.</P>
5790 <H2><A NAME="STCOLOR">EPSON Stylus Color</A></H2>
5791 <P>The EPSON Stylus Color driver (<VAR>stcolor.ppd</VAR>) supports EPSON
5792  Stylus Color printers that implement the ESC/P2 command set. It
5793  provides 180, 360, and 720 DPI output in black and color (CMYK).</P>
5794 <H2><A NAME="STPHOTO">EPSON Stylus Photo</A></H2>
5795 <P>The EPSON Stylus Photo driver (<VAR>stphoto.ppd</VAR>) supports EPSON
5796  Stylus Photo printers that implement the ESC/P2 command set. It
5797  provides 180, 360, and 720 DPI output in black and color (CMYKcm).</P>
5798 <H2><A NAME="DESKJET">HP DeskJet</A></H2>
5799 <P>The HP DeskJet driver (<VAR>deskjet.ppd</VAR>) supports HP DeskJet
5800  printers that implement the PCL command set. It provides 150, 300, and
5801  600 DPI output in black and color (CMYK).</P>
5802 <P>The DeskJet printers that implement the HP-PPA command set (720C,
5803  722C, 820C, and 1100C) are<B> not</B> supported due to a complete lack
5804  of documentation and support from Hewlett Packard.</P>
5805 <P>The duplexer provided with the HP DeskJet 900 series printers is also
5806  not supported for similar reasons.</P>
5807 <H2><A NAME="LASERJET">HP LaserJet</A></H2>
5808 <P>The HP LaserJet driver (<VAR>laserjet.ppd</VAR>) supports HP LaserJet
5809  printers that implement the PCL command set. It provides 150, 300, and
5810  600 DPI output in black only and supports the duplexer if installed.</P>
5811 <P>LaserJet printers that do not implement PCL (3100, 3150) are not
5812  supported due to a complete lack of documentation and support from
5813  Hewlett Packard.</P>
5814 <H1 ALIGN="RIGHT"><A NAME="FILES">D - List of Files</A></H1>
5815 <P>This appendix lists the files and directories that are installed for
5816  the Common UNIX Printing System.
5817 <CENTER>
5818 <TABLE BORDER="1" WIDTH="80%">
5819 <TR VALIGN="TOP"><TH>Pathname</TH><TH>Description</TH></TR>
5820 <TR VALIGN="TOP"><TD>/etc/cups/certs/</TD><TD>The location of
5821  authentication certificate files for local HTTP clients.</TD></TR>
5822 <TR VALIGN="TOP"><TD>/etc/cups/classes.conf</TD><TD>The printer classes
5823  configuration file for the scheduler.</TD></TR>
5824 <TR VALIGN="TOP"><TD>/etc/cups/cupsd.conf</TD><TD>The scheduler
5825  configuration file.</TD></TR>
5826 <TR VALIGN="TOP"><TD>/etc/cups/interfaces/</TD><TD>The location of
5827  System V interface scripts for printers.</TD></TR>
5828 <TR VALIGN="TOP"><TD>/etc/cups/mime.convs</TD><TD>The list of standard
5829  file filters included with CUPS.</TD></TR>
5830 <TR VALIGN="TOP"><TD>/etc/cups/mime.types</TD><TD>The list of recognized
5831  file types for CUPS.</TD></TR>
5832 <TR VALIGN="TOP"><TD>/etc/cups/ppd/</TD><TD>The location of PostScript
5833  Printer Description (&quot;PPD&quot;) files for printers.</TD></TR>
5834 <TR VALIGN="TOP"><TD>/etc/cups/printers.conf</TD><TD>The printer
5835  configuration file for the scheduler.</TD></TR>
5836 <TR VALIGN="TOP"><TD>/usr/bin/cancel</TD><TD>The System V cancel job(s)
5837  command.</TD></TR>
5838 <TR VALIGN="TOP"><TD>/usr/bin/disable</TD><TD>The System V disable
5839  printer command.</TD></TR>
5840 <TR VALIGN="TOP"><TD>/usr/bin/enable</TD><TD>The System V enable printer
5841  command.</TD></TR>
5842 <TR VALIGN="TOP"><TD>/usr/bin/lp</TD><TD>The System V print command.</TD>
5843 </TR>
5844 <TR VALIGN="TOP"><TD>/usr/bin/lpoptions</TD><TD>Sets user-defined
5845  printing options and defaults.</TD></TR>
5846 <TR VALIGN="TOP"><TD>/usr/bin/lppasswd</TD><TD>Adds, changes, or removes
5847  Digest password accounts.</TD></TR>
5848 <TR VALIGN="TOP"><TD>/usr/bin/lpq</TD><TD>The Berkeley status command.</TD>
5849 </TR>
5850 <TR VALIGN="TOP"><TD>/usr/bin/lpr</TD><TD>The Berkeley print command.</TD>
5851 </TR>
5852 <TR VALIGN="TOP"><TD>/usr/bin/lprm</TD><TD>The Berkeley cancel job(s)
5853  command.</TD></TR>
5854 <TR VALIGN="TOP"><TD>/usr/bin/lpstat</TD><TD>The System V status
5855  command.</TD></TR>
5856 <TR VALIGN="TOP"><TD>/usr/include/cups/</TD><TD>CUPS API header files.</TD>
5857 </TR>
5858 <TR VALIGN="TOP"><TD>/usr/lib32/libcups.a
5859 <BR> /usr/lib32/libcupsimage.a</TD><TD>Static libraries (IRIX 6.5)</TD></TR>
5860 <TR VALIGN="TOP"><TD>/usr/lib/libcups.a
5861 <BR> /usr/lib/libcupsimage.a</TD><TD>Static libraries (all others)</TD></TR>
5862 <TR VALIGN="TOP"><TD>/usr/lib/libcups.sl.2
5863 <BR> /usr/lib/libcupsimage.sl.2</TD><TD>Shared libraries (HP-UX)</TD></TR>
5864 <TR VALIGN="TOP"><TD>/usr/lib32/libcups.so.2
5865 <BR> /usr/lib32/libcupsimage.so.2</TD><TD>Shared libraries (IRIX 6.5)</TD>
5866 </TR>
5867 <TR VALIGN="TOP"><TD>/usr/lib/libcups.so.2
5868 <BR> /usr/lib/libcupsimage.so.2</TD><TD>Shared libraries (all others)</TD>
5869 </TR>
5870 <TR VALIGN="TOP"><TD>/usr/lib/cups/backend/</TD><TD>Backends for various
5871  types of printer connections.</TD></TR>
5872 <TR VALIGN="TOP"><TD>/usr/lib/cups/cgi-bin/</TD><TD>CGI programs for the
5873  scheduler.</TD></TR>
5874 <TR VALIGN="TOP"><TD>/usr/lib/cups/daemon/</TD><TD>Daemons for polling
5875  and LPD support.</TD></TR>
5876 <TR VALIGN="TOP"><TD>/usr/lib/cups/filter/</TD><TD>Filters for various
5877  types of files.</TD></TR>
5878 <TR VALIGN="TOP"><TD>/usr/lib/locale/</TD><TD>The location of
5879  language-specific message files. (System V)</TD></TR>
5880 <TR VALIGN="TOP"><TD>/usr/lib/nls/msg/</TD><TD>The location of
5881  language-specific message files. (Compaq Tru64 UNIX)</TD></TR>
5882 <TR VALIGN="TOP"><TD>/usr/share/locale/</TD><TD>The location of
5883  language-specific message files. (Linux, *BSD)</TD></TR>
5884 <TR VALIGN="TOP"><TD>/usr/sbin/accept</TD><TD>The accept-jobs command.</TD>
5885 </TR>
5886 <TR VALIGN="TOP"><TD>/usr/sbin/cupsd</TD><TD>The CUPS print scheduler.</TD>
5887 </TR>
5888 <TR VALIGN="TOP"><TD>/usr/sbin/lpadmin</TD><TD>The System V printer
5889  administration tool.</TD></TR>
5890 <TR VALIGN="TOP"><TD>/usr/sbin/lpc</TD><TD>The Berkeley printer
5891  administration tool.</TD></TR>
5892 <TR VALIGN="TOP"><TD>/usr/sbin/lpinfo</TD><TD>The get-devices and
5893  get-ppds command.</TD></TR>
5894 <TR VALIGN="TOP"><TD>/usr/sbin/lpmove</TD><TD>The move-jobs command.</TD>
5895 </TR>
5896 <TR VALIGN="TOP"><TD>/usr/sbin/reject</TD><TD>The reject-jobs command.</TD>
5897 </TR>
5898 <TR VALIGN="TOP"><TD>/usr/share/catman/a_man/
5899 <BR> /usr/share/catman/u_man/</TD><TD>Man pages (IRIX)</TD></TR>
5900 <TR VALIGN="TOP"><TD>/usr/share/man/</TD><TD>Man pages (Compaq Tru64
5901  UNIX, HP-UX, Solaris)</TD></TR>
5902 <TR VALIGN="TOP"><TD>/usr/man/</TD><TD>Man pages (all others)</TD></TR>
5903 <TR VALIGN="TOP"><TD>/usr/share/cups/data/</TD><TD>The location of
5904  filter data files.</TD></TR>
5905 <TR VALIGN="TOP"><TD>/usr/share/cups/data/testprint.ps</TD><TD>The
5906  PostScript test page file.</TD></TR>
5907 <TR VALIGN="TOP"><TD>/usr/share/cups/fonts/</TD><TD>The location of
5908  PostScript fonts for the PostScript RIP.</TD></TR>
5909 <TR VALIGN="TOP"><TD>/usr/share/cups/model/</TD><TD>The location of
5910  PostScript Printer Description (&quot;PPD&quot;) files and interface scripts that
5911  may be used to setup a printer queue.</TD></TR>
5912 <TR VALIGN="TOP"><TD>/usr/share/cups/pstoraster/</TD><TD>Other
5913  PostScript RIP initialization files.</TD></TR>
5914 <TR VALIGN="TOP"><TD>/usr/share/cups/pstoraster/Fontmap</TD><TD>The font
5915  mapping file (converts filenames to fontnames)</TD></TR>
5916 <TR VALIGN="TOP"><TD>/usr/share/cups/templates/</TD><TD>The location of
5917  HTML template files for the web interfaces.</TD></TR>
5918 <TR VALIGN="TOP"><TD>/usr/share/doc/cups/</TD><TD>Documentation and web
5919  page data for the scheduler.</TD></TR>
5920 <TR VALIGN="TOP"><TD>/var/log/cups/</TD><TD>The location of scheduler
5921  log files.</TD></TR>
5922 <TR VALIGN="TOP"><TD>/var/spool/cups/</TD><TD>The location of print
5923  files waiting to be printed.</TD></TR>
5924 </TABLE>
5925 </CENTER>
5926 </P>
5927 <H1 ALIGN="RIGHT"><A NAME="FAQ">E - Troubleshooting Common Problems</A></H1>
5928 <P>This appendix covers some of the common problems first-time users
5929  encounter when installing and configuring CUPS.</P>
5930 <P>Commercial support for CUPS is available from Easy Software Products.
5931  For more information please contact us at:</P>
5932 <UL>
5933 <LI>WWW:<A HREF="http://www.easysw.com"> <CODE>http://www.easysw.com</CODE>
5934 </A></LI>
5935 <LI>EMail:<A HREF="mailto:info@easysw.com"> info@easysw.com</A></LI>
5936 <LI>Telephone (M-F, 9-5 EST): +1.301.373.9600</LI>
5937 </UL>
5938 <H2><A NAME="13_1">My Applications Don't See the Available Printers</A></H2>
5939 <P>Many applications read the<VAR> /etc/printcap</VAR> file to get a
5940  list of available printers.</P>
5941 <P>The default CUPS configuration creates the<VAR> /etc/printcap</VAR>
5942  file automatically. To enable or disable automatic creation and
5943  updating of this file, use the<A HREF="#Printcap"> <CODE>Printcap</CODE>
5944 </A> directive described in<A HREF="#PRINTING_MANAGEMENT"> Chapter 6,
5945  &quot;Printing System Management&quot;</A>.</P>
5946 <H2><A NAME="13_2">CUPS Doesn't Recognize My Username or Password!</A></H2>
5947 <P>CUPS will ask you for a UNIX username and password when you perform
5948  printer administration tasks remotely or via a web browser. The default
5949  configuration requires that you use the <CODE>root</CODE> username and
5950  the corresponding password to authenticate the request.</P>
5951 <P>CUPS does not allow you to authenticate an administration request
5952  with an account that has no password for security reasons. If you do
5953  not have a password on your <CODE>root</CODE> account then you won't be
5954  able to add printers remotely or via the web interface!
5955 <!-- NEED 2in -->
5956 </P>
5957 <P>To disable password authentication you need to edit the<VAR>
5958  /etc/cups/cupsd.conf</VAR> file and comment out the lines reading:</P>
5959 <UL>
5960 <PRE>
5961 AuthType Basic
5962 AuthClass System
5963 </PRE>
5964 </UL>
5965 <P>for the<VAR> /admin</VAR> location. Then restart the CUPS server as
5966  described in<A HREF="#PRINTING_MANAGEMENT"> Chapter 6, &quot;Printing System
5967  Management&quot;</A>.</P>
5968 <CENTER>
5969 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
5970 <TR><TD><B> NOTE:</B>
5971 <P>Disabling password checks will allow any local user to change your
5972  printer and class configuration, but remote administration from another
5973  machine will still not be allowed.</P>
5974 </TD></TR>
5975 </TABLE>
5976 </CENTER>
5977 <H2><A NAME="ALLOW_REMOTE">I Can't Do Administration Tasks from Another
5978  Machine!</A></H2>
5979 <P>The default CUPS configuration limits administration to the local
5980  machine. To open up access, edit the<VAR> /etc/cups/cupsd.conf</VAR>
5981  and comment out the lines reading:</P>
5982 <UL>
5983 <PRE>
5984 Order deny,allow
5985 Deny from all
5986 Allow from 127.0.0.1
5987 </PRE>
5988 </UL>
5989 <P>for the<VAR> /admin</VAR> location. Then restart the CUPS server as
5990  described in<A HREF="#PRINTING_MANAGEMENT"> Chapter 6, &quot;Printing System
5991  Management&quot;</A>.</P>
5992 <CENTER>
5993 <TABLE BGCOLOR="#cccccc" BORDER="1" CELLPADDING="5" WIDTH="80%">
5994 <TR><TD><B> NOTE:</B>
5995 <P>Allowing administration access from all hosts is a potential security
5996  risk. Please read<A HREF="#PRINTING_SECURITY"> Chapter 6, &quot;Printing
5997  System Management&quot;</A> for a description of these risks and ways to
5998  minimize them.</P>
5999 </TD></TR>
6000 </TABLE>
6001 </CENTER>
6002
6003 <!-- NEED 4in -->
6004 <H2><A NAME="13_4">I Can't Do Administration Tasks from My Web Browser!</A>
6005 </H2>
6006 <P>This problem is usually caused by:</P>
6007 <OL>
6008 <LI>not specifying the correct password for the root account.</LI>
6009 <LI>accessing the CUPS server using the hostname or IP address of the
6010  server without enabling remote access for administration functions.
6011  This can be corrected by following the instructions in the<A HREF="#ALLOW_REMOTE">
6012  &quot;I Can't Do Administration Tasks from Another Machine!&quot;</A> section
6013  earlier in this appendix.</LI>
6014 <LI>not setting a password on the root account. CUPS will not
6015  authenticate a user account that does not have a password for security
6016  reasons.</LI>
6017 <LI>authenticating using an account other than root, but the account you
6018  are using is not a member of the system group.</LI>
6019 <LI>configuring CUPS to use Digest authentication, but your web browser
6020  does not support Digest authentication.</LI>
6021 </OL>
6022 <H2><A NAME="13_5">Connection Refused Messages</A></H2>
6023 <P>Under normal circumstances, &quot;connection refused&quot; messages for a
6024  networked printer should be expected from time to time. Most network
6025  interfaces only allow a single connection to be made at any given time
6026  (one job at a time) and will refuse access to all other systems while
6027  the first connection is active. CUPS automatically retries the
6028  connection once every 30 seconds.</P>
6029 <P>If the problem persists and you are unable to print any jobs to the
6030  printer, verify that another machine is not maintaining a connection
6031  with the printer, and that you have selected the proper port or printer
6032  name for the printer.</P>
6033 <P>Also, most external print servers will refuse connections if the
6034  connected printer is turned off or is off-line. Verify that the
6035  affected printer is turned on and is online.</P>
6036 <H2><A NAME="13_6">Write Error Messages</A></H2>
6037 <P>If you get &quot;write error&quot; messages on a printer queue the printer
6038  interface (usually a Hewlett Packard JetDirect interface) has timed out
6039  and reset the network connection from your workstation.</P>
6040 <P>The error is caused by that startup delay between the initial setup
6041  of the printer or plotter and the first page of print data that is
6042  sent.
6043 <!-- NEED 3in -->
6044 </P>
6045 <P>To correct the problem, change the idle timeout on the interface to
6046  at least 180 seconds or 3 minutes. To change the timeout on a Hewlett
6047  Packard JetDirect interface, type:</P>
6048 <UL>
6049 <PRE>
6050 <B>telnet ip-address ENTER</B>
6051
6052 Trying ip-address...
6053 Connected to ip-address.
6054 Escape character is `^]'.
6055
6056 Please type [Return] two times, to initialize telnet configuration
6057 For HELP type &quot;?&quot;
6058 &gt; <B>idle-timeout: 180 ENTER</B>
6059 &gt; <B>quit ENTER</B>
6060 </PRE>
6061 </UL>
6062 </BODY>
6063 </HTML>