doc/help/ref-cupsd-conf.html.in

   1 <HTML>
   2 <!-- SECTION: References -->
   3 <HEAD>
   4         <TITLE>cupsd.conf</TITLE>
   5         <LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
   6 </HEAD>
   7 <BODY>
   8
   9 <H1 CLASS="title">cupsd.conf</H1>
  10
  11 <P>The <VAR>/etc/cups/cupsd.conf</VAR> file contains
  12 configuration <I>directives</I> that control how the server
  13 functions. Each directive is listed on a line by itself followed
  14 by its value. Comments are introduced using the number sign ("#")
  15 character at the beginning of a line.</P>
  16
  17 <P>Since the server configuration file consists of plain text,
  18 you can use your favorite text editor to make changes to it.
  19 After making any changes, restart the <CODE>cupsd(8)</CODE>
  20 process using the startup script for your operating system:</P>
  21
  22 <UL>
  23
  24         <LI>AIX, IRIX, Linux, Solaris:
  25         <PRE CLASS="command">
  26 /etc/init.d/cups restart
  27         </PRE></LI>
  28
  29         <LI>HP-UX:
  30         <PRE CLASS="command">
  31 /sbin/init.d/cups restart
  32         </PRE></LI>
  33
  34         <LI>MacOS X:
  35         <PRE CLASS="command">
  36 sudo launchctl unload /System/Library/LaunchDaemons/org.cups.cupsd.plist
  37 sudo launchctl load /System/Library/LaunchDaemons/org.cups.cupsd.plist
  38         </PRE></LI>
  39
  40 </UL>
  41
  42 <P>You can also edit this file from the CUPS web interface, which
  43 automatically handles restarting the scheduler.</P>
  44
  45
  46 <H2 CLASS="title"><A NAME="AccessLog">AccessLog</A></H2>
  47
  48 <H3>Examples</H3>
  49
  50 <PRE CLASS="command">
  51 AccessLog /var/log/cups/access_log
  52 AccessLog /var/log/cups/access_log-%s
  53 AccessLog syslog
  54 </PRE>
  55
  56 <H3>Description</H3>
  57
  58 <P>The <CODE>AccessLog</CODE> directive sets the name of the
  59 access log file. If the filename is not absolute then it is
  60 assumed to be relative to the <A
  61 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
  62 access log file is stored in "common log format" and can be used
  63 by any web access reporting tool to generate a report on CUPS
  64 server activity.</P>
  65
  66 <P>The server name can be included in the filename by using
  67 <CODE>%s</CODE> in the name.</P>
  68
  69 <P>The special name "syslog" can be used to send the access
  70 information to the system log instead of a plain file.</P>
  71
  72 <P>The default access log file is
  73 <VAR>@CUPS_LOGDIR@/access_log</VAR>.</P>
  74
  75
  76 <H2 CLASS="title"><A NAME="AccessLogLevel">AccessLogLevel</A></H2>
  77
  78 <H3>Examples</H3>
  79
  80 <PRE CLASS="command">
  81 AccessLogLevel config
  82 AccessLogLevel actions
  83 AccessLogLevel all
  84 </PRE>
  85
  86 <H3>Description</H3>
  87
  88 <P>The <CODE>AccessLogLevel</CODE> directive controls which requests are logged
  89 to the access log file. The following levels are defined:</P>
  90
  91 <UL>
  92
  93         <LI><CODE>config</CODE>; Log when printers and classes are added,
  94         deleted, or modified and when configuration files are accessed or
  95         updated.</LI>
  96
  97         <LI><CODE>actions</CODE>; Log when print jobs are submitted,
  98         held, released, modified, or canceled, and any of the conditions
  99         for <CODE>config</CODE>.</LI>
 100
 101         <LI><CODE>all</CODE>; Log all requests.</LI>
 102
 103 </UL>
 104
 105 <P>The default access log level is <CODE>@CUPS_ACCESS_LOG_LEVEL@</CODE>.</P>
 106
 107
 108 <H2 CLASS="title"><A NAME="Allow">Allow</A></H2>
 109
 110 <H3>Examples</H3>
 111
 112 <PRE CLASS="command">
 113 &lt;Location /path&gt;
 114   ...
 115   Allow from All
 116   Allow from None
 117   Allow from *.domain.com
 118   Allow from .domain.com
 119   Allow from host.domain.com
 120   Allow from nnn.*
 121   Allow from nnn.nnn.*
 122   Allow from nnn.nnn.nnn.*
 123   Allow from nnn.nnn.nnn.nnn
 124   Allow from nnn.nnn.nnn.nnn/mm
 125   Allow from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
 126   Allow from xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx
 127   Allow from @LOCAL
 128   Allow from @IF(name)
 129 &lt;/Location&gt;
 130 </PRE>
 131
 132 <H3>Description</H3>
 133
 134 <P>The <CODE>Allow</CODE> directive specifies a hostname, IP
 135 address, or network that is allowed access to the server.
 136 <CODE>Allow</CODE> directives are cummulative, so multiple
 137 <CODE>Allow</CODE> directives can be used to allow access for
 138 multiple hosts or networks.</P>
 139
 140 <P>Host and domain name matching require that you enable the <A
 141 HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A>
 142 directive.</P>
 143
 144 <P>The <CODE>/mm</CODE> notation specifies a CIDR netmask, as shown in
 145 <A HREF="#TABLE1">Table 1</A>.</P>
 146
 147 <DIV CLASS="table"><TABLE SUMMARY="CIDR Netmasks">
 148 <CAPTION>Table 1: <A NAME="TABLE1">CIDR Netmasks</A></CAPTION>
 149 <TR>
 150         <TH WIDTH="10%">mm</TH>
 151         <TH WIDTH="20%">netmask</TH>
 152         <TH WIDTH="10%">mm</TH>
 153         <TH WIDTH="20%">netmask</TH>
 154 </TR>
 155 <TR>
 156         <TD ALIGN="CENTER">0</TD>
 157         <TD ALIGN="CENTER">0.0.0.0</TD>
 158         <TD ALIGN="CENTER">8</TD>
 159         <TD ALIGN="CENTER">255.0.0.0</TD>
 160 </TR>
 161 <TR>
 162         <TD ALIGN="CENTER">1</TD>
 163         <TD ALIGN="CENTER">128.0.0.0</TD>
 164         <TD ALIGN="CENTER">16</TD>
 165         <TD ALIGN="CENTER">255.255.0.0</TD>
 166 </TR>
 167 <TR>
 168         <TD ALIGN="CENTER">2</TD>
 169         <TD ALIGN="CENTER">192.0.0.0</TD>
 170         <TD ALIGN="CENTER">24</TD>
 171         <TD ALIGN="CENTER">255.255.255.0</TD>
 172 </TR>
 173 <TR>
 174         <TD ALIGN="CENTER">...</TD>
 175         <TD ALIGN="CENTER">...</TD>
 176         <TD ALIGN="CENTER">32</TD>
 177         <TD ALIGN="CENTER">255.255.255.255</TD>
 178 </TR>
 179 </TABLE></DIV>
 180
 181 <P>The <CODE>@LOCAL</CODE> name will allow access from all local
 182 interfaces. The <CODE>@IF(name)</CODE> name will allow access
 183 from the named interface. In both cases, CUPS only allows access
 184 from the network that the interface(s) are configured for -
 185 requests  arriving on the interface from a foreign network will
 186 <em>not</em> be accepted.</P>
 187
 188 <P>The <CODE>Allow</CODE> directive must appear inside a <A
 189 HREF="#Location"><CODE>Location</CODE></A> or <A
 190 HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
 191
 192
 193 <H2 CLASS="title"><SPAN CLASS="info">Deprecated</SPAN><A NAME="AuthClass">AuthClass</A></H2>
 194
 195 <H3>Examples</H3>
 196
 197 <PRE CLASS="command">
 198 &lt;Location /path&gt;
 199   ...
 200   AuthClass Anonymous
 201   AuthClass User
 202   AuthClass System
 203   AuthClass Group
 204 &lt;/Location&gt;
 205 </PRE>
 206
 207 <H3>Description</H3>
 208
 209 <P>The <CODE>AuthClass</CODE> directive defines what level of
 210 authentication is required:</P>
 211
 212 <UL>
 213
 214         <LI><CODE>Anonymous</CODE> - No authentication should be
 215         performed (default)</LI>
 216
 217         <LI><CODE>User</CODE> - A valid username and password is
 218         required</LI>
 219
 220         <LI><CODE>System</CODE> - A valid username and password
 221         is required, and the username must belong to the "sys"
 222         group; this can be changed using the <A
 223         HREF="#SystemGroup"><CODE>SystemGroup</CODE></A>
 224         directive</LI>
 225
 226         <LI><CODE>Group</CODE> - A valid username and password is
 227         required, and the username must belong to the group named
 228         by the <A
 229         HREF="#AuthGroupName"><CODE>AuthGroupName</CODE></A>
 230         directive</LI>
 231
 232 </UL>
 233
 234 <P>The <CODE>AuthClass</CODE> directive must appear inside a <A
 235 HREF="#Location"><CODE>Location</CODE></A> or <A
 236 HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
 237
 238 <P><B>This directive is deprecated and will be removed from a
 239 future release of CUPS.</B> Consider using the more flexible <A
 240 HREF="#Require"><CODE>Require</CODE></A> directive instead.</P>
 241
 242
 243 <H2 CLASS="title"><SPAN CLASS="info">Deprecated</SPAN><A NAME="AuthGroupName">AuthGroupName</A></H2>
 244
 245 <H3>Examples</H3>
 246
 247 <PRE CLASS="command">
 248 &lt;Location /path&gt;
 249   ...
 250   AuthGroupName mygroup
 251   AuthGroupName lp
 252 &lt;/Location&gt;
 253 </PRE>
 254
 255 <H3>Description</H3>
 256
 257 <P>The <CODE>AuthGroupName</CODE> directive sets the group to use
 258 for <CODE>Group</CODE> authentication.</P>
 259
 260 <P>The <CODE>AuthGroupName</CODE> directive must appear inside a
 261 <A HREF="#Location"><CODE>Location</CODE></A> or <A
 262 HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
 263
 264 <P><B>This directive is deprecated and will be removed from a
 265 future release of CUPS.</B> Consider using the more flexible <A
 266 HREF="#Require"><CODE>Require</CODE></A> directive instead.</P>
 267
 268
 269 <H2 CLASS="title"><A NAME="AuthType">AuthType</A></H2>
 270
 271 <H3>Examples</H3>
 272
 273 <PRE CLASS="command">
 274 &lt;Location /path&gt;
 275   ...
 276   AuthType None
 277   AuthType Basic
 278   AuthType Digest
 279   AuthType BasicDigest
 280   AuthType Negotiate
 281 &lt;/Location&gt;
 282 </PRE>
 283
 284 <H3>Description</H3>
 285
 286 <P>The <CODE>AuthType</CODE> directive defines the type of
 287 authentication to perform:</P>
 288
 289 <UL>
 290
 291         <LI><CODE>None</CODE> - No authentication should be
 292         performed (default)</LI>
 293
 294         <LI><CODE>Basic</CODE> - Basic authentication should be
 295         performed using the UNIX password and group files</LI>
 296
 297         <LI><CODE>Digest</CODE> - Digest authentication should be
 298         performed using the <VAR>/etc/cups/passwd.md5</VAR>
 299         file</LI>
 300
 301         <LI><CODE>BasicDigest</CODE> - Basic authentication
 302         should be performed using the
 303         <VAR>/etc/cups/passwd.md5</VAR> file</LI>
 304
 305         <LI><CODE>Negotiate</CODE> - Kerberos authentication
 306         should be performed</LI>
 307
 308 </UL>
 309
 310 <P>When using <CODE>Basic</CODE>, <CODE>Digest</CODE>,
 311 <CODE>BasicDigest</CODE>, or <CODE>Negotiate</CODE> authentication,
 312 clients connecting through the <CODE>localhost</CODE> interface can
 313 also authenticate using certificates.</P>
 314
 315 <P>The <CODE>AuthType</CODE> directive must appear inside a <A
 316 HREF="#Location"><CODE>Location</CODE></A> or <A
 317 HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
 318
 319
 320 <H2 CLASS="title"><A NAME="AutoPurgeJobs">AutoPurgeJobs</A></H2>
 321
 322 <H3>Examples</H3>
 323
 324 <PRE CLASS="command">
 325 AutoPurgeJobs Yes
 326 AutoPurgeJobs No
 327 </PRE>
 328
 329 <H3>Description</H3>
 330
 331 <P>The <CODE>AutoPurgeJobs</CODE> directive specifies whether or
 332 not to purge completed jobs once they are no longer required for
 333 quotas. This option has no effect if quotas are not enabled. The
 334 default setting is <CODE>No</CODE>.</P>
 335
 336
 337 <H2 CLASS="title"><A NAME="BrowseAddress">BrowseAddress</A></H2>
 338
 339 <H3>Examples</H3>
 340
 341 <PRE CLASS="command">
 342 BrowseAddress 255.255.255.255:631
 343 BrowseAddress 192.0.2.255:631
 344 BrowseAddress host.domain.com:631
 345 BrowseAddress @LOCAL
 346 BrowseAddress @IF(name)
 347 </PRE>
 348
 349 <H3>Description</H3>
 350
 351 <P>The <CODE>BrowseAddress</CODE> directive specifies an address
 352 to send browsing information to. Multiple
 353 <CODE>BrowseAddress</CODE> directives can be specified to send
 354 browsing information to different networks or systems.</P>
 355
 356 <P>The <CODE>@LOCAL</CODE> name will broadcast printer
 357 information to all local interfaces. The <CODE>@IF(name)</CODE>
 358 name will broadcast to the named interface.</P>
 359
 360 <P>There is no default browse address.</P>
 361
 362 <BLOCKQUOTE><B>Note:</B>
 363
 364 <P>If you are using HP-UX 10.20 and a subnet that is not 24,
 365 16, or 8 bits, printer browsing (and in fact all broadcast
 366 reception) will not work. This problem appears to be fixed in
 367 HP-UX 11.0.</P>
 368
 369 </BLOCKQUOTE>
 370
 371
 372 <H2 CLASS="title"><A NAME="BrowseAllow">BrowseAllow</A></H2>
 373
 374 <H3>Examples</H3>
 375
 376 <PRE CLASS="command">
 377 BrowseAllow from all
 378 BrowseAllow from none
 379 BrowseAllow from 192.0.2
 380 BrowseAllow from 192.0.2.0/24
 381 BrowseAllow from 192.0.2.0/255.255.255.0
 382 BrowseAllow from *.domain.com
 383 BrowseAllow from @LOCAL
 384 BrowseAllow from @IF(name)
 385 </PRE>
 386
 387 <H3>Description</H3>
 388
 389 <P>The <CODE>BrowseAllow</CODE> directive specifies a system or
 390 network to accept browse packets from. The default is to accept
 391 browse packets from all hosts.</P>
 392
 393 <P>Host and domain name matching require that you enable the <A
 394 HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A>
 395 directive.</P>
 396
 397 <P>IP address matching supports exact matches, partial addresses that match
 398 networks using netmasks of 255.0.0.0, 255.255.0.0, and 255.255.255.0, or network
 399 addresses using the specified netmask or bit count. The <CODE>/mm</CODE>
 400 notation specifies a CIDR netmask, a shown in <A HREF="TABLE1">Table 1</A>.</P>
 401
 402 <P>The <CODE>@LOCAL</CODE> name will allow browse data from all
 403 local interfaces. The <CODE>@IF(name)</CODE> name will allow
 404 browse data from the named interface. In both cases, CUPS only
 405 allows data from the network that the interface(s) are configured
 406 for - data arriving on the interface from a foreign network will
 407 <em>not</em> be allowed.</P>
 408
 409
 410 <H2 CLASS="title"><A NAME="BrowseDeny">BrowseDeny</A></H2>
 411
 412 <H3>Examples</H3>
 413
 414 <PRE CLASS="command">
 415 BrowseDeny from all
 416 BrowseDeny from none
 417 BrowseDeny from 192.0.2
 418 BrowseDeny from 192.0.2.0/24
 419 BrowseDeny from 192.0.2.0/255.255.255.0
 420 BrowseDeny from *.domain.com
 421 BrowseDeny from @LOCAL
 422 BrowseDeny from @IF(name)
 423 </PRE>
 424
 425 <H3>Description</H3>
 426
 427 <P>The <CODE>BrowseDeny</CODE> directive specifies a system or
 428 network to reject browse packets from. The default is to not deny
 429 browse packets from any hosts.</P>
 430
 431 <P>Host and domain name matching require that you enable the <A
 432 HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A>
 433 directive.</P>
 434
 435 <P>IP address matching supports exact matches, partial addresses that match
 436 networks using netmasks of 255.0.0.0, 255.255.0.0, and 255.255.255.0, or network
 437 addresses using the specified netmask or bit count. The <CODE>/mm</CODE>
 438 notation specifies a CIDR netmask, a shown in <A HREF="TABLE1">Table 1</A>.</P>
 439
 440 <P>The <CODE>@LOCAL</CODE> name will block browse data from all
 441 local interfaces. The <CODE>@IF(name)</CODE> name will block
 442 browse data from the named interface. In both cases, CUPS only
 443 blocks data from the network that the interface(s) are configured
 444 for - data arriving on the interface from a foreign network will
 445 <em>not</em> be blocked.</P>
 446
 447
 448 <H2 CLASS="title"><A NAME="BrowseInterval">BrowseInterval</A></H2>
 449
 450 <H3>Examples</H3>
 451
 452 <PRE CLASS="command">
 453 BrowseInterval 0
 454 BrowseInterval 30
 455 </PRE>
 456
 457 <H3>Description</H3>
 458
 459 <P>The <CODE>BrowseInterval</CODE> directive specifies the
 460 maximum amount of time between browsing updates. Specifying a
 461 value of 0 seconds disables outgoing browse updates but allows a
 462 server to receive printer information from other hosts.</P>
 463
 464 <P>The <CODE>BrowseInterval</CODE> value should always be less
 465 than the <A HREF="#BrowseTimeout"><CODE>BrowseTimeout</CODE></A>
 466 value. Otherwise printers and classes will disappear from client
 467 systems between updates.</P>
 468
 469
 470 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="BrowseLDAPBindDN">BrowseLDAPBindDN</A></H2>
 471
 472 <H3>Examples</H3>
 473
 474 <PRE CLASS="command">
 475 BrowseLDAPBindDN foo
 476 </PRE>
 477
 478 <H3>Description</H3>
 479
 480 <P>The <CODE>BrowseLDAPBindDN</CODE> directive specifies the LDAP
 481 domain name to use when listening for printer registrations. The
 482 default is undefined.</P>
 483
 484
 485 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/Mac OS X 10.6</SPAN><A NAME="BrowseLDAPCACertFile">BrowseLDAPCACertFile</A></H2>
 486
 487 <H3>Examples</H3>
 488
 489 <PRE CLASS="command">
 490 BrowseLDAPCACertFile /etc/cups/ssl/certs
 491 </PRE>
 492
 493 <H3>Description</H3>
 494
 495 <P>The <CODE>BrowseLDAPCACertFile</CODE> directive specifies the SSL certificate
 496 authority file to use for LDAP + SSL. The default is undefined.</P>
 497
 498
 499 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="BrowseLDAPDN">BrowseLDAPDN</A></H2>
 500
 501 <H3>Examples</H3>
 502
 503 <PRE CLASS="command">
 504 BrowseLDAPDN bar
 505 </PRE>
 506
 507 <H3>Description</H3>
 508
 509 <P>The <CODE>BrowseLDAPDN</CODE> directive specifies the LDAP
 510 domain name to use when registering local shared printers. The
 511 default is undefined.</P>
 512
 513
 514 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="BrowseLDAPPassword">BrowseLDAPPassword</A></H2>
 515
 516 <H3>Examples</H3>
 517
 518 <PRE CLASS="command">
 519 BrowseLDAPPassword foo123
 520 </PRE>
 521
 522 <H3>Description</H3>
 523
 524 <P>The <CODE>BrowseLDAPPassword</CODE> directive specifies the
 525 access password to use when connecting to the LDAP server. The
 526 default is undefined.</P>
 527
 528
 529 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="BrowseLDAPServer">BrowseLDAPServer</A></H2>
 530
 531 <H3>Examples</H3>
 532
 533 <PRE CLASS="command">
 534 BrowseLDAPServer localhost
 535 </PRE>
 536
 537 <H3>Description</H3>
 538
 539 <P>The <CODE>BrowseLDAPServer</CODE> directive specifies the name
 540 of the LDAP server to connect to. The default is undefined.</P>
 541
 542
 543 <H2 CLASS="title"><A NAME="BrowseLocalOptions">BrowseLocalOptions</A></H2>
 544
 545 <H3>Examples</H3>
 546
 547 <PRE CLASS="command">
 548 BrowseLocalOptions compression=yes
 549 BrowseLocalOptions encryption=required
 550 BrowseLocalOptions compression=yes&amp;encryption=required
 551 </PRE>
 552
 553 <H3>Description</H3>
 554
 555 <P>The <CODE>BrowseLocalOptions</CODE> directive specifies
 556 additional IPP backend options to advertise with local shared
 557 printers. The default is to not include any options.</P>
 558
 559
 560 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="BrowseLocalProtocols">BrowseLocalProtocols</A></H2>
 561
 562 <H3>Examples</H3>
 563
 564 <PRE CLASS="command">
 565 BrowseLocalProtocols all
 566 BrowseLocalProtocols none
 567 BrowseLocalProtocols cups
 568 BrowseLocalProtocols dnssd
 569 BrowseLocalProtocols ldap
 570 BrowseLocalProtocols lpd
 571 BrowseLocalProtocols slp
 572 BrowseLocalProtocols smb
 573 BrowseLocalProtocols cups dnssd
 574 </PRE>
 575
 576 <H3>Description</H3>
 577
 578 <P>The <CODE>BrowseLocalProtocols</CODE> directive specifies the
 579 protocols to use when advertising local shared printers on the
 580 network. Multiple protocols can be specified by separating them
 581 with spaces. The default is "<CODE>@CUPS_BROWSE_LOCAL_PROTOCOLS@</CODE>".</P>
 582
 583
 584 <H2 CLASS="title"><A NAME="BrowseOrder">BrowseOrder</A></H2>
 585
 586 <H3>Examples</H3>
 587
 588 <PRE CLASS="command">
 589 BrowseOrder allow,deny
 590 BrowseOrder deny,allow
 591 </PRE>
 592
 593 <H3>Description</H3>
 594
 595 <P>The <CODE>BrowseOrder</CODE> directive specifies the order of
 596 allow/deny processing. The default order is
 597 <CODE>deny,allow</CODE>:</P>
 598
 599 <UL>
 600
 601         <LI><CODE>allow,deny</CODE> - Deny browse packets by
 602         default, then check <CODE>BrowseAllow</CODE> lines
 603         followed by <CODE>BrowseDeny</CODE> lines.</LI>
 604
 605         <LI><CODE>deny,allow</CODE> - Allow browse packets by
 606         default, then check <CODE>BrowseDeny</CODE> lines
 607         followed by <CODE>BrowseAllow</CODE> lines.</LI>
 608
 609 </UL>
 610
 611
 612 <H2 CLASS="title"><A NAME="BrowsePoll">BrowsePoll</A></H2>
 613
 614 <H3>Examples</H3>
 615
 616 <PRE CLASS="command">
 617 BrowsePoll 192.0.2.2:631
 618 BrowsePoll host.domain.com:631
 619 </PRE>
 620
 621 <H3>Description</H3>
 622
 623 <P>The <CODE>BrowsePoll</CODE> directive polls a server for
 624 available printers once every <A
 625 HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A> seconds.
 626 Multiple <CODE>BrowsePoll</CODE> directives can be specified to
 627 poll multiple servers.</P>
 628
 629 <P>If <CODE>BrowseInterval</CODE> is set to 0 then the server is
 630 polled once every 30 seconds.</P>
 631
 632
 633 <H2 CLASS="title"><A NAME="BrowsePort">BrowsePort</A></H2>
 634
 635 <H3>Examples</H3>
 636
 637 <PRE CLASS="command">
 638 BrowsePort 631
 639 BrowsePort 9999
 640 </PRE>
 641
 642 <H3>Description</H3>
 643
 644 <P>The <CODE>BrowsePort</CODE> directive specifies the UDP port number
 645 used for browse packets. The default port number is 631.</P>
 646
 647 <BLOCKQUOTE><B>Note:</B>
 648
 649 <P>You must set the <CODE>BrowsePort</CODE> to the same value
 650 on all of the systems that you want to see.
 651
 652 </BLOCKQUOTE>
 653
 654
 655 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.10</SPAN><A NAME="BrowseProtocols">BrowseProtocols</A></H2>
 656
 657 <H3>Examples</H3>
 658
 659 <PRE CLASS="command">
 660 BrowseProtocols all
 661 BrowseProtocols none
 662 BrowseProtocols cups
 663 BrowseProtocols dnssd
 664 BrowseProtocols ldap
 665 BrowseProtocols lpd
 666 BrowseProtocols slp
 667 BrowseProtocols smb
 668 BrowseProtocols cups dnssd
 669 </PRE>
 670
 671 <H3>Description</H3>
 672
 673 <P>The <CODE>BrowseProtocols</CODE> directive specifies the
 674 protocols to use when showing and advertising shared printers on
 675 the local network. Multiple protocols can be specified by
 676 separating them with spaces. The default protocol is
 677 "<CODE>@CUPS_BROWSE_LOCAL_PROTOCOLS@</CODE>" for
 678 <A HREF="#BrowseLocalProtocols"><CODE>BrowseLocalProtocols</CODE></A> and
 679 "<CODE>@CUPS_BROWSE_REMOTE_PROTOCOLS@</CODE>" for
 680 <A HREF="#BrowseRemoteProtocols"><CODE>BrowseRemoteProtocols</CODE></A>.</P>
 681
 682 <BLOCKQUOTE><B>Note:</B>
 683
 684 <P>When using the <CODE>SLP</CODE> protocol, you must have at least
 685 one Directory Agent (DA) server on your network. Otherwise the
 686 CUPS scheduler (<CODE>cupsd</CODE>) will not respond to client
 687 requests for several seconds while polling the network.</P>
 688
 689 </BLOCKQUOTE>
 690
 691
 692 <H2 CLASS="title"><A NAME="BrowseRelay">BrowseRelay</A></H2>
 693
 694 <H3>Examples</H3>
 695
 696 <PRE CLASS="command">
 697 BrowseRelay 193.0.2.1 192.0.2.255
 698 BrowseRelay 193.0.2.0/255.255.255.0 192.0.2.255
 699 BrowseRelay 193.0.2.0/24 192.0.2.255
 700 BrowseRelay *.domain.com 192.0.2.255
 701 BrowseRelay host.domain.com 192.0.2.255
 702 </PRE>
 703
 704 <H3>Description</H3>
 705
 706 <P>The <CODE>BrowseRelay</CODE> directive specifies source and
 707 destination addresses for relaying browsing information from one
 708 host or network to another. Multiple <CODE>BrowseRelay</CODE>
 709 directives can be specified as needed.</P>
 710
 711 <P><CODE>BrowseRelay</CODE> is typically used on systems that
 712 bridge multiple subnets using one or more network interfaces. It
 713 can also be used to relay printer information from polled servers
 714 with the line:</P>
 715
 716 <PRE CLASS="command">
 717 BrowseRelay 127.0.0.1 @LOCAL
 718 </PRE>
 719
 720 <P>This effectively provides access to printers on a WAN for all
 721 clients on the LAN(s).</P>
 722
 723
 724 <H2 CLASS="title"><A NAME="BrowseRemoteOptions">BrowseRemoteOptions</A></H2>
 725
 726 <H3>Examples</H3>
 727
 728 <PRE CLASS="command">
 729 BrowseRemoteOptions compression=yes
 730 BrowseRemoteOptions encryption=required
 731 BrowseRemoteOptions ?compression=yes&amp;encryption=required
 732 </PRE>
 733
 734 <H3>Description</H3>
 735
 736 <P>The <CODE>BrowseRemoteOptions</CODE> directive specifies
 737 additional IPP backend options to include with remote shared
 738 printers. If the options string begins with a question mark (?),
 739 the options replace any options specified by the remote server.
 740 The default is to not include any options.</P>
 741
 742
 743 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="BrowseRemoteProtocols">BrowseRemoteProtocols</A></H2>
 744
 745 <H3>Examples</H3>
 746
 747 <PRE CLASS="command">
 748 BrowseRemoteProtocols all
 749 BrowseRemoteProtocols none
 750 BrowseRemoteProtocols cups
 751 BrowseRemoteProtocols ldap
 752 BrowseRemoteProtocols slp
 753 </PRE>
 754
 755 <H3>Description</H3>
 756
 757 <P>The <CODE>BrowseRemoteProtocols</CODE> directive specifies the
 758 protocols to use when finding remote shared printers on the
 759 network. Multiple protocols can be specified by separating them
 760 with spaces. The default is "<CODE>@CUPS_BROWSE_REMOTE_PROTOCOLS@</CODE>".</P>
 761
 762
 763 <H2 CLASS="title"><A NAME="BrowseShortNames">BrowseShortNames</A></H2>
 764
 765 <H3>Examples</H3>
 766
 767 <PRE CLASS="command">
 768 BrowseShortNames Yes
 769 BrowseShortNames No
 770 </PRE>
 771
 772 <H3>Description</H3>
 773
 774 <P>The <CODE>BrowseShortNames</CODE> directive specifies whether
 775 or not short names are used for remote printers when possible.
 776 Short names are just the remote printer name, without the server
 777 ("printer"). If more than one remote printer is detected with the
 778 same name, the printers will have long names ("printer@server1",
 779 "printer@server2".)</P>
 780
 781 <P>The default value for this option is <CODE>@CUPS_BROWSE_SHORT_NAMES@</CODE>.</P>
 782
 783
 784 <H2 CLASS="title"><A NAME="BrowseTimeout">BrowseTimeout</A></H2>
 785
 786 <H3>Examples</H3>
 787
 788 <PRE CLASS="command">
 789 BrowseTimeout 300
 790 BrowseTimeout 60
 791 </PRE>
 792
 793 <H3>Description</H3>
 794
 795 <P>The <CODE>BrowseTimeout</CODE> directive sets the timeout for
 796 printer or class information that is received in browse packets.
 797 Once a printer or class times out it is removed from the list of
 798 available destinations.</P>
 799
 800 <P>The <CODE>BrowseTimeout</CODE> value should always be greater
 801 than the <A
 802 HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A> value.
 803 Otherwise printers and classes will disappear from client systems
 804 between updates.</P>
 805
 806
 807 <H2 CLASS="title"><A NAME="BrowseWebIF">BrowseWebIF</A></H2>
 808
 809 <H3>Examples</H3>
 810
 811 <PRE CLASS="command">
 812 BrowseWebIF On
 813 BrowseWebIF Off
 814 </PRE>
 815
 816 <H3>Description</H3>
 817
 818 <P>The <CODE>BrowseWebIF</CODE> directive controls whether the CUPS web
 819 interface is advertised via DNS-SD. The default setting is
 820 <CODE>Off</CODE>.</P>
 821
 822
 823 <H2 CLASS="title"><A NAME="Browsing">Browsing</A></H2>
 824
 825 <H3>Examples</H3>
 826
 827 <PRE CLASS="command">
 828 Browsing On
 829 Browsing Off
 830 </PRE>
 831
 832 <H3>Description</H3>
 833
 834 <P>The <CODE>Browsing</CODE> directive controls whether or not
 835 network printer browsing is enabled. The default setting is
 836 <CODE>@CUPS_BROWSING@</CODE>.</P>
 837
 838 <P>This directive does not enable sharing of local printers by
 839 itself; you must also use the <A
 840 HREF="#BrowseAddress"><CODE>BrowseAddress</CODE></A> or <A
 841 HREF="#BrowseProtocols"><CODE>BrowseProtocols</CODE></A>
 842 directives to advertise local printers to other systems.</P>
 843
 844 <BLOCKQUOTE><B>Note:</B>
 845
 846 <P>If you are using HP-UX 10.20 and a subnet that is not 24,
 847 16, or 8 bits, printer browsing (and in fact all broadcast
 848 reception) will not work. This problem appears to be fixed in
 849 HP-UX 11.0.</P>
 850
 851 </BLOCKQUOTE>
 852
 853
 854 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="Classification">Classification</A></H2>
 855
 856 <H3>Examples</H3>
 857
 858 <PRE CLASS="command">
 859 Classification
 860 Classification classified
 861 Classification confidential
 862 Classification secret
 863 Classification topsecret
 864 Classification unclassified
 865 </PRE>
 866
 867 <H3>Description</H3>
 868
 869 <P>The <CODE>Classification</CODE> directive sets the
 870 classification level on the server. When this option is set, at
 871 least one of the banner pages is forced to the classification
 872 level, and the classification is placed on each page of output.
 873 The default is no classification level.</P>
 874
 875
 876 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.10</SPAN><A NAME="ClassifyOverride">ClassifyOverride</A></H2>
 877
 878 <H3>Examples</H3>
 879
 880 <PRE CLASS="command">
 881 ClassifyOverride Yes
 882 ClassifyOverride No
 883 </PRE>
 884
 885 <H3>Description</H3>
 886
 887 <P>The <CODE>ClassifyOverride</CODE> directive specifies whether
 888 users can override the default classification level on the
 889 server. When the server classification is set, users can change
 890 the classification using the <CODE>job-sheets</CODE> option and
 891 can choose to only print one security banner before or after the
 892 job. If the <CODE>job-sheets</CODE> option is set to
 893 <CODE>none</CODE> then the server default classification is
 894 used.</P>
 895
 896 <P>The default is to not allow classification overrides.</P>
 897
 898
 899 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.15</SPAN><A NAME="ConfigFilePerm">ConfigFilePerm</A></H2>
 900
 901 <H3>Examples</H3>
 902
 903 <PRE CLASS="command">
 904 ConfigFilePerm 0644
 905 ConfigFilePerm 0640
 906 </PRE>
 907
 908 <H3>Description</H3>
 909
 910 <P>The <CODE>ConfigFilePerm</CODE> directive specifies the
 911 permissions to use when writing configuration files. The default
 912 is @CUPS_CONFIG_FILE_PERM@.</P>
 913
 914
 915 <H2 CLASS="title"><A NAME="DataDir">DataDir</A></H2>
 916
 917 <H3>Examples</H3>
 918
 919 <PRE CLASS="command">
 920 DataDir /usr/share/cups
 921 </PRE>
 922
 923 <H3>Description</H3>
 924
 925 <P>The <CODE>DataDir</CODE> directive sets the directory to use
 926 for data files.</P>
 927
 928
 929 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="DefaultAuthType">DefaultAuthType</A></H2>
 930
 931 <H3>Examples</H3>
 932
 933 <PRE CLASS="command">
 934 DefaultAuthType Basic
 935 DefaultAuthType BasicDigest
 936 DefaultAuthType Digest
 937 DefaultAuthType Negotiate
 938 </PRE>
 939
 940 <H3>Description</H3>
 941
 942 <P>The <CODE>DefaultAuthType</CODE> directive specifies the type
 943 of authentication to use for IPP operations that require a
 944 username. The default is <CODE>Basic</CODE>.</P>
 945
 946
 947 <H2 CLASS="title"><A NAME="DefaultCharset">DefaultCharset</A></H2>
 948
 949 <H3>Examples</H3>
 950
 951 <PRE CLASS="command">
 952 DefaultCharset utf-8
 953 DefaultCharset iso-8859-1
 954 DefaultCharset windows-1251
 955 </PRE>
 956
 957 <H3>Description</H3>
 958
 959 <P>The <CODE>DefaultCharset</CODE> directive sets the default
 960 character set to use for client connections. The default
 961 character set is <CODE>utf-8</CODE> but is overridden by the
 962 character set for the language specified by the client or the
 963 <CODE>DefaultLanguage</CODE> directive.</P>
 964
 965
 966 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="DefaultEncryption">DefaultEncryption</A></H2>
 967
 968 <H3>Examples</H3>
 969
 970 <PRE CLASS="command">
 971 DefaultEncryption Never
 972 DefaultEncryption IfRequested
 973 DefaultEncryption Required
 974 </PRE>
 975
 976 <H3>Description</H3>
 977
 978 <P>The <CODE>DefaultEncryption</CODE> directive specifies the
 979 type of encryption to use when performing authentication. The
 980 default is <CODE>Required</CODE>.</P>
 981
 982
 983 <H2 CLASS="title"><A NAME="DefaultLanguage">DefaultLanguage</A></H2>
 984
 985 <H3>Examples</H3>
 986
 987 <PRE CLASS="command">
 988 DefaultLanguage de
 989 DefaultLanguage en
 990 DefaultLanguage es
 991 DefaultLanguage fr
 992 DefaultLanguage it
 993 </PRE>
 994
 995 <H3>Description</H3>
 996
 997 <P>The <CODE>DefaultLanguage</CODE> directive specifies the
 998 default language to use for client connections. Setting the
 999 default language also sets the default character set if a
1000 language localization file exists for it. The default language
1001 is "en" for English.</P>
1002
1003
1004 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/Mac OS X 10.6</SPAN><A NAME="DefaultPaperSize">DefaultPaperSize</A></H2>
1005
1006 <H3>Examples</H3>
1007
1008 <PRE CLASS="command">
1009 DefaultPaperSize Letter
1010 DefaultPaperSize A4
1011 DefaultPaperSize Auto
1012 DefaultPaperSize None
1013 </PRE>
1014
1015 <H3>Description</H3>
1016
1017 <P>The <CODE>DefaultPaperSize</CODE> directive specifies the default paper
1018 size to use when creating new printers. The default is <CODE>Auto</CODE>
1019 which uses a paper size appropriate for the system default locale. A value
1020 of <CODE>None</CODE> tells the scheduler to not set the default paper
1021 size.</P>
1022
1023
1024 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="DefaultPolicy">DefaultPolicy</A></H2>
1025
1026 <H3>Examples</H3>
1027
1028 <PRE CLASS="command">
1029 DefaultPolicy default
1030 DefaultPolicy foo
1031 </PRE>
1032
1033 <H3>Description</H3>
1034
1035 <P>The <CODE>DefaultPolicy</CODE> directive specifies the default
1036 policy to use for IPP operation. The default is
1037 <CODE>default</CODE>.</P>
1038
1039
1040 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="DefaultShared">DefaultShared</A></H2>
1041
1042 <H3>Examples</H3>
1043
1044 <PRE CLASS="command">
1045 DefaultShared yes
1046 DefaultShared no
1047 </PRE>
1048
1049 <H3>Description</H3>
1050
1051 <P>The <CODE>DefaultShared</CODE> directive specifies whether
1052 printers are shared (published) by default. The default is
1053 <CODE>@CUPS_DEFAULT_SHARED@</CODE>.</P>
1054
1055
1056 <H2 CLASS="title"><A NAME="Deny">Deny</A></H2>
1057
1058 <H3>Examples</H3>
1059
1060 <PRE CLASS="command">
1061 &lt;Location /path&gt;
1062   ..
1063   Deny from All
1064   Deny from None
1065   Deny from *.domain.com
1066   Deny from .domain.com
1067   Deny from host.domain.com
1068   Deny from nnn.*
1069   Deny from nnn.nnn.*
1070   Deny from nnn.nnn.nnn.*
1071   Deny from nnn.nnn.nnn.nnn
1072   Deny from nnn.nnn.nnn.nnn/mm
1073   Deny from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
1074   Deny from xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx
1075   Deny from @LOCAL
1076   Deny from @IF(name)
1077 &lt;/Location&gt;
1078 </PRE>
1079
1080 <H3>Description</H3>
1081
1082 <P>The <CODE>Deny</CODE> directive specifies a hostname, IP
1083 address, or network that is denied access to the server.
1084 <CODE>Deny</CODE> directives are cummulative, so multiple
1085 <CODE>Deny</CODE> directives can be used to allow access for
1086 multiple hosts or networks.</P>
1087
1088 <P>Host and domain name matching require that you enable the <A
1089 HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A>
1090 directive.</P>
1091
1092 <P>The <CODE>/mm</CODE> notation specifies a CIDR netmask, a shown in
1093 <A HREF="TABLE1">Table 1</A>.</P>
1094
1095 <P>The <CODE>@LOCAL</CODE> name will deny access from all local
1096 interfaces. The <CODE>@IF(name)</CODE> name will deny access from
1097 the named interface. In both cases, CUPS only denies access from
1098 the network that the interface(s) are configured for - requests
1099 arriving on the interface from a foreign network will
1100 <em>not</em> be denied.</P>
1101
1102 <P>The <CODE>Deny</CODE> directive must appear inside a <A
1103 HREF="#Location"><CODE>Location</CODE></A> or <A
1104 HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
1105
1106
1107 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/Mac OS X 10.6</SPAN><A NAME="DirtyCleanInterval">DirtyCleanInterval</A></H2>
1108
1109 <H3>Examples</H3>
1110
1111 <PRE CLASS="command">
1112 DirtyCleanInterval 30
1113 DirtyCleanInterval 0
1114 </PRE>
1115
1116 <H3>Description</H3>
1117
1118 <P>The <CODE>DirtyCleanInterval</CODE> directive specifies the number of
1119 seconds to wait before updating configuration and state files for printers,
1120 classes, subscriptions, and jobs. The default is 30 seconds. A value of 0
1121 causes the update to occur as soon as possible, typically within a few
1122 milliseconds.</P>
1123
1124
1125 <H2 CLASS="title"><A NAME="DocumentRoot">DocumentRoot</A></H2>
1126
1127 <H3>Examples</H3>
1128
1129 <PRE CLASS="command">
1130 DocumentRoot /usr/share/doc/cups
1131 DocumentRoot /foo/bar/doc/cups
1132 </PRE>
1133
1134 <H3>Description</H3>
1135
1136 <P>The <CODE>DocumentRoot</CODE> directive specifies the location
1137 of web content for the HTTP server in CUPS. If an absolute path
1138 is not specified then it is assumed to be relative to the <A
1139 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
1140 default directory is <VAR>@CUPS_DOCROOT@</VAR>.</P>
1141
1142 <P>Documents are first looked up in a sub-directory for the
1143 primary language requested by the client (e.g.
1144 <VAR>@CUPS_DOCROOT@/fr/...</VAR>) and then directly under
1145 the <CODE>DocumentRoot</CODE> directory (e.g.
1146 <VAR>@CUPS_DOCROOT@/...</VAR>), so it is possible to
1147 localize the web content by providing subdirectories for each
1148 language needed.</P>
1149
1150
1151 <H2 CLASS="title"><A NAME="Encryption">Encryption</A></H2>
1152
1153 <H3>Examples</H3>
1154
1155 <PRE CLASS="command">
1156 &lt;Location /path&gt;
1157   ...
1158   Encryption Never
1159   Encryption IfRequested
1160   Encryption Required
1161 &lt;/Location&gt;
1162 </PRE>
1163
1164 <H3>Description</H3>
1165
1166 <P>The <CODE>Encryption</CODE> directive must appear instead a <A
1167 HREF="#Location"><CODE>Location</CODE></A> or <A
1168 HREF="#Limit"><CODE>Limit</CODE></A> section and specifies the
1169 encryption settings for that location. The default setting is
1170 <CODE>IfRequested</CODE> for all locations.</P>
1171
1172
1173 <H2 CLASS="title"><A NAME="ErrorLog">ErrorLog</A></H2>
1174
1175 <H3>Examples</H3>
1176
1177 <PRE CLASS="command">
1178 ErrorLog /var/log/cups/error_log
1179 ErrorLog /var/log/cups/error_log-%s
1180 ErrorLog syslog
1181 </PRE>
1182
1183 <H3>Description</H3>
1184
1185 <P>The <CODE>ErrorLog</CODE> directive sets the name of the error
1186 log file. If the filename is not absolute then it is assumed to
1187 be relative to the <A
1188 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
1189 default error log file is <VAR>@CUPS_LOGDIR@/error_log</VAR>.</P>
1190
1191 <P>The server name can be included in the filename by using
1192 <CODE>%s</CODE> in the name.</P>
1193
1194 <P>The special name "syslog" can be used to send the error
1195 information to the system log instead of a plain file.</P>
1196
1197
1198 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.3/Mac OS X 10.5</SPAN><A NAME="ErrorPolicy">ErrorPolicy</A></H2>
1199
1200 <H3>Examples</H3>
1201
1202 <PRE CLASS="command">
1203 ErrorPolicy abort-job
1204 ErrorPolicy retry-job
1205 ErrorPolicy stop-printer
1206 </PRE>
1207
1208 <H3>Description</H3>
1209
1210 <P>The <CODE>ErrorPolicy</CODE> directive defines the default policy that
1211 is used when a backend is unable to send a print job to the
1212 printer.</P>
1213
1214 <P>The following values are supported:</P>
1215
1216 <UL>
1217
1218         <LI><CODE>abort-job</CODE> - Abort the job and proceed
1219         with the next job in the queue</LI>
1220
1221         <LI><CODE>retry-job</CODE> - Retry the job after waiting
1222         for N seconds; the <VAR>cupsd.conf</VAR> <A
1223         HREF="#JobRetryInterval"><CODE>JobRetryInterval</CODE></A>
1224         directive controls the value of N</LI>
1225
1226         <LI><CODE>retry-this-job</CODE> - Retry the current job immediately
1227         and indefinitely.</LI>
1228
1229         <LI><CODE>stop-printer</CODE> - Stop the printer and keep
1230         the job for future printing; this is the default
1231         value</LI>
1232
1233 </UL>
1234
1235
1236
1237 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/Mac OS X 10.6</SPAN><A NAME="FatalErrors">FatalErrors</A></H2>
1238
1239 <H3>Examples</H3>
1240
1241 <PRE CLASS="command">
1242 FatalErrors none
1243 FatalErrors all
1244 FatalErrors browse
1245 FatalErrors config
1246 FatalErrors listen
1247 FatalErrors log
1248 FatalErrors permissions
1249 FatalErrors all -permissions
1250 FatalErrors config permissions log
1251 </PRE>
1252
1253 <H3>Description</H3>
1254
1255 <P>The <CODE>FatalErrors</CODE> directive determines whether certain kinds of
1256 errors are fatal. The following kinds of errors are currently recognized:</P>
1257
1258 <UL>
1259
1260         <LI><CODE>none</CODE> - No errors are fatal</LI>
1261
1262         <LI><CODE>all</CODE> - All of the errors below are fatal</LI>
1263
1264         <LI><CODE>browse</CODE> - Browsing initialization errors are fatal,
1265         for example failed binding to the CUPS browse port or failed connections
1266         to LDAP servers</LI>
1267
1268         <LI><CODE>config</CODE> - Configuration file syntax errors are
1269         fatal</LI>
1270
1271         <LI><CODE>listen</CODE> - Listen or Port errors are fatal, except for
1272         IPv6 failures on the loopback or "any" addresses</LI>
1273
1274         <LI><CODE>log</CODE> - Log file creation or write errors are fatal</LI>
1275
1276         <LI><CODE>permissions</CODE> - Bad startup file permissions are
1277         fatal, for example shared SSL certificate and key files with world-
1278         read permissions</LI>
1279
1280 </UL>
1281
1282 <P>Multiple errors can be listed, and the form "-kind" can be used with
1283 <CODE>all</CODE> to remove specific kinds of errors. The default setting is
1284 <CODE>@CUPS_FATAL_ERRORS@</CODE>.</P>
1285
1286
1287 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.18</SPAN><A NAME="FileDevice">FileDevice</A></H2>
1288
1289 <H3>Examples</H3>
1290
1291 <PRE CLASS="command">
1292 FileDevice Yes
1293 FileDevice No
1294 </PRE>
1295
1296 <H3>Description</H3>
1297
1298 <P>The <CODE>FileDevice</CODE> directive determines whether the
1299 scheduler allows new printers to be added using device URIs of
1300 the form <CODE>file:/filename</CODE>. File devices are most often
1301 used to test new printer drivers and do not support raw file
1302 printing.</P>
1303
1304 <P>The default setting is <CODE>No</CODE>.</P>
1305
1306 <BLOCKQUOTE><B>Note:</B>
1307
1308 <P>File devices are managed by the scheduler. Since the
1309 scheduler normally runs as the root user, file devices
1310 can be used to overwrite system files and potentially
1311 gain unauthorized access to the system. If you must
1312 create printers using file devices, we recommend that
1313 you set the <CODE>FileDevice</CODE> directive to
1314 <CODE>Yes</CODE> for only as long as you need to add the
1315 printers to the system, and then reset the directive to
1316 <CODE>No</CODE>.</P>
1317
1318 </BLOCKQUOTE>
1319
1320
1321 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.3</SPAN><A NAME="FilterLimit">FilterLimit</A></H2>
1322
1323 <H3>Examples</H3>
1324
1325 <PRE CLASS="command">
1326 FilterLimit 0
1327 FilterLimit 200
1328 FilterLimit 1000
1329 </PRE>
1330
1331 <H3>Description</H3>
1332
1333 <P>The <CODE>FilterLimit</CODE> directive sets the maximum cost
1334 of all running job filters. It can be used to limit the number of
1335 filter programs that are run on a server to minimize disk,
1336 memory, and CPU resource problems. A limit of 0 disables filter
1337 limiting.</P>
1338
1339 <P>An average print to a non-PostScript printer needs a filter
1340 limit of about 200. A PostScript printer needs about half that
1341 (100). Setting the limit below these thresholds will effectively
1342 limit the scheduler to printing a single job at any time.</P>
1343
1344 <P>The default limit is 0.</P>
1345
1346
1347 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.16</SPAN><A NAME="FilterNice">FilterNice</A></H2>
1348
1349 <H3>Examples</H3>
1350
1351 <PRE CLASS="command">
1352 FilterNice 0
1353 FilterNice 10
1354 FilterNice 19
1355 </PRE>
1356
1357 <H3>Description</H3>
1358
1359 <P>The <CODE>FilterNice</CODE> directive sets the <B>nice(1)</B>
1360 value to assign to filter processes. The nice value ranges from
1361 0, the highest priority, to 19, the lowest priority. The default
1362 is 0.</P>
1363
1364
1365 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.3</SPAN><A NAME="FontPath">FontPath</A></H2>
1366
1367 <H3>Examples</H3>
1368
1369 <PRE CLASS="command">
1370 FontPath /foo/bar/fonts
1371 FontPath /usr/share/cups/fonts:/foo/bar/fonts
1372 </PRE>
1373
1374 <H3>Description</H3>
1375
1376 <P>The <CODE>FontPath</CODE> directive specifies the font path to
1377 use when searching for fonts. The default font path is
1378 <CODE>/usr/share/cups/fonts</CODE>.</P>
1379
1380
1381 <H2 CLASS="title"><A NAME="Group">Group</A></H2>
1382
1383 <H3>Examples</H3>
1384
1385 <PRE CLASS="command">
1386 Group lp
1387 Group nobody
1388 </PRE>
1389
1390 <H3>Description</H3>
1391
1392 <P>The <CODE>Group</CODE> directive specifies the UNIX group that
1393 filter and CGI programs run as. The default group is
1394 system-specific but is usually <CODE>lp</CODE> or
1395 <CODE>nobody</CODE>.</P>
1396
1397
1398 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.10</SPAN><A NAME="HideImplicitMembers">HideImplicitMembers</A></H2>
1399
1400 <H3>Examples</H3>
1401
1402 <PRE CLASS="command">
1403 HideImplicitMembers Yes
1404 HideImplicitMembers No
1405 </PRE>
1406
1407 <H3>Description</H3>
1408
1409 <P>The <CODE>HideImplicitMembers</CODE> directive controls
1410 whether the individual printers in an implicit class are hidden
1411 from the user. The default is <CODE>Yes</CODE>.</P>
1412
1413 <P><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
1414 must be enabled for this directive to have any effect.</P>
1415
1416
1417 <H2 CLASS="title"><A NAME="HostNameLookups">HostNameLookups</A></H2>
1418
1419 <H3>Examples</H3>
1420
1421 <PRE CLASS="command">
1422 HostNameLookups On
1423 HostNameLookups Off
1424 HostNameLookups Double
1425 </PRE>
1426
1427 <H3>Description</H3>
1428
1429 <P>The <CODE>HostNameLookups</CODE> directive controls whether or
1430 not CUPS looks up the hostname for connecting clients. The
1431 <CODE>Double</CODE> setting causes CUPS to verify that the
1432 hostname resolved from the address matches one of the addresses
1433 returned for that hostname. <CODE>Double</CODE> lookups also
1434 prevent clients with unregistered addresses from connecting to
1435 your server.</P>
1436
1437 <P>The default is <CODE>Off</CODE> to avoid the potential server
1438 performance problems with hostname lookups. Set this option to
1439 <CODE>On</CODE> or <CODE>Double</CODE> only if absolutely
1440 required.</P>
1441
1442
1443 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.10</SPAN><A NAME="ImplicitAnyClasses">ImplicitAnyClasses</A></H2>
1444
1445 <H3>Examples</H3>
1446
1447 <PRE CLASS="command">
1448 ImplicitAnyClasses On
1449 ImplicitAnyClasses Off
1450 </PRE>
1451
1452 <H3>Description</H3>
1453
1454 <P>The <CODE>ImplicitAnyClasses</CODE> directive controls
1455 whether implicit classes for local and remote printers are
1456 created with the name <CODE>AnyPrinter</CODE>. The default
1457 setting is <CODE>Off</CODE>.</P>
1458
1459 <P><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A>
1460 must be enabled for this directive to have any effect.</P>
1461
1462
1463 <H2 CLASS="title"><A NAME="ImplicitClasses">ImplicitClasses</A></H2>
1464
1465 <H3>Examples</H3>
1466
1467 <PRE CLASS="command">
1468 ImplicitClasses On
1469 ImplicitClasses Off
1470 </PRE>
1471
1472 <H3>Description</H3>
1473
1474 <P>The <CODE>ImplicitClasses</CODE> directive controls whether
1475 implicit classes are created based upon the available network
1476 printers and classes. The default setting is
1477 <CODE>@CUPS_IMPLICIT_CLASSES@</CODE> but is automatically turned
1478 <CODE>Off</CODE> if <A HREF="#Browsing"><CODE>Browsing</CODE></A> is turned
1479 <CODE>Off</CODE>.</P>
1480
1481
1482 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.9</SPAN><A NAME="Include">Include</A></H2>
1483
1484 <H3>Examples</H3>
1485
1486 <PRE CLASS="command">
1487 Include filename
1488 Include /foo/bar/filename
1489 </PRE>
1490
1491 <H3>Description</H3>
1492
1493 <P>The <CODE>Include</CODE> directive includes the named file in
1494 the <CODE>cupsd.conf</CODE> file. If no leading path is provided,
1495 the file is assumed to be relative to the <A
1496 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory.</P>
1497
1498
1499 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="JobRetryInterval">JobRetryInterval</A></H2>
1500
1501 <H3>Examples</H3>
1502
1503 <PRE CLASS="command">
1504 JobRetryInterval 30
1505 JobRetryInterval 120
1506 </PRE>
1507
1508 <H3>Description</H3>
1509
1510 <P>The <CODE>JobRetryInterval</CODE> directive specifies the
1511 number of seconds to wait before retrying a job. This is
1512 typically used for fax queues but can also be used with normal
1513 print queues whose error policy is <CODE>retry-job</CODE>. The
1514 default is 30 seconds.</P>
1515
1516
1517 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/Mac OS X 10.6</SPAN><A NAME="JobKillDelay">JobKillDelay</A></H2>
1518
1519 <H3>Examples</H3>
1520
1521 <PRE CLASS="command">
1522 JobKillDelay 30
1523 JobKillDelay 120
1524 </PRE>
1525
1526 <H3>Description</H3>
1527
1528 <P>The <CODE>JobKillDelay</CODE> directive specifies the number of seconds to
1529 wait before killing the filters and backend associated with a canceled or held
1530 job. The default is 30 seconds.</P>
1531
1532
1533 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="JobRetryLimit">JobRetryLimit</A></H2>
1534
1535 <H3>Examples</H3>
1536
1537 <PRE CLASS="command">
1538 JobRetryLimit 5
1539 JobRetryLimit 50
1540 </PRE>
1541
1542 <H3>Description</H3>
1543
1544 <P>The <CODE>JobRetryLimit</CODE> directive specifies the maximum
1545 number of times the scheduler will try to print a job. This is
1546 typically used for fax queues but can also be used with normal
1547 print queues whose error policy is <CODE>retry-job</CODE>. The
1548 default is 5 times.</P>
1549
1550
1551 <H2 CLASS="title"><A NAME="KeepAlive">KeepAlive</A></H2>
1552
1553 <H3>Examples</H3>
1554
1555 <PRE CLASS="command">
1556 KeepAlive On
1557 KeepAlive Off
1558 </PRE>
1559
1560 <H3>Description</H3>
1561
1562 <P>The <CODE>KeepAlive</CODE> directive controls whether or not
1563 to support persistent HTTP connections. The default is
1564 <CODE>On</CODE>.</P>
1565
1566 <P>HTTP/1.1 clients automatically support persistent connections,
1567 while HTTP/1.0 clients must specifically request them using the
1568 <CODE>Keep-Alive</CODE> attribute in the <CODE>Connection:</CODE>
1569 field of each request.</P>
1570
1571
1572 <H2 CLASS="title"><A NAME="KeepAliveTimeout">KeepAliveTimeout</A></H2>
1573
1574 <H3>Examples</H3>
1575
1576 <PRE CLASS="command">
1577 KeepAliveTimeout 60
1578 KeepAliveTimeout 30
1579 </PRE>
1580
1581 <H3>Description</H3>
1582
1583 <P>The <CODE>KeepAliveTimeout</CODE> directive controls how long
1584 a persistent HTTP connection will remain open after the last
1585 request. The default is 30 seconds.</P>
1586
1587
1588 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="Limit">Limit (Location)</A></H2>
1589
1590 <H3>Examples</H3>
1591
1592 <PRE CLASS="command">
1593 &lt;Location /path&gt;
1594   &lt;Limit GET POST&gt;
1595   ...
1596   &lt;/Limit&gt;
1597
1598   &lt;Limit ALL&gt;
1599   ...
1600   &lt;/Limit&gt;
1601 &lt;/Location&gt;
1602 </PRE>
1603
1604 <H3>Description</H3>
1605
1606 <P>The <CODE>Limit</CODE> directive groups access control
1607 directives for specific types of HTTP requests and must appear
1608 inside a <A HREF="#Location"><CODE>Location</CODE></A> section.
1609 Access can be limited for individual request types
1610 (<CODE>DELETE</CODE>, <CODE>GET</CODE>, <CODE>HEAD</CODE>,
1611 <CODE>OPTIONS</CODE>, <CODE>POST</CODE>, <CODE>PUT</CODE>, and
1612 <CODE>TRACE</CODE>) or for all request types (<CODE>ALL</CODE>).
1613 The request type names are case-sensitive for compatibility with
1614 Apache.</P>
1615
1616
1617 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="LimitIPP">Limit (Policy)</A></H2>
1618
1619 <H3>Examples</H3>
1620
1621 <PRE CLASS="command">
1622 &lt;Policy name&gt;
1623   &lt;Limit CUPS-Add-Modify-Printer CUPS-Delete-Printer&gt;
1624   ...
1625   &lt;/Limit&gt;
1626
1627   &lt;Limit All&gt;
1628   ...
1629   &lt;/Limit&gt;
1630 &lt;/Policy&gt;
1631 </PRE>
1632
1633 <H3>Description</H3>
1634
1635 <P>When included in <A HREF="#Policy"><CODE>Policy</CODE></A>
1636 sections, the <CODE>Limit</CODE> directive groups access control
1637 directives for specific IPP operations. Multiple operations can
1638 be listed, separated by spaces. Table 2 lists the supported
1639 operations.</P>
1640
1641 <DIV CLASS="table"><TABLE SUMMARY="Supported IPP Operations">
1642 <CAPTION>Table 2: <A NAME="TABLE2">Supported IPP Operations</A></CAPTION>
1643 <THEAD>
1644 <TR>
1645         <TH>Operation Name</TH>
1646         <TH>Description</TH>
1647 </TR>
1648 </THEAD>
1649 <TBODY>
1650 <TR>
1651         <TD>All</TD>
1652         <TD>All operations - used as the default limit for
1653         operations that are not listed</TD>
1654 </TR>
1655 <TR>
1656         <TD>Cancel-Job</TD>
1657         <TD>Cancel a job</TD>
1658 </TR>
1659 <TR>
1660         <TD>Cancel-Subscription</TD>
1661         <TD>Cancel a subscription</TD>
1662 </TR>
1663 <TR>
1664         <TD>Create-Job</TD>
1665         <TD>Create a new, empty job</TD>
1666 </TR>
1667 <TR>
1668         <TD>Create-Job-Subscription</TD>
1669         <TD>Creates a notification subscription on a job</TD>
1670 </TR>
1671 <TR>
1672         <TD>Create-Printer-Subscription</TD>
1673         <TD>Creates a notification subscription on a printer</TD>
1674 </TR>
1675 <TR>
1676         <TD>CUPS-Accept-Jobs</TD>
1677         <TD>Sets the printer-is-accepting-jobs value for a printer to true</TD>
1678 </TR>
1679 <TR>
1680         <TD>CUPS-Add-Modify-Class</TD>
1681         <TD>Adds or modifies a class</TD>
1682 </TR>
1683 <TR>
1684         <TD>CUPS-Add-Modify-Printer</TD>
1685         <TD>Adds or modifies a printer</TD>
1686 </TR>
1687 <TR>
1688         <TD>CUPS-Authenticate-Job</TD>
1689         <TD>Authenticates a job for printing</TD>
1690 </TR>
1691 <TR>
1692         <TD>CUPS-Delete-Class</TD>
1693         <TD>Deletes a class</TD>
1694 </TR>
1695 <TR>
1696         <TD>CUPS-Delete-Printer</TD>
1697         <TD>Deletes a printer</TD>
1698 </TR>
1699 <TR>
1700         <TD>CUPS-Get-Classes</TD>
1701         <TD>Gets a list of classes</TD>
1702 </TR>
1703 <TR>
1704         <TD>CUPS-Get-Default</TD>
1705         <TD>Gets the (network/server) default printer or class</TD>
1706 </TR>
1707 <TR>
1708         <TD>CUPS-Get-Devices</TD>
1709         <TD>Gets a list of available devices</TD>
1710 </TR>
1711 <TR>
1712         <TD>CUPS-Get-PPDs</TD>
1713         <TD>Gets a list of available manufacturers or drivers</TD>
1714 </TR>
1715 <TR>
1716         <TD>CUPS-Get-Printers</TD>
1717         <TD>Gets a list of printers and/or classes</TD>
1718 </TR>
1719 <TR>
1720         <TD>CUPS-Move-Job</TD>
1721         <TD>Moves a job to a new destination</TD>
1722 </TR>
1723 <TR>
1724         <TD>CUPS-Reject-Jobs</TD>
1725         <TD>Sets the printer-is-accepting-jobs value for a printer to false</TD>
1726 </TR>
1727 <TR>
1728         <TD>CUPS-Set-Default</TD>
1729         <TD>Sets the network/server default printer or class</TD>
1730 </TR>
1731 <TR>
1732         <TD>Disable-Printer</TD>
1733         <TD>Sets the printer-state value for a printer to stopped</TD>
1734 </TR>
1735 <TR>
1736         <TD>Enable-Printer</TD>
1737         <TD>Sets the printer-state value for a printer to idle/processing</TD>
1738 </TR>
1739 <TR>
1740         <TD>Get-Job-Attributes</TD>
1741         <TD>Gets information about a job</TD>
1742 </TR>
1743 <TR>
1744         <TD>Get-Jobs</TD>
1745         <TD>Gets a list of jobs</TD>
1746 </TR>
1747 <TR>
1748         <TD>Get-Notifications</TD>
1749         <TD>Gets a list of events</TD>
1750 </TR>
1751 <TR>
1752         <TD>Get-Printer-Attributes</TD>
1753         <TD>Gets informaion about a printer or class</TD>
1754 </TR>
1755 <TR>
1756         <TD>Get-Subscription-Attributes</TD>
1757         <TD>Gets informaion about a notification subscription</TD>
1758 </TR>
1759 <TR>
1760         <TD>Get-Subscriptions</TD>
1761         <TD>Gets a list of notification subscriptions</TD>
1762 </TR>
1763 <TR>
1764         <TD>Hold-Job</TD>
1765         <TD>Holds a job for printing</TD>
1766 </TR>
1767 <TR>
1768         <TD>Pause-Printer</TD>
1769         <TD>Sets the printer-state value for a printer to stopped</TD>
1770 </TR>
1771 <TR>
1772         <TD>Print-Job</TD>
1773         <TD>Creates a job with a single file for printing</TD>
1774 </TR>
1775 <TR>
1776         <TD>Purge-Jobs</TD>
1777         <TD>Removes all jobs from a printer</TD>
1778 </TR>
1779 <TR>
1780         <TD>Release-Job</TD>
1781         <TD>Releases a previously held job for printing</TD>
1782 </TR>
1783 <TR>
1784         <TD>Renew-Subscription</TD>
1785         <TD>Renews a notification subscription</TD>
1786 </TR>
1787 <TR>
1788         <TD>Restart-Job</TD>
1789         <TD>Reprints a job</TD>
1790 </TR>
1791 <TR>
1792         <TD>Resume-Printer</TD>
1793         <TD>Sets the printer-stae value for a printer to idle/processing</TD>
1794 </TR>
1795 <TR>
1796         <TD>Send-Document</TD>
1797         <TD>Adds a file to an job created with Create-Job</TD>
1798 </TR>
1799 <TR>
1800         <TD>Set-Job-Attributes</TD>
1801         <TD>Changes job options</TD>
1802 </TR>
1803 <TR>
1804         <TD>Validate-Job</TD>
1805         <TD>Validates job options prior to printing</TD>
1806 </TR>
1807 </TBODY>
1808 </TABLE></DIV>
1809
1810
1811 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="LimitExcept">LimitExcept</A></H2>
1812
1813 <H3>Examples</H3>
1814
1815 <PRE CLASS="command">
1816 &lt;Location /path&gt;
1817   &lt;LimitExcept GET POST&gt;
1818   ...
1819   &lt;/LimitExcept&gt;
1820 &lt;/Location&gt;
1821 </PRE>
1822
1823 <H3>Description</H3>
1824
1825 <P>The <CODE>LimitExcept</CODE> directive groups access control
1826 directives for specific types of HTTP requests and must appear
1827 inside a <A HREF="#Location"><CODE>Location</CODE></A> section.
1828 Unlike the <A HREF="#Limit"><CODE>Limit</CODE></A> directive,
1829 <CODE>LimitExcept</CODE> restricts access for all requests
1830 <I>except</I> those listed on the <CODE>LimitExcept</CODE>
1831 line.</P>
1832
1833
1834 <H2 CLASS="title"><A NAME="LimitRequestBody">LimitRequestBody</A></H2>
1835
1836 <H3>Examples</H3>
1837
1838 <PRE CLASS="command">
1839 LimitRequestBody 10485760
1840 LimitRequestBody 10m
1841 LimitRequestBody 0
1842 </PRE>
1843
1844 <H3>Description</H3>
1845
1846 <P>The <CODE>LimitRequestBody</CODE> directive controls the
1847 maximum size of print files, IPP requests, and HTML form data in
1848 HTTP POST requests. The default limit is 0 which disables the
1849 limit check.</P>
1850
1851
1852 <H2 CLASS="title"><A NAME="Listen">Listen</A></H2>
1853
1854 <H3>Examples</H3>
1855
1856 <PRE CLASS="command">
1857 Listen 127.0.0.1:631
1858 Listen 192.0.2.1:631
1859 Listen [::1]:631
1860 Listen *:631
1861 </PRE>
1862
1863 <H3>Description</H3>
1864
1865 <P>The <CODE>Listen</CODE> directive specifies a network address
1866 and port to listen for connections. Multiple <CODE>Listen</CODE>
1867 directives can be provided to listen on multiple addresses.</P>
1868
1869 <P>The <CODE>Listen</CODE> directive is similar to the <A
1870 HREF="#Port"><CODE>Port</CODE></A> directive but allows you to
1871 restrict access to specific interfaces or networks.</P>
1872
1873
1874 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="ListenBackLog">ListenBackLog</A></H2>
1875
1876 <H3>Examples</H3>
1877
1878 <PRE CLASS="command">
1879 ListenBackLog 5
1880 ListenBackLog 10
1881 </PRE>
1882
1883 <H3>Description</H3>
1884
1885 <P>The <CODE>ListenBackLog</CODE> directive sets the maximum
1886 number of pending connections the scheduler will allow. This
1887 normally only affects very busy servers that have reached the <A
1888 HREF="#MaxClients"><CODE>MaxClients</CODE></A> limit, but can
1889 also be triggered by large numbers of simultaneous connections.
1890 When the limit is reached, the operating system will refuse
1891 additional connections until the scheduler can accept the pending
1892 ones. The default is the OS-defined default limit, typically
1893 either 5 for older operating systems or 128 for newer operating
1894 systems.</P>
1895
1896
1897 <H2 CLASS="title"><A NAME="Location">Location</A></H2>
1898
1899 <H3>Examples</H3>
1900
1901 <PRE CLASS="command">
1902 &lt;Location /&gt;
1903 ...
1904 &lt;/Location&gt;
1905
1906 &lt;Location /admin&gt;
1907 ...
1908 &lt;/Location&gt;
1909
1910 &lt;Location /admin/conf&gt;
1911 ...
1912 &lt;/Location&gt;
1913
1914 &lt;Location /admin/log&gt;
1915 ...
1916 &lt;/Location&gt;
1917
1918 &lt;Location /classes&gt;
1919 ...
1920 &lt;/Location&gt;
1921
1922 &lt;Location /classes/name&gt;
1923 ...
1924 &lt;/Location&gt;
1925
1926 &lt;Location /jobs&gt;
1927 ...
1928 &lt;/Location&gt;
1929
1930 &lt;Location /printers&gt;
1931 ...
1932 &lt;/Location&gt;
1933
1934 &lt;Location /printers/name&gt;
1935 ...
1936 &lt;/Location&gt;
1937
1938 </PRE>
1939
1940 <H3>Description</H3>
1941
1942 <P>The <CODE>Location</CODE> directive specifies access control
1943 and authentication options for the specified HTTP resource or
1944 path.  The  <A HREF="#Allow"><CODE>Allow</CODE></A>,  <A
1945 HREF="#AuthType"><CODE>AuthType</CODE></A>,  <A
1946 HREF="#Deny"><CODE>Deny</CODE></A>,  <A
1947 HREF="#Encryption"><CODE>Encryption</CODE></A>,  <A
1948 HREF="#Limit"><CODE>Limit</CODE></A>,  <A
1949 HREF="#LimitExcept"><CODE>LimitExcept</CODE></A>,  <A
1950 HREF="#Order"><CODE>Order</CODE></A>,  <A
1951 HREF="#Require"><CODE>Require</CODE></A>, and <A
1952 HREF="#Satisfy"><CODE>Satisfy</CODE></A> directives may all
1953 appear inside a location.</P>
1954
1955 <P>Note that more specific resources override the less specific
1956 ones. So the directives inside the <CODE>/printers/name</CODE>
1957 location will override ones from <CODE>/printers</CODE>.
1958 Directives inside <CODE>/printers</CODE> will override ones from
1959 <CODE>/</CODE>. None of the directives are inherited.</P>
1960
1961 <DIV CLASS="table"><TABLE SUMMARY="Common Locations on the Server">
1962 <CAPTION>Table 3: <A NAME="TABLE3">Common Locations on the Server</A></CAPTION>
1963 <THEAD>
1964 <TR><TH>Location</TH><TH>Description</TH></TR>
1965 </THEAD>
1966 <TBODY>
1967 <TR><TD><CODE>/</CODE></TD><TD>The path for all get operations (get-printers, get-jobs, etc.)</TD></TR>
1968 <TR><TD><CODE>/admin</CODE></TD><TD>The path for all administration operations (add-printer, delete-printer, start-printer, etc.)</TD></TR>
1969 <TR><TD><CODE>/admin/conf</CODE></TD><TD>The path for access to the CUPS configuration files (cupsd.conf, client.conf, etc.)</TD></TR>
1970 <TR><TD><CODE>/admin/log</CODE></TD><TD>The path for access to the CUPS log files (access_log, error_log, page_log)</TD></TR>
1971 <TR><TD><CODE>/classes</CODE></TD><TD>The path for all classes</TD></TR>
1972 <TR><TD><CODE>/classes/name</CODE></TD><TD>The resource for class <CODE>name</CODE></TD></TR>
1973 <TR><TD><CODE>/jobs</CODE></TD><TD>The path for all jobs (hold-job, release-job, etc.)</TD></TR>
1974 <TR><TD><CODE>/jobs/id</CODE></TD><TD>The resource for job <CODE>id</CODE></TD></TR>
1975 <TR><TD><CODE>/printers</CODE></TD><TD>The path for all printers</TD></TR>
1976 <TR><TD><CODE>/printers/name</CODE></TD><TD>The path for printer <CODE>name</CODE></TD></TR>
1977 <TR><TD><CODE>/printers/name.ppd</CODE></TD><TD>The PPD file path for printer <CODE>name</CODE></TD></TR>
1978 </TBODY>
1979 </TABLE></DIV>
1980
1981
1982 <H2 CLASS="title"><A NAME="LogDebugHistory">LogDebugHistory</A></H2>
1983
1984 <H3>Examples</H3>
1985
1986 <PRE CLASS="command">
1987 LogDebugHistory 0
1988 LogDebugHistory 200
1989 </PRE>
1990
1991 <H3>Description</H3>
1992
1993 <P>When <A HREF="#LogLevel"><CODE>LogLevel</CODE></A> is not set to
1994 <CODE>debug</CODE> or <CODE>debug2</CODE>, the <CODE>LogDebugHistory</CODE>
1995 directive specifies the number of debugging messages that are logged when an
1996 error occurs during printing. The default is 200 messages. A value of 0
1997 disables debugging history entirely and is not recommended.</P>
1998
1999
2000 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.15</SPAN><A NAME="LogFilePerm">LogFilePerm</A></H2>
2001
2002 <H3>Examples</H3>
2003
2004 <PRE CLASS="command">
2005 LogFilePerm 0644
2006 LogFilePerm 0600
2007 </PRE>
2008
2009 <H3>Description</H3>
2010
2011 <P>The <CODE>LogFilePerm</CODE> directive specifies the
2012 permissions to use when writing configuration files. The default
2013 is @CUPS_LOG_FILE_PERM@.</P>
2014
2015
2016 <H2 CLASS="title"><A NAME="LogLevel">LogLevel</A></H2>
2017
2018 <H3>Examples</H3>
2019
2020 <PRE CLASS="command">
2021 LogLevel none
2022 LogLevel emerg
2023 LogLevel alert
2024 LogLevel crit
2025 LogLevel error
2026 LogLevel warn
2027 LogLevel notice
2028 LogLevel info
2029 LogLevel debug
2030 LogLevel debug2
2031 </PRE>
2032
2033 <H3>Description</H3>
2034
2035 <P>The <CODE>LogLevel</CODE> directive specifies the level of
2036 logging for the <A HREF="#ErrorLog"><CODE>ErrorLog</CODE></A>
2037 file. The following values are recognized (each level logs
2038 everything under the preceding levels):</P>
2039
2040 <UL>
2041
2042         <LI><CODE>none</CODE> - Log nothing</LI>
2043
2044         <LI><CODE>emerg</CODE> - Log emergency conditions that
2045         prevent the server from running</LI>
2046
2047         <LI><CODE>alert</CODE> - Log alerts that must be handled
2048         immediately</LI>
2049
2050         <LI><CODE>crit</CODE> - Log critical errors that don't
2051         prevent the server from running</LI>
2052
2053         <LI><CODE>error</CODE> - Log general errors</LI>
2054
2055         <LI><CODE>warn</CODE> - Log errors and warnings</LI>
2056
2057         <LI><CODE>notice</CODE> - Log temporary error conditions</LI>
2058
2059         <LI><CODE>info</CODE> - Log all requests and state
2060         changes</LI>
2061
2062         <LI><CODE>debug</CODE> - Log basic debugging
2063         information</LI>
2064
2065         <LI><CODE>debug2</CODE> - Log all debugging
2066         information</LI>
2067
2068 </UL>
2069
2070 <p>The default <code>LogLevel</code> is <code>@CUPS_LOG_LEVEL@</code>.</p>
2071
2072
2073 <H2 CLASS="title"><A NAME="LogTimeFormat">LogTimeFormat</A></H2>
2074
2075 <H3>Examples</H3>
2076
2077 <PRE CLASS="command">
2078 LogTimeFormat standard
2079 LogTimeFormat usecs
2080 </PRE>
2081
2082 <H3>Description</H3>
2083
2084 <P>The <CODE>LogTimeFormat</CODE> directive specifies the format used for the
2085 date and time in the log files. <CODE>Standard</CODE> uses the standard Apache
2086 Common Log Format date and time while <CODE>usecs</CODE> adds microseconds.
2087 The default is <CODE>standard</CODE>.</P>
2088
2089
2090 <H2 CLASS="title"><A NAME="MaxClients">MaxClients</A></H2>
2091
2092 <H3>Examples</H3>
2093
2094 <PRE CLASS="command">
2095 MaxClients 100
2096 MaxClients 1024
2097 </PRE>
2098
2099 <H3>Description</H3>
2100
2101 <P>The <CODE>MaxClients</CODE> directive controls the maximum
2102 number of simultaneous clients that will be allowed by the
2103 server. The default is 100 clients.</P>
2104
2105 <BLOCKQUOTE><B>Note:</B>
2106
2107 <P>Since each print job requires a file descriptor for the status
2108 pipe, the scheduler internally limits the <CODE>MaxClients</CODE>
2109 value to 1/3 of the available file descriptors to avoid possible
2110 problems when printing large numbers of jobs.</P>
2111
2112 </BLOCKQUOTE>
2113
2114
2115 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.18</SPAN><A NAME="MaxClientsPerHost">MaxClientsPerHost</A></H2>
2116
2117 <H3>Examples</H3>
2118
2119 <PRE CLASS="command">
2120 MaxClientsPerHost 10
2121 </PRE>
2122
2123 <H3>Description</H3>
2124
2125 <P>The <CODE>MaxClientsPerHost</CODE> directive controls the
2126 maximum number of simultaneous clients that will be allowed from
2127 a single host by the server. The default is the
2128 <CODE>MaxClients</CODE> value.</P>
2129
2130 <P>This directive provides a small measure of protection against
2131 Denial of Service attacks from a single host.</P>
2132
2133
2134 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.16</SPAN><A NAME="MaxCopies">MaxCopies</A></H2>
2135
2136 <H3>Examples</H3>
2137
2138 <PRE CLASS="command">
2139 MaxCopies 100
2140 MaxCopies 65535
2141 </PRE>
2142
2143 <H3>Description</H3>
2144
2145 <P>The <CODE>MaxCopies</CODE> directive controls the maximum
2146 number of copies that a user can print of a job. The default is
2147 @CUPS_MAX_COPIES@ copies.</P>
2148
2149 <BLOCKQUOTE><B>Note:</B>
2150
2151 <P>Most HP PCL laser printers internally limit the number of
2152 copies to 100.</P>
2153
2154 </BLOCKQUOTE>
2155
2156
2157
2158 <H2 CLASS="title"><A NAME="MaxJobs">MaxJobs</A></H2>
2159
2160 <H3>Examples</H3>
2161
2162 <PRE CLASS="command">
2163 MaxJobs 100
2164 MaxJobs 9999
2165 MaxJobs 0
2166 </PRE>
2167
2168 <H3>Description</H3>
2169
2170 <P>The <CODE>MaxJobs</CODE> directive controls the maximum number
2171 of jobs that are kept in memory. Once the number of jobs reaches
2172 the limit, the oldest completed job is automatically purged from
2173 the system to make room for the new one. If all of the known jobs
2174 are still pending or active then the new job will be
2175 rejected.</P>
2176
2177 <P>Setting the maximum size to 0 disables this functionality. The
2178 default setting is 500.</P>
2179
2180
2181 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="MaxJobsPerPrinter">MaxJobsPerPrinter</A></H2>
2182
2183 <H3>Examples</H3>
2184
2185 <PRE CLASS="command">
2186 MaxJobsPerPrinter 100
2187 MaxJobsPerPrinter 9999
2188 MaxJobsPerPrinter 0
2189 </PRE>
2190
2191 <H3>Description</H3>
2192
2193 <P>The <CODE>MaxJobsPerPrinter</CODE> directive controls the
2194 maximum number of active jobs that are allowed for each printer
2195 or class. Once a printer or class reaches the limit, new jobs
2196 will be rejected until one of the active jobs is completed,
2197 stopped, aborted, or canceled.</P>
2198
2199 <P>Setting the maximum to 0 disables this functionality. The
2200 default setting is 0.</P>
2201
2202
2203 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="MaxJobsPerUser">MaxJobsPerUser</A></H2>
2204
2205 <H3>Examples</H3>
2206
2207 <PRE CLASS="command">
2208 MaxJobsPerUser 100
2209 MaxJobsPerUser 9999
2210 MaxJobsPerUser 0
2211 </PRE>
2212
2213 <H3>Description</H3>
2214
2215 <P>The <CODE>MaxJobsPerUser</CODE> directive controls the maximum
2216 number of active jobs that are allowed for each user. Once a user
2217 reaches the limit, new jobs will be rejected until one of the
2218 active jobs is completed, stopped, aborted, or canceled.</P>
2219
2220 <P>Setting the maximum to 0 disables this functionality. The
2221 default setting is 0.</P>
2222
2223
2224 <H2 CLASS="title"><A NAME="MaxLogSize">MaxLogSize</A></H2>
2225
2226 <H3>Examples</H3>
2227
2228 <PRE CLASS="command">
2229 MaxLogSize 1048576
2230 MaxLogSize 1m
2231 MaxLogSize 0
2232 </PRE>
2233
2234 <H3>Description</H3>
2235
2236 <P>The <CODE>MaxLogSize</CODE> directive controls the maximum
2237 size of each log file. Once a log file reaches or exceeds the
2238 maximum size it is closed and renamed to <VAR>filename.O</VAR>.
2239 This allows you to rotate the logs automatically. The default
2240 size is 1048576 bytes (1MB).</P>
2241
2242 <P>Setting the maximum size to 0 disables log rotation.</P>
2243
2244
2245 <H2 CLASS="title"><SPAN CLASS="info">Deprecated</SPAN><A NAME="MaxRequestSize">MaxRequestSize</A></H2>
2246
2247 <H3>Examples</H3>
2248
2249 <PRE CLASS="command">
2250 MaxRequestSize 10485760
2251 MaxRequestSize 10m
2252 MaxRequestSize 0
2253 </PRE>
2254
2255 <H3>Description</H3>
2256
2257 <P>The <CODE>MaxRequestSize</CODE> directive controls the maximum
2258 size of print files, IPP requests, and HTML form data in HTTP
2259 POST requests. The default limit is 0 which disables the limit
2260 check.</P>
2261
2262 <P><B>This directive is deprecated and will be removed in a
2263 future CUPS release.</B> Use the <A
2264 HREF="#LimitRequestBody"><CODE>LimitRequestBody</CODE></A>
2265 directive instead.</P>
2266
2267
2268 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/Mac OS X 10.6</SPAN><A NAME="MultipleOperationTimeout">MultipleOperationTimeout</A></H2>
2269
2270 <H3>Examples</H3>
2271
2272 <PRE CLASS="command">
2273 MultipleOperationTimeout 60
2274 MultipleOperationTimeout 300
2275 MultipleOperationTimeout 86400
2276 </PRE>
2277
2278 <H3>Description</H3>
2279
2280 <P>The <CODE>MultipleOperationTimeout</CODE> directive sets the maximum amount
2281 of time between files in a multi-file print job. The default is 300 seconds.</P>
2282
2283
2284 <H2 CLASS="title"><A NAME="Order">Order</A></H2>
2285
2286 <H3>Examples</H3>
2287
2288 <PRE CLASS="command">
2289 &lt;Location /path&gt;
2290   ...
2291   Order Allow,Deny
2292   Order Deny,Allow
2293 &lt;/Location&gt;
2294 </PRE>
2295
2296 <H3>Description</H3>
2297
2298 <P>The <CODE>Order</CODE> directive defines the default access
2299 control. The following values are supported:</P>
2300
2301 <UL>
2302
2303         <LI><CODE>allow,deny</CODE> - Deny requests by default,
2304         then check the <A HREF="#Allow"><CODE>Allow</CODE></A>
2305         lines followed by the <A
2306         HREF="#Deny"><CODE>Deny</CODE></A> lines</LI>
2307
2308         <LI><CODE>deny,allow</CODE> - Allow requests by default,
2309         then check the <A HREF="#Deny"><CODE>Deny</CODE></A>
2310         lines followed by the <A
2311         HREF="#Allow"><CODE>Allow</CODE></A> lines</LI>
2312
2313 </UL>
2314
2315 <P>The <CODE>Order</CODE> directive must appear inside a <A
2316 HREF="#Location"><CODE>Location</CODE></A> or <A
2317 HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
2318
2319
2320 <H2 CLASS="title"><A NAME="PageLog">PageLog</A></H2>
2321
2322 <H3>Examples</H3>
2323
2324 <PRE CLASS="command">
2325 PageLog /var/log/cups/page_log
2326 PageLog /var/log/cups/page_log-%s
2327 PageLog syslog
2328 </PRE>
2329
2330 <H3>Description</H3>
2331
2332 <P>The <CODE>PageLog</CODE> directive sets the name of the page
2333 log file. If the filename is not absolute then it is assumed to
2334 be relative to the <A
2335 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
2336 default page log file is <VAR>@CUPS_LOGDIR@/page_log</VAR>.</P>
2337
2338 <P>The server name can be included in the filename by using
2339 <CODE>%s</CODE> in the name.</P>
2340
2341 <P>The special name "syslog" can be used to send the page
2342 information to the system log instead of a plain file.</P>
2343
2344
2345 <H2 CLASS="title"><A NAME="PageLogFormat">PageLogFormat</A></H2>
2346
2347 <H3>Examples</H3>
2348
2349 <PRE CLASS="command">
2350 PageLogFormat %p %j %u %T %P %C %{job-billing} %{job-originating-host-name} %{job-name} %{media} %{sides}
2351 PageLogFormat PAGE %p %j %u %P %C %{job-billing} %{job-originating-host-name}
2352 </PRE>
2353
2354 <H3>Description</H3>
2355
2356 <P>The <CODE>PageLogFormat</CODE> directive sets the format of lines
2357 that are logged to the page log file. Sequences beginning with percent (%)
2358 characters are replaced with the corresponding information, while all other
2359 characters are copied literally. The following percent sequences are
2360 recognized:</P>
2361
2362 <UL>
2363
2364         <LI><CODE>%%</CODE>: Inserts a single percent character.</LI>
2365
2366         <LI><CODE>%{name}</CODE>: Inserts the value of the specified IPP
2367         attribute.</LI>
2368
2369         <LI><CODE>%C</CODE>: Inserts the number of copies for the current page.</LI>
2370
2371         <LI><CODE>%P</CODE>: Inserts the current page number.</LI>
2372
2373         <LI><CODE>%T</CODE>: Inserts the current date and time in common log
2374         format.</LI>
2375
2376         <LI><CODE>%j</CODE>: Inserts the job ID.</LI>
2377
2378         <LI><CODE>%p</CODE>: Inserts the printer name.</LI>
2379
2380         <LI><CODE>%u</CODE>: Inserts the username.</LI>
2381
2382 </UL>
2383
2384 <P>The default is "%p %j %u %T %P %C %{job-billing} %{job-originating-host-name} %{job-name} %{media} %{sides}".</P>
2385
2386
2387 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="PassEnv">PassEnv</A></H2>
2388
2389 <H3>Examples</H3>
2390
2391 <PRE CLASS="command">
2392 PassEnv MY_ENV_VARIABLE
2393 </PRE>
2394
2395 <H3>Description</H3>
2396
2397 <P>The <CODE>PassEnv</CODE> directive specifies an environment
2398 variable that should be passed to child processes. Normally, the
2399 scheduler only passes the <CODE>DYLD_LIBRARY_PATH</CODE>,
2400 <CODE>LD_ASSUME_KERNEL</CODE>, <CODE>LD_LIBRARY_PATH</CODE>,
2401 <CODE>LD_PRELOAD</CODE>, <CODE>NLSPATH</CODE>,
2402 <CODE>SHLIB_PATH</CODE>, <CODE>TZ</CODE>, and <CODE>VGARGS</CODE>
2403 environment variables to child processes.</P>
2404
2405
2406 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="Policy">Policy</A></H2>
2407
2408 <H3>Examples</H3>
2409
2410 <PRE CLASS="command">
2411 &lt;Policy name&gt;
2412   &lt;Limit operation ... operation&gt;
2413   ...
2414   &lt;/Limit&gt;
2415   &lt;Limit operation ... operation&gt;
2416   ...
2417   &lt;/Limit&gt;
2418   &lt;Limit All&gt;
2419   ...
2420   &lt;/Limit&gt;
2421 &lt;/Policy&gt;
2422 </PRE>
2423
2424 <H3>Description</H3>
2425
2426 <P>The <CODE>Policy</CODE> directive specifies IPP operation
2427 access control limits. Each policy contains 1 or more <A
2428 HREF="#LimitIPP"><CODE>Limit</CODE></A> sections to set the
2429 access control limits for specific operations - user limits,
2430 authentication, encryption, and allowed/denied addresses,
2431 domains, or hosts. The <CODE>&lt;Limit All&gt;</CODE> section
2432 specifies the default access control limits for operations that
2433 are not listed.</P>
2434
2435 <P>Policies are named and associated with printers via the
2436 printer's operation policy setting
2437 (<CODE>printer-op-policy</CODE>). The default policy for the
2438 scheduler is specified using the <A
2439 HREF="#DefaultPolicy"><CODE>DefaultPolicy</CODE></A>
2440 directive.</P>
2441
2442
2443 <H2 CLASS="title"><A NAME="Port">Port</A></H2>
2444
2445 <H3>Examples</H3>
2446
2447 <PRE CLASS="command">
2448 Port 631
2449 Port 80
2450 </PRE>
2451
2452 <H3>Description</H3>
2453
2454 <P>The <CODE>Port</CODE> directive specifies a port to listen on.
2455 Multiple <CODE>Port</CODE> lines can be specified to listen on
2456 multiple ports. The <CODE>Port</CODE> directive is equivalent to
2457 "<CODE>Listen *:nnn</CODE>". The default port is 631.</P>
2458
2459 <BLOCKQUOTE><B>Note:</B>
2460
2461 <P>On systems that support IPv6, this directive will bind to both
2462 the IPv4 and IPv6 wildcard address.</P>
2463
2464 </BLOCKQUOTE>
2465
2466
2467 <H2 CLASS="title"><A NAME="PreserveJobHistory">PreserveJobHistory</A></H2>
2468
2469 <H3>Examples</H3>
2470
2471 <PRE CLASS="command">
2472 PreserveJobHistory On
2473 PreserveJobHistory Off
2474 </PRE>
2475
2476 <H3>Description</H3>
2477
2478 <P>The <CODE>PreserveJobHistory</CODE> directive controls whether
2479 the history of completed, canceled, or aborted print jobs is
2480 stored on disk.</P>
2481
2482 <P>A value of <CODE>On</CODE> (the default) preserves job
2483 information until the administrator purges it with the
2484 <CODE>cancel</CODE> command.</P>
2485
2486 <P>A value of <CODE>Off</CODE> removes the job information as
2487 soon as each job is completed, canceled, or aborted.</P>
2488
2489
2490 <H2 CLASS="title"><A NAME="PreserveJobFiles">PreserveJobFiles</A></H2>
2491
2492 <H3>Examples</H3>
2493
2494 <PRE CLASS="command">
2495 PreserveJobFiles On
2496 PreserveJobFiles Off
2497 </PRE>
2498
2499 <H3>Description</H3>
2500
2501 <P>The <CODE>PreserveJobFiles</CODE> directive controls whether
2502 the document files of completed, canceled, or aborted print jobs
2503 are stored on disk.</P>
2504
2505 <P>A value of <CODE>On</CODE> preserves job files until the
2506 administrator purges them with the <CODE>cancel</CODE> command.
2507 Jobs can be restarted (and reprinted) as desired until they are
2508 purged.</P>
2509
2510 <P>A value of <CODE>Off</CODE> (the default) removes the job
2511 files as soon as each job is completed, canceled, or aborted.</P>
2512
2513
2514 <H2 CLASS="title"><A NAME="Printcap">Printcap</A></H2>
2515
2516 <H3>Examples</H3>
2517
2518 <PRE CLASS="command">
2519 Printcap
2520 Printcap /etc/printcap
2521 Printcap /etc/printers.conf
2522 Printcap /Library/Preferences/org.cups.printers.plist
2523 </PRE>
2524
2525 <H3>Description</H3>
2526
2527 <P>The <CODE>Printcap</CODE> directive controls whether or not a
2528 printcap file is automatically generated and updated with a list
2529 of available printers. If specified with no value, then no
2530 printcap file will be generated. The default is to generate a
2531 file named <VAR>@CUPS_DEFAUL_PRINTCAP@</VAR>.</P>
2532
2533 <P>When a filename is specified (e.g. <VAR>@CUPS_DEFAULT_PRINTCAP@</VAR>),
2534 the printcap file is written whenever a printer is added or
2535 removed. The printcap file can then be used by applications that
2536 are hardcoded to look at the printcap file for the available
2537 printers.</P>
2538
2539
2540 <H2 CLASS="title"><A NAME="PrintcapFormat">PrintcapFormat</A></H2>
2541
2542 <H3>Examples</H3>
2543
2544 <PRE CLASS="command">
2545 PrintcapFormat BSD
2546 PrintcapFormat Solaris
2547 PrintcapFormat plist
2548 </PRE>
2549
2550 <H3>Description</H3>
2551
2552 <P>The <CODE>PrintcapFormat</CODE> directive controls the output format of the
2553 printcap file. The default is to generate the plist format on Mac OS X, the
2554 Solaris format on Solaris, and the BSD format on other operating systems.</P>
2555
2556
2557 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.13</SPAN><A NAME="PrintcapGUI">PrintcapGUI</A></H2>
2558
2559 <H3>Examples</H3>
2560
2561 <PRE CLASS="command">
2562 PrintGUI /usr/bin/glpoptions
2563 </PRE>
2564
2565 <H3>Description</H3>
2566
2567 <P>The <CODE>PrintcapGUI</CODE> directive sets the program to
2568 associate with the IRIX printer GUI interface script which is
2569 used by IRIX applications to display printer-specific options.
2570 There is no default program.</P>
2571
2572
2573 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.21</SPAN><A NAME="ReloadTimeout">ReloadTimeout</A></H2>
2574
2575 <H3>Examples</H3>
2576
2577 <PRE CLASS="command">
2578 ReloadTimeout 0
2579 ReloadTimeout 30
2580 </PRE>
2581
2582 <H3>Description</H3>
2583
2584 <P>The <CODE>ReloadTimeout</CODE> directive specifies the number
2585 of seconds the scheduler will wait for active jobs to complete
2586 before doing a restart. The default is 30 seconds.</P>
2587
2588
2589 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.3</SPAN><A NAME="RemoteRoot">RemoteRoot</A></H2>
2590
2591 <H3>Examples</H3>
2592
2593 <PRE CLASS="command">
2594 RemoteRoot remroot
2595 RemoteRoot root
2596 </PRE>
2597
2598 <H3>Description</H3>
2599
2600 <P>The <CODE>RemoteRoot</CODE> directive sets the username for
2601 unauthenticated root requests from remote hosts. The default
2602 username is <VAR>remroot</VAR>. Setting <CODE>RemoteRoot</CODE>
2603 to <VAR>root</VAR> effectively disables this security
2604 mechanism.</P>
2605
2606
2607 <H2 CLASS="title"><A NAME="RequestRoot">RequestRoot</A></H2>
2608
2609 <H3>Examples</H3>
2610
2611 <PRE CLASS="command">
2612 RequestRoot /var/spool/cups
2613 RequestRoot /foo/bar/spool/cups
2614 </PRE>
2615
2616 <H3>Description</H3>
2617
2618 <P>The <CODE>RequestRoot</CODE> directive sets the directory for
2619 incoming IPP requests and HTML forms. If an absolute path is not
2620 provided then it is assumed to be relative to the <A
2621 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
2622 default request directory is <VAR>@CUPS_REQUESTS@</VAR>.</P>
2623
2624
2625 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="Require">Require</A></H2>
2626
2627 <H3>Examples</H3>
2628
2629 <PRE CLASS="command">
2630 &lt;Location /path&gt;
2631   ...
2632   Require group foo bar
2633   Require user john mary
2634   Require valid-user
2635   Require user @groupname
2636   Require user @SYSTEM
2637   Require user @OWNER
2638 &lt;/Location&gt;
2639 </PRE>
2640
2641 <H3>Description</H3>
2642
2643 <P>The <CODE>Require</CODE> directive specifies that
2644 authentication is required for the resource. The
2645 <CODE>group</CODE> keyword specifies that the authenticated user
2646 must be a member of one or more of the named groups that
2647 follow.</P>
2648
2649 <P>The <CODE>user</CODE> keyword specifies that the
2650 authenticated user must be one of the named users or groups that
2651 follow. Group names are specified using the "@" prefix.</P>
2652
2653 <P>The <CODE>valid-user</CODE> keyword specifies that any
2654 authenticated user may access the resource.</P>
2655
2656 <P>The default is to do no authentication. This directive must
2657 appear inside a <A HREF="#Location"><CODE>Location</CODE></A> or
2658 <A HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
2659
2660
2661 <H2 CLASS="title"><A NAME="RIPCache">RIPCache</A></H2>
2662
2663 <H3>Examples</H3>
2664
2665 <PRE CLASS="command">
2666 RIPCache 8m
2667 RIPCache 1g
2668 RIPCache 2048k
2669 </PRE>
2670
2671 <H3>Description</H3>
2672
2673 <P>The <CODE>RIPCache</CODE> directive sets the size of the
2674 memory cache used by Raster Image Processor ("RIP") filters such
2675 as <CODE>imagetoraster</CODE> and <CODE>pstoraster</CODE>. The
2676 size can be suffixed with a "k" for kilobytes, "m" for megabytes,
2677 or "g" for gigabytes. The default cache size is "8m", or 8
2678 megabytes.</P>
2679
2680
2681 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.16</SPAN><A NAME="RootCertDuration">RootCertDuration</A></H2>
2682
2683 <H3>Examples</H3>
2684
2685 <PRE CLASS="command">
2686 RootCertDuration 0
2687 RootCertDuration 300
2688 </PRE>
2689
2690 <H3>Description</H3>
2691
2692 <P>The <CODE>RootCertDuration</CODE> directive specifies the
2693 number of seconds the <EM>root certificate</EM> remains valid.
2694 The scheduler will generate a new certificate as needed when the
2695 number of seconds has expired. If set to 0, the root certificate
2696 is generated only once on startup or on a restart. The default is
2697 300 seconds.</P>
2698
2699
2700 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="Satisfy">Satisfy</A></H2>
2701
2702 <H3>Examples</H3>
2703
2704 <PRE CLASS="command">
2705 &lt;Location /path&gt;
2706   ...
2707   Satisfy all
2708   Satisfy any
2709 &lt;/Location&gt;
2710 </PRE>
2711
2712 <H3>Description</H3>
2713
2714 <P>The <CODE>Satisfy</CODE> directive specifies whether all
2715 conditions must be satisfied to allow access to the resource. If
2716 set to <CODE>all</CODE>, then all authentication and access
2717 control conditions must be satified to allow access.</P>
2718
2719 <P>Setting <CODE>Satisfy</CODE> to <CODE>any</CODE> allows a user
2720 to gain access if the authentication or access control
2721 requirements are satisfied. For example, you might require
2722 authentication for remote access, but allow local access without
2723 authentication.</P>
2724
2725 <P>The default is <CODE>all</CODE>. This directive must appear
2726 inside a <A HREF="#Location"><CODE>Location</CODE></A> or <A
2727 HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
2728
2729
2730 <H2 CLASS="title"><A NAME="ServerAdmin">ServerAdmin</A></H2>
2731
2732 <H3>Examples</H3>
2733
2734 <PRE CLASS="command">
2735 ServerAdmin user@host
2736 ServerAdmin root@foo.bar.com
2737 </PRE>
2738
2739 <H3>Description</H3>
2740
2741 <P>The <CODE>ServerAdmin</CODE> directive identifies the email
2742 address for the administrator on the system. By default the
2743 administrator email address is <CODE>root@server</CODE>, where
2744 <CODE>server</CODE> is the <A
2745 HREF="#ServerName"><CODE>ServerName</CODE></A>.</P>
2746
2747
2748 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.3.10</SPAN><A NAME="ServerAlias">ServerAlias</A></H2>
2749
2750 <H3>Examples</H3>
2751
2752 <PRE CLASS="command">
2753 ServerAlias althost
2754 ServerAlias althost.foo.com
2755 ServerAlias althost.bar.com
2756 ServerAlias *
2757 </PRE>
2758
2759 <H3>Description</H3>
2760
2761 <P>The <CODE>ServerAlias</CODE> directive specifies alternate names that the
2762 server is known by. By default it contains a list of all aliases associated
2763 with the <A HREF="#ServerName"><CODE>ServerName</CODE></A>. The special name
2764 "*" can be used to allow any hostname when accessing CUPS via an external
2765 network interfaces.</P>
2766
2767 <BLOCKQUOTE><B>Note</B>
2768
2769 <P>The <CODE>ServerAlias</CODE> directive is used for HTTP Host header
2770 validation when clients connect to the scheduler from external interfaces.
2771 Using the special name "*" can expose your system to known browser-based
2772 DNS rebinding attacks, even when accessing sites through a firewall. If the
2773 auto-discovery of alternate names does not work, we recommend listing each
2774 alternate name with a ServerAlias directive instead of using "*".</P>
2775
2776 </BLOCKQUOTE>
2777
2778
2779 <H2 CLASS="title"><A NAME="ServerBin">ServerBin</A></H2>
2780
2781 <H3>Examples</H3>
2782
2783 <PRE CLASS="command">
2784 ServerBin /usr/lib/cups
2785 ServerBin /foo/bar/lib/cups
2786 </PRE>
2787
2788 <H3>Description</H3>
2789
2790 <P>The <CODE>ServerBin</CODE> directive sets the directory for
2791 server-run executables. If an absolute path is not provided then
2792 it is assumed to be relative to the <A
2793 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
2794 default executable directory is <VAR>/usr/lib/cups</VAR>,
2795 <VAR>/usr/lib32/cups</VAR>, or <VAR>/usr/libexec/cups</VAR>
2796 depending on the operating system.</P>
2797
2798
2799 <H2 CLASS="title"><A NAME="ServerCertificate">ServerCertificate</A></H2>
2800
2801 <H3>Examples</H3>
2802
2803 <PRE CLASS="command">
2804 ServerCertificate /etc/cups/ssl/server.crt
2805 </PRE>
2806
2807 <H3>Description</H3>
2808
2809 <P>The <CODE>ServerCertificate</CODE> directive specifies the
2810 location of the SSL certificate file used by the server when
2811 negotiating encrypted connections. The certificate must not be
2812 encrypted (password protected) since the scheduler normally runs
2813 in the background and will be unable to ask for a password.</P>
2814
2815 <P>The default certificate file is
2816 <VAR>/etc/cups/ssl/server.crt</VAR>.</P>
2817
2818
2819 <H2 CLASS="title"><A NAME="ServerKey">ServerKey</A></H2>
2820
2821 <H3>Examples</H3>
2822
2823 <PRE CLASS="command">
2824 ServerKey /etc/cups/ssl/server.key
2825 </PRE>
2826
2827 <H3>Description</H3>
2828
2829 <P>The <CODE>ServerKey</CODE> directive specifies the location of
2830 the SSL private key file used by the server when negotiating
2831 encrypted connections.</P>
2832
2833 <P>The default key file is
2834 <VAR>/etc/cups/ssl/server.crt</VAR>.</P>
2835
2836
2837 <H2 CLASS="title"><A NAME="ServerName">ServerName</A></H2>
2838
2839 <H3>Examples</H3>
2840
2841 <PRE CLASS="command">
2842 ServerName foo.domain.com
2843 ServerName myserver.domain.com
2844 </PRE>
2845
2846 <H3>Description</H3>
2847
2848 <P>The <CODE>ServerName</CODE> directive specifies the hostname
2849 that is reported to clients. By default the server name is the
2850 hostname.</P>
2851
2852
2853 <H2 CLASS="title"><A NAME="ServerRoot">ServerRoot</A></H2>
2854
2855 <H3>Examples</H3>
2856
2857 <PRE CLASS="command">
2858 ServerRoot /etc/cups
2859 ServerRoot /foo/bar/cups
2860 </PRE>
2861
2862 <H3>Description</H3>
2863
2864 <P>The <CODE>ServerRoot</CODE> directive specifies the absolute
2865 path to the server configuration and state files. It is also used
2866 to resolve relative paths in the <VAR>cupsd.conf</VAR> file. The
2867 default server directory is <VAR>/etc/cups</VAR>.</P>
2868
2869
2870 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.21</SPAN><A NAME="ServerTokens">ServerTokens</A></H2>
2871
2872 <H3>Examples</H3>
2873
2874 <PRE CLASS="command">
2875 ServerTokens None
2876 ServerTokens ProductOnly
2877 ServerTokens Major
2878 ServerTokens Minor
2879 ServerTokens Minimal
2880 ServerTokens OS
2881 ServerTokens Full
2882 </PRE>
2883
2884 <H3>Description</H3>
2885
2886 <P>The <CODE>ServerTokens</CODE> directive specifies the
2887 information that is included in the <CODE>Server:</CODE> header
2888 of all HTTP responses. Table 4 lists the token name along with
2889 the text that is returned. The default is
2890 <CODE>Minimal</CODE>.</P>
2891
2892 <DIV CLASS="table"><TABLE SUMMARY="ServerToken Names and Values">
2893 <CAPTION>Table 4: <A NAME="TABLE4">ServerToken Names and Values</A></CAPTION>
2894 <THEAD>
2895 <TR>
2896         <TH>Name</TH>
2897         <TH>Value</TH>
2898 </TR>
2899 </THEAD>
2900 <TBODY>
2901 <TR>
2902         <TD>None</TD>
2903         <TD>No <CODE>Server:</CODE> header is returned</TD>
2904 </TR>
2905 <TR>
2906         <TD>ProductOnly</TD>
2907         <TD>"CUPS"</TD>
2908 </TR>
2909 <TR>
2910         <TD>Major</TD>
2911         <TD>"CUPS 1"</TD>
2912 </TR>
2913 <TR>
2914         <TD>Minor</TD>
2915         <TD>"CUPS 1.2"</TD>
2916 </TR>
2917 <TR>
2918         <TD>Minimal</TD>
2919         <TD>"CUPS 1.2.N" where N is the patch release</TD>
2920 </TR>
2921 <TR>
2922         <TD>OS</TD>
2923         <TD>"CUPS 1.2.N (UNAME)" where N is the patch release and
2924         UNAME is the output of the <B>uname(1)</B> command</TD>
2925 </TR>
2926 <TR>
2927         <TD>Full</TD>
2928         <TD>"CUPS 1.2.N (UNAME) IPP/1.1" where N is the patch
2929         release and UNAME is the output of the <B>uname(1)</B>
2930         command</TD>
2931 </TR>
2932 </TBODY>
2933 </TABLE></DIV>
2934
2935
2936 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="SetEnv">SetEnv</A></H2>
2937
2938 <H3>Examples</H3>
2939
2940 <PRE CLASS="command">
2941 SetEnv PATH /usr/lib/cups/filter:/bin:/usr/bin:/usr/local/bin
2942 SetEnv MY_ENV_VAR foo
2943 </PRE>
2944
2945 <H3>Description</H3>
2946
2947 <P>The <CODE>SetEnv</CODE> directive specifies an environment
2948 variable that should be passed to child processes.</P>
2949
2950
2951 <H2 CLASS="title"><A NAME="SSLOptions">SSLOptions</A></H2>
2952
2953 <H3>Examples</H3>
2954
2955 <PRE CLASS="command">
2956 SSLOptions 127.0.0.1:443
2957 SSLOptions 192.0.2.1:443
2958 </PRE>
2959
2960 <H3>Description</H3>
2961
2962 <P>The <CODE>SSLOptions</CODE> directive specifies a network
2963 address and port to listen for secure connections. Multiple
2964 <CODE>SSLOptions</CODE> directives can be provided to listen on
2965 multiple addresses.</P>
2966
2967 <P>The <CODE>SSLOptions</CODE> directive is similar to the <A
2968 HREF="#SSLPort"><CODE>SSLPort</CODE></A> directive but allows you
2969 to restrict access to specific interfaces or networks.</P>
2970
2971
2972 <H2 CLASS="title"><A NAME="SSLOptions">SSLOptions</A></H2>
2973
2974 <H3>Examples</H3>
2975
2976 <PRE CLASS="command">
2977 SSLOptions None
2978 SSLOptions NoEmptyFragments
2979 </PRE>
2980
2981 <H3>Description</H3>
2982
2983 <P>The <CODE>SSLOptions</CODE> directive specifies additional SSL/TLS
2984 protocol options to use for encrypted connected. Currently only two
2985 options are supported - <code>None</code> (the default) for the most
2986 secure mode and <code>NoEmptyFragments</code> to allow CUPS to work with
2987 Microsoft Windows with the FIPS conformance mode enabled.</p>
2988
2989
2990 <H2 CLASS="title"><A NAME="SSLPort">SSLPort</A></H2>
2991
2992 <H3>Examples</H3>
2993
2994 <PRE CLASS="command">
2995 SSLPort 443
2996 </PRE>
2997
2998 <H3>Description</H3>
2999
3000 <P>The <CODE>SSLPort</CODE> directive specifies a port to listen
3001 on for secure connections. Multiple <CODE>SSLPort</CODE> lines
3002 can be specified to listen on multiple ports.</P>
3003
3004
3005 <H2 CLASS="title"><A NAME="SystemGroup">SystemGroup</A></H2>
3006
3007 <H3>Examples</H3>
3008
3009 <PRE CLASS="command">
3010 SystemGroup lpadmin
3011 SystemGroup sys
3012 SystemGroup system
3013 SystemGroup root
3014 SystemGroup root lpadmin
3015 </PRE>
3016
3017 <H3>Description</H3>
3018
3019 <P>The <CODE>SystemGroup</CODE> directive specifies the system
3020 administration group for <CODE>System</CODE> authentication.
3021 Multiple groups can be listed, separated with spaces. The default
3022 group list is <CODE>@CUPS_SYSTEM_GROUPS@</CODE>.</P>
3023
3024
3025 <H2 CLASS="title"><A NAME="TempDir">TempDir</A></H2>
3026
3027 <H3>Examples</H3>
3028
3029 <PRE CLASS="command">
3030 TempDir /var/tmp
3031 TempDir /foo/bar/tmp
3032 </PRE>
3033
3034 <H3>Description</H3>
3035
3036 <P>The <CODE>TempDir</CODE> directive specifies an absolute path
3037 for the directory to use for temporary files. The default
3038 directory is <VAR>@CUPS_REQUESTS@/tmp</VAR>.</P>
3039
3040 <P>Temporary directories must be world-writable and should have
3041 the "sticky" permission bit enabled so that other users cannot
3042 delete filter temporary files. The following commands will create
3043 an appropriate temporary directory called
3044 <VAR>/foo/bar/tmp</VAR>:</P>
3045
3046 <PRE CLASS="command">
3047 <KBD>mkdir /foo/bar/tmp</KBD>
3048 <KBD>chmod a+rwxt /foo/bar/tmp</KBD>
3049 </PRE>
3050
3051
3052 <H2 CLASS="title"><A NAME="Timeout">Timeout</A></H2>
3053
3054 <H3>Examples</H3>
3055
3056 <PRE CLASS="command">
3057 Timeout 300
3058 Timeout 90
3059 </PRE>
3060
3061 <H3>Description</H3>
3062
3063 <P>The <CODE>Timeout</CODE> directive controls the amount of time
3064 to wait before an active HTTP or IPP request times out. The
3065 default timeout is 300 seconds.</P>
3066
3067
3068 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="UseNetworkDefault">UseNetworkDefault</A></H2>
3069
3070 <H3>Examples</H3>
3071
3072 <PRE CLASS="command">
3073 UseNetworkDefault yes
3074 UseNetworkDefault no
3075 </PRE>
3076
3077 <H3>Description</H3>
3078
3079 <P>The <CODE>UseNetworkDefault</CODE> directive controls whether
3080 the client will use a network/remote printer as a default
3081 printer. If enabled, the default printer of a server is used as
3082 the default printer on a client. When multiple servers are
3083 advertising a default printer, the client's default printer is
3084 set to the first discovered printer, or to the implicit class for
3085 the same printer available from multiple servers.</P>
3086
3087 <P>The default is <CODE>@CUPS_USE_NETWORK_DEFAULT@</CODE>.</P>
3088
3089
3090 <H2 CLASS="title"><A NAME="User">User</A></H2>
3091
3092 <H3>Examples</H3>
3093
3094 <PRE CLASS="command">
3095 User lp
3096 User guest
3097 </PRE>
3098
3099 <H3>Description</H3>
3100
3101 <P>The <CODE>User</CODE> directive specifies the UNIX user that
3102 filter and CGI programs run as. The default user is
3103 <CODE>@CUPS_USER@</CODE>.</P>
3104
3105 <BLOCKQUOTE><B>Note:</B>
3106
3107 <P>You may not use user <CODE>root</CODE>, as that would expose
3108 the system to unacceptable security risks. The scheduler will
3109 automatically choose user <CODE>nobody</CODE> if you specify a
3110 user whose ID is 0.</P>
3111
3112 </BLOCKQUOTE>
3113
3114
3115 </BODY>
3116 </HTML>