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