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

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