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

   1 <HTML>
   2 <!-- SECTION: References -->
   3 <HEAD>
   4         <TITLE>cupsd.conf</TITLE>
   5         <LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
   6 </HEAD>
   7 <BODY>
   8
   9 <H1 CLASS="title">cupsd.conf</H1>
  10
  11 <P>The <VAR>/etc/cups/cupsd.conf</VAR> file contains
  12 configuration <I>directives</I> that control how the server
  13 functions. Each directive is listed on a line by itself followed
  14 by its value. Comments are introduced using the number sign ("#")
  15 character at the beginning of a line.</P>
  16
  17 <P>Since the server configuration file consists of plain text,
  18 you can use your favorite text editor to make changes to it.
  19 After making any changes, restart the <CODE>cupsd(8)</CODE>
  20 process using the startup script for your operating system:</P>
  21
  22 <UL>
  23
  24         <LI>AIX, Linux, Solaris:
  25         <PRE CLASS="command">
  26 /etc/init.d/cups restart
  27         </PRE></LI>
  28
  29         <LI>HP-UX:
  30         <PRE CLASS="command">
  31 /sbin/init.d/cups restart
  32         </PRE></LI>
  33
  34         <LI>MacOS X:
  35         <PRE CLASS="command">
  36 sudo launchctl unload /System/Library/LaunchDaemons/org.cups.cupsd.plist
  37 sudo launchctl load /System/Library/LaunchDaemons/org.cups.cupsd.plist
  38         </PRE></LI>
  39
  40 </UL>
  41
  42 <P>You can also edit this file from the CUPS web interface, which
  43 automatically handles restarting the scheduler.</P>
  44
  45 <BLOCKQUOTE><B>Note:</B>
  46
  47 <P>The specification of time units ("w" for weeks, "h" for hours, etc.) in the various time interval directives is new in CUPS 1.6/OS X 10.8. Prior releases of CUPS only supported time intervals in seconds.</P>
  48
  49 </BLOCKQUOTE>
  50
  51
  52 <H2 CLASS="title"><A NAME="AccessLog">AccessLog</A></H2>
  53
  54 <H3>Examples</H3>
  55
  56 <PRE CLASS="command">
  57 AccessLog /var/log/cups/access_log
  58 AccessLog /var/log/cups/access_log-%s
  59 AccessLog syslog
  60 </PRE>
  61
  62 <H3>Description</H3>
  63
  64 <P>The <CODE>AccessLog</CODE> directive sets the name of the
  65 access log file. If the filename is not absolute then it is
  66 assumed to be relative to the <A
  67 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
  68 access log file is stored in "common log format" and can be used
  69 by any web access reporting tool to generate a report on CUPS
  70 server activity.</P>
  71
  72 <P>The server name can be included in the filename by using
  73 <CODE>%s</CODE> in the name.</P>
  74
  75 <P>The special name "syslog" can be used to send the access
  76 information to the system log instead of a plain file.</P>
  77
  78 <P>The default access log file is
  79 <VAR>@CUPS_LOGDIR@/access_log</VAR>.</P>
  80
  81
  82 <H2 CLASS="title"><A NAME="AccessLogLevel">AccessLogLevel</A></H2>
  83
  84 <H3>Examples</H3>
  85
  86 <PRE CLASS="command">
  87 AccessLogLevel config
  88 AccessLogLevel actions
  89 AccessLogLevel all
  90 </PRE>
  91
  92 <H3>Description</H3>
  93
  94 <P>The <CODE>AccessLogLevel</CODE> directive controls which requests are logged
  95 to the access log file. The following levels are defined:</P>
  96
  97 <UL>
  98
  99         <LI><CODE>config</CODE>; Log when printers and classes are added,
 100         deleted, or modified and when configuration files are accessed or
 101         updated.</LI>
 102
 103         <LI><CODE>actions</CODE>; Log when print jobs are submitted,
 104         held, released, modified, or canceled, and any of the conditions
 105         for <CODE>config</CODE>.</LI>
 106
 107         <LI><CODE>all</CODE>; Log all requests.</LI>
 108
 109 </UL>
 110
 111 <P>The default access log level is <CODE>@CUPS_ACCESS_LOG_LEVEL@</CODE>.</P>
 112
 113
 114 <H2 CLASS="title"><A NAME="Allow">Allow</A></H2>
 115
 116 <H3>Examples</H3>
 117
 118 <PRE CLASS="command">
 119 &lt;Location /path&gt;
 120   ...
 121   Allow from All
 122   Allow from None
 123   Allow from *.example.com
 124   Allow from .example.com
 125   Allow from host.example.com
 126   Allow from nnn.*
 127   Allow from nnn.nnn.*
 128   Allow from nnn.nnn.nnn.*
 129   Allow from nnn.nnn.nnn.nnn
 130   Allow from nnn.nnn.nnn.nnn/mm
 131   Allow from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
 132   Allow from [xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]
 133   Allow from [xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]/mmm
 134   Allow from @LOCAL
 135   Allow from @IF(name)
 136 &lt;/Location&gt;
 137 </PRE>
 138
 139 <H3>Description</H3>
 140
 141 <P>The <CODE>Allow</CODE> directive specifies a hostname, IP
 142 address, or network that is allowed access to the server.
 143 <CODE>Allow</CODE> directives are cumulative, so multiple
 144 <CODE>Allow</CODE> directives can be used to allow access for
 145 multiple hosts or networks.</P>
 146
 147 <P>Host and domain name matching require that you enable the <A
 148 HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A>
 149 directive.</P>
 150
 151 <P>The <CODE>/mm</CODE> notation specifies a CIDR netmask, as shown in
 152 <A HREF="#TABLE1">Table 1</A>.</P>
 153
 154 <DIV CLASS="table"><TABLE SUMMARY="CIDR Netmasks">
 155 <CAPTION>Table 1: <A NAME="TABLE1">CIDR Netmasks</A></CAPTION>
 156 <TR>
 157         <TH WIDTH="10%">mm</TH>
 158         <TH WIDTH="20%">netmask</TH>
 159         <TH WIDTH="10%">mm</TH>
 160         <TH WIDTH="20%">netmask</TH>
 161 </TR>
 162 <TR>
 163         <TD ALIGN="CENTER">0</TD>
 164         <TD ALIGN="CENTER">0.0.0.0</TD>
 165         <TD ALIGN="CENTER">8</TD>
 166         <TD ALIGN="CENTER">255.0.0.0</TD>
 167 </TR>
 168 <TR>
 169         <TD ALIGN="CENTER">1</TD>
 170         <TD ALIGN="CENTER">128.0.0.0</TD>
 171         <TD ALIGN="CENTER">16</TD>
 172         <TD ALIGN="CENTER">255.255.0.0</TD>
 173 </TR>
 174 <TR>
 175         <TD ALIGN="CENTER">2</TD>
 176         <TD ALIGN="CENTER">192.0.0.0</TD>
 177         <TD ALIGN="CENTER">24</TD>
 178         <TD ALIGN="CENTER">255.255.255.0</TD>
 179 </TR>
 180 <TR>
 181         <TD ALIGN="CENTER">...</TD>
 182         <TD ALIGN="CENTER">...</TD>
 183         <TD ALIGN="CENTER">32</TD>
 184         <TD ALIGN="CENTER">255.255.255.255</TD>
 185 </TR>
 186 </TABLE></DIV>
 187
 188 <P>The <CODE>@LOCAL</CODE> name will allow access from all local
 189 interfaces. The <CODE>@IF(name)</CODE> name will allow access
 190 from the named interface. In both cases, CUPS only allows access
 191 from the network that the interface(s) are configured for -
 192 requests  arriving on the interface from a foreign network will
 193 <em>not</em> be accepted.</P>
 194
 195 <P>The <CODE>Allow</CODE> directive must appear inside a <A
 196 HREF="#Location"><CODE>Location</CODE></A> or <A
 197 HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
 198
 199
 200 <H2 CLASS="title"><A NAME="AuthType">AuthType</A></H2>
 201
 202 <H3>Examples</H3>
 203
 204 <PRE CLASS="command">
 205 &lt;Location /path&gt;
 206   ...
 207   AuthType None
 208   AuthType Basic
 209   AuthType Digest
 210   AuthType BasicDigest
 211   AuthType Negotiate
 212 &lt;/Location&gt;
 213 </PRE>
 214
 215 <H3>Description</H3>
 216
 217 <P>The <CODE>AuthType</CODE> directive defines the type of
 218 authentication to perform:</P>
 219
 220 <UL>
 221
 222         <LI><CODE>None</CODE> - No authentication should be
 223         performed (default)</LI>
 224
 225         <LI><CODE>Basic</CODE> - Basic authentication should be
 226         performed using the UNIX password and group files</LI>
 227
 228         <LI><CODE>Digest</CODE> - Digest authentication should be
 229         performed using the <VAR>/etc/cups/passwd.md5</VAR>
 230         file</LI>
 231
 232         <LI><CODE>BasicDigest</CODE> - Basic authentication
 233         should be performed using the
 234         <VAR>/etc/cups/passwd.md5</VAR> file</LI>
 235
 236         <LI><CODE>Negotiate</CODE> - Kerberos authentication
 237         should be performed</LI>
 238
 239 </UL>
 240
 241 <P>When using <CODE>Basic</CODE>, <CODE>Digest</CODE>,
 242 <CODE>BasicDigest</CODE>, or <CODE>Negotiate</CODE> authentication,
 243 clients connecting through the <CODE>localhost</CODE> interface can
 244 also authenticate using certificates.</P>
 245
 246 <P>The <CODE>AuthType</CODE> directive must appear inside a <A
 247 HREF="#Location"><CODE>Location</CODE></A> or <A
 248 HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
 249
 250
 251 <H2 CLASS="title"><A NAME="AutoPurgeJobs">AutoPurgeJobs</A></H2>
 252
 253 <H3>Examples</H3>
 254
 255 <PRE CLASS="command">
 256 AutoPurgeJobs Yes
 257 AutoPurgeJobs No
 258 </PRE>
 259
 260 <H3>Description</H3>
 261
 262 <P>The <CODE>AutoPurgeJobs</CODE> directive specifies whether or
 263 not to purge completed jobs once they are no longer required for
 264 quotas. This option has no effect if quotas are not enabled. The
 265 default setting is <CODE>No</CODE>.</P>
 266
 267
 268 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="BrowseLocalProtocols">BrowseLocalProtocols</A></H2>
 269
 270 <H3>Examples</H3>
 271
 272 <PRE CLASS="command">
 273 BrowseLocalProtocols all
 274 BrowseLocalProtocols none
 275 BrowseLocalProtocols dnssd
 276 </PRE>
 277
 278 <H3>Description</H3>
 279
 280 <P>The <CODE>BrowseLocalProtocols</CODE> directive specifies the
 281 protocols to use when advertising local shared printers on the
 282 network. Multiple protocols can be specified by separating them
 283 with spaces. The default is "<CODE>@CUPS_BROWSE_LOCAL_PROTOCOLS@</CODE>".</P>
 284
 285
 286 <H2 CLASS="title"><A NAME="BrowseWebIF">BrowseWebIF</A></H2>
 287
 288 <H3>Examples</H3>
 289
 290 <PRE CLASS="command">
 291 BrowseWebIF On
 292 BrowseWebIF Off
 293 </PRE>
 294
 295 <H3>Description</H3>
 296
 297 <P>The <CODE>BrowseWebIF</CODE> directive controls whether the CUPS web
 298 interface is advertised via DNS-SD. The default setting is
 299 <CODE>Off</CODE>.</P>
 300
 301
 302 <H2 CLASS="title"><A NAME="Browsing">Browsing</A></H2>
 303
 304 <H3>Examples</H3>
 305
 306 <PRE CLASS="command">
 307 Browsing On
 308 Browsing Off
 309 </PRE>
 310
 311 <H3>Description</H3>
 312
 313 <P>The <CODE>Browsing</CODE> directive controls whether or not
 314 printer sharing is enabled. The default setting is
 315 <CODE>@CUPS_BROWSING@</CODE>.</P>
 316
 317
 318 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="Classification">Classification</A></H2>
 319
 320 <H3>Examples</H3>
 321
 322 <PRE CLASS="command">
 323 Classification
 324 Classification classified
 325 Classification confidential
 326 Classification secret
 327 Classification topsecret
 328 Classification unclassified
 329 </PRE>
 330
 331 <H3>Description</H3>
 332
 333 <P>The <CODE>Classification</CODE> directive sets the
 334 classification level on the server. When this option is set, at
 335 least one of the banner pages is forced to the classification
 336 level, and the classification is placed on each page of output.
 337 The default is no classification level.</P>
 338
 339
 340 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.10</SPAN><A NAME="ClassifyOverride">ClassifyOverride</A></H2>
 341
 342 <H3>Examples</H3>
 343
 344 <PRE CLASS="command">
 345 ClassifyOverride Yes
 346 ClassifyOverride No
 347 </PRE>
 348
 349 <H3>Description</H3>
 350
 351 <P>The <CODE>ClassifyOverride</CODE> directive specifies whether
 352 users can override the default classification level on the
 353 server. When the server classification is set, users can change
 354 the classification using the <CODE>job-sheets</CODE> option and
 355 can choose to only print one security banner before or after the
 356 job. If the <CODE>job-sheets</CODE> option is set to
 357 <CODE>none</CODE> then the server default classification is
 358 used.</P>
 359
 360 <P>The default is to not allow classification overrides.</P>
 361
 362
 363 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.15</SPAN><A NAME="ConfigFilePerm">ConfigFilePerm</A></H2>
 364
 365 <H3>Examples</H3>
 366
 367 <PRE CLASS="command">
 368 ConfigFilePerm 0644
 369 ConfigFilePerm 0640
 370 </PRE>
 371
 372 <H3>Description</H3>
 373
 374 <P>The <CODE>ConfigFilePerm</CODE> directive specifies the permissions to use when the scheduler writes configuration and cache files, typically in response to IPP or HTTP requests. The default is @CUPS_CONFIG_FILE_PERM@.</P>
 375
 376 <BLOCKQUOTE><B>Note:</B>
 377
 378 <P>The permissions for the <VAR>printers.conf</VAR> file are always masked to only allow access from the scheduler user (typically root). This is done because printer device URIs sometimes contain sensitive authentication information that should not be generally known on the system. There is no way to disable this security feature.</P>
 379
 380 </BLOCKQUOTE>
 381
 382
 383 <H2 CLASS="title"><A NAME="DataDir">DataDir</A></H2>
 384
 385 <H3>Examples</H3>
 386
 387 <PRE CLASS="command">
 388 DataDir /usr/share/cups
 389 </PRE>
 390
 391 <H3>Description</H3>
 392
 393 <P>The <CODE>DataDir</CODE> directive sets the directory to use
 394 for data files.</P>
 395
 396
 397 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="DefaultAuthType">DefaultAuthType</A></H2>
 398
 399 <H3>Examples</H3>
 400
 401 <PRE CLASS="command">
 402 DefaultAuthType Basic
 403 DefaultAuthType BasicDigest
 404 DefaultAuthType Digest
 405 DefaultAuthType Negotiate
 406 </PRE>
 407
 408 <H3>Description</H3>
 409
 410 <P>The <CODE>DefaultAuthType</CODE> directive specifies the type
 411 of authentication to use for IPP operations that require a
 412 username. The default is <CODE>Basic</CODE>.</P>
 413
 414
 415 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="DefaultEncryption">DefaultEncryption</A></H2>
 416
 417 <H3>Examples</H3>
 418
 419 <PRE CLASS="command">
 420 DefaultEncryption Never
 421 DefaultEncryption IfRequested
 422 DefaultEncryption Required
 423 </PRE>
 424
 425 <H3>Description</H3>
 426
 427 <P>The <CODE>DefaultEncryption</CODE> directive specifies the
 428 type of encryption to use when performing authentication. The
 429 default is <CODE>Required</CODE>.</P>
 430
 431
 432 <H2 CLASS="title"><A NAME="DefaultLanguage">DefaultLanguage</A></H2>
 433
 434 <H3>Examples</H3>
 435
 436 <PRE CLASS="command">
 437 DefaultLanguage de
 438 DefaultLanguage en
 439 DefaultLanguage es
 440 DefaultLanguage fr
 441 DefaultLanguage it
 442 </PRE>
 443
 444 <H3>Description</H3>
 445
 446 <P>The <CODE>DefaultLanguage</CODE> directive specifies the
 447 default language to use for client connections. Setting the
 448 default language also sets the default character set if a
 449 language localization file exists for it. The default language
 450 is "en" for English.</P>
 451
 452
 453 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/OS X 10.6</SPAN><A NAME="DefaultPaperSize">DefaultPaperSize</A></H2>
 454
 455 <H3>Examples</H3>
 456
 457 <PRE CLASS="command">
 458 DefaultPaperSize Letter
 459 DefaultPaperSize A4
 460 DefaultPaperSize Auto
 461 DefaultPaperSize None
 462 </PRE>
 463
 464 <H3>Description</H3>
 465
 466 <P>The <CODE>DefaultPaperSize</CODE> directive specifies the default paper
 467 size to use when creating new printers. The default is <CODE>Auto</CODE>
 468 which uses a paper size appropriate for the system default locale. A value
 469 of <CODE>None</CODE> tells the scheduler to not set the default paper
 470 size.</P>
 471
 472
 473 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="DefaultPolicy">DefaultPolicy</A></H2>
 474
 475 <H3>Examples</H3>
 476
 477 <PRE CLASS="command">
 478 DefaultPolicy default
 479 DefaultPolicy authenticated
 480 DefaultPolicy foo
 481 </PRE>
 482
 483 <H3>Description</H3>
 484
 485 <P>The <CODE>DefaultPolicy</CODE> directive specifies the default
 486 policy to use for IPP operation. The default is
 487 <CODE>default</CODE>. CUPS also includes a policy called
 488 <CODE>authenticated</CODE> that requires a username and password for printing
 489 and other job operations.</P>
 490
 491
 492 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="DefaultShared">DefaultShared</A></H2>
 493
 494 <H3>Examples</H3>
 495
 496 <PRE CLASS="command">
 497 DefaultShared yes
 498 DefaultShared no
 499 </PRE>
 500
 501 <H3>Description</H3>
 502
 503 <P>The <CODE>DefaultShared</CODE> directive specifies whether
 504 printers are shared (published) by default. The default is
 505 <CODE>@CUPS_DEFAULT_SHARED@</CODE>.</P>
 506
 507
 508 <H2 CLASS="title"><A NAME="Deny">Deny</A></H2>
 509
 510 <H3>Examples</H3>
 511
 512 <PRE CLASS="command">
 513 &lt;Location /path&gt;
 514   ..
 515   Deny from All
 516   Deny from None
 517   Deny from *.example.com
 518   Deny from .example.com
 519   Deny from host.example.com
 520   Deny from nnn.*
 521   Deny from nnn.nnn.*
 522   Deny from nnn.nnn.nnn.*
 523   Deny from nnn.nnn.nnn.nnn
 524   Deny from nnn.nnn.nnn.nnn/mm
 525   Deny from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
 526   Deny from [xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]
 527   Deny from [xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]/mmm
 528   Deny from @LOCAL
 529   Deny from @IF(name)
 530 &lt;/Location&gt;
 531 </PRE>
 532
 533 <H3>Description</H3>
 534
 535 <P>The <CODE>Deny</CODE> directive specifies a hostname, IP
 536 address, or network that is denied access to the server.
 537 <CODE>Deny</CODE> directives are cumulative, so multiple
 538 <CODE>Deny</CODE> directives can be used to deny access for
 539 multiple hosts or networks.</P>
 540
 541 <P>Host and domain name matching require that you enable the <A
 542 HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A>
 543 directive.</P>
 544
 545 <P>The <CODE>/mm</CODE> notation specifies a CIDR netmask, a shown in
 546 <A HREF="TABLE1">Table 1</A>.</P>
 547
 548 <P>The <CODE>@LOCAL</CODE> name will deny access from all local
 549 interfaces. The <CODE>@IF(name)</CODE> name will deny access from
 550 the named interface. In both cases, CUPS only denies access from
 551 the network that the interface(s) are configured for - requests
 552 arriving on the interface from a foreign network will
 553 <em>not</em> be denied.</P>
 554
 555 <P>The <CODE>Deny</CODE> directive must appear inside a <A
 556 HREF="#Location"><CODE>Location</CODE></A> or <A
 557 HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
 558
 559
 560 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/OS X 10.6</SPAN><A NAME="DirtyCleanInterval">DirtyCleanInterval</A></H2>
 561
 562 <H3>Examples</H3>
 563
 564 <PRE CLASS="command">
 565 DirtyCleanInterval 1w
 566 DirtyCleanInterval 1d
 567 DirtyCleanInterval 1h
 568 DirtyCleanInterval 1m
 569 DirtyCleanInterval 30
 570 DirtyCleanInterval 0
 571 </PRE>
 572
 573 <H3>Description</H3>
 574
 575 <P>The <CODE>DirtyCleanInterval</CODE> directive specifies the amount of time to wait before updating configuration and state files for printers, classes, subscriptions, and jobs in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix). A value of <CODE>0</CODE> causes the update to occur as soon as possible, typically within a few milliseconds.</P>
 576
 577 <P>The default value is <CODE>30</CODE> (30 seconds).</P>
 578
 579
 580 <H2 CLASS="title"><A NAME="DocumentRoot">DocumentRoot</A></H2>
 581
 582 <H3>Examples</H3>
 583
 584 <PRE CLASS="command">
 585 DocumentRoot /usr/share/doc/cups
 586 DocumentRoot /foo/bar/doc/cups
 587 </PRE>
 588
 589 <H3>Description</H3>
 590
 591 <P>The <CODE>DocumentRoot</CODE> directive specifies the location
 592 of web content for the HTTP server in CUPS. If an absolute path
 593 is not specified then it is assumed to be relative to the <A
 594 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
 595 default directory is <VAR>@CUPS_DOCROOT@</VAR>.</P>
 596
 597 <P>Documents are first looked up in a sub-directory for the
 598 primary language requested by the client (e.g.
 599 <VAR>@CUPS_DOCROOT@/fr/...</VAR>) and then directly under
 600 the <CODE>DocumentRoot</CODE> directory (e.g.
 601 <VAR>@CUPS_DOCROOT@/...</VAR>), so it is possible to
 602 localize the web content by providing subdirectories for each
 603 language needed.</P>
 604
 605
 606 <H2 CLASS="title"><A NAME="Encryption">Encryption</A></H2>
 607
 608 <H3>Examples</H3>
 609
 610 <PRE CLASS="command">
 611 &lt;Location /path&gt;
 612   ...
 613   Encryption Never
 614   Encryption IfRequested
 615   Encryption Required
 616 &lt;/Location&gt;
 617 </PRE>
 618
 619 <H3>Description</H3>
 620
 621 <P>The <CODE>Encryption</CODE> directive must appear instead a <A
 622 HREF="#Location"><CODE>Location</CODE></A> or <A
 623 HREF="#Limit"><CODE>Limit</CODE></A> section and specifies the
 624 encryption settings for that location. The default setting is
 625 <CODE>IfRequested</CODE> for all locations.</P>
 626
 627
 628 <H2 CLASS="title"><A NAME="ErrorLog">ErrorLog</A></H2>
 629
 630 <H3>Examples</H3>
 631
 632 <PRE CLASS="command">
 633 ErrorLog /var/log/cups/error_log
 634 ErrorLog /var/log/cups/error_log-%s
 635 ErrorLog syslog
 636 </PRE>
 637
 638 <H3>Description</H3>
 639
 640 <P>The <CODE>ErrorLog</CODE> directive sets the name of the error
 641 log file. If the filename is not absolute then it is assumed to
 642 be relative to the <A
 643 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
 644 default error log file is <VAR>@CUPS_LOGDIR@/error_log</VAR>.</P>
 645
 646 <P>The server name can be included in the filename by using
 647 <CODE>%s</CODE> in the name.</P>
 648
 649 <P>The special name "syslog" can be used to send the error
 650 information to the system log instead of a plain file.</P>
 651
 652
 653 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.3/OS X 10.5</SPAN><A NAME="ErrorPolicy">ErrorPolicy</A></H2>
 654
 655 <H3>Examples</H3>
 656
 657 <PRE CLASS="command">
 658 ErrorPolicy abort-job
 659 ErrorPolicy retry-job
 660 ErrorPolicy stop-printer
 661 </PRE>
 662
 663 <H3>Description</H3>
 664
 665 <P>The <CODE>ErrorPolicy</CODE> directive defines the default policy that
 666 is used when a backend is unable to send a print job to the
 667 printer.</P>
 668
 669 <P>The following values are supported:</P>
 670
 671 <UL>
 672
 673         <LI><CODE>abort-job</CODE> - Abort the job and proceed
 674         with the next job in the queue</LI>
 675
 676         <LI><CODE>retry-job</CODE> - Retry the job after waiting
 677         for N seconds; the <VAR>cupsd.conf</VAR> <A
 678         HREF="#JobRetryInterval"><CODE>JobRetryInterval</CODE></A>
 679         directive controls the value of N</LI>
 680
 681         <LI><CODE>retry-this-job</CODE> - Retry the current job immediately
 682         and indefinitely.</LI>
 683
 684         <LI><CODE>stop-printer</CODE> - Stop the printer and keep
 685         the job for future printing; this is the default
 686         value</LI>
 687
 688 </UL>
 689
 690
 691
 692 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/OS X 10.6</SPAN><A NAME="FatalErrors">FatalErrors</A></H2>
 693
 694 <H3>Examples</H3>
 695
 696 <PRE CLASS="command">
 697 FatalErrors none
 698 FatalErrors all
 699 FatalErrors browse
 700 FatalErrors config
 701 FatalErrors listen
 702 FatalErrors log
 703 FatalErrors permissions
 704 FatalErrors all -permissions
 705 FatalErrors config permissions log
 706 </PRE>
 707
 708 <H3>Description</H3>
 709
 710 <P>The <CODE>FatalErrors</CODE> directive determines whether certain kinds of
 711 errors are fatal. The following kinds of errors are currently recognized:</P>
 712
 713 <UL>
 714
 715         <LI><CODE>none</CODE> - No errors are fatal</LI>
 716
 717         <LI><CODE>all</CODE> - All of the errors below are fatal</LI>
 718
 719         <LI><CODE>browse</CODE> - Browsing initialization errors are fatal,
 720         for example failed binding to the CUPS browse port or failed connections
 721         to LDAP servers</LI>
 722
 723         <LI><CODE>config</CODE> - Configuration file syntax errors are
 724         fatal</LI>
 725
 726         <LI><CODE>listen</CODE> - Listen or Port errors are fatal, except for
 727         IPv6 failures on the loopback or "any" addresses</LI>
 728
 729         <LI><CODE>log</CODE> - Log file creation or write errors are fatal</LI>
 730
 731         <LI><CODE>permissions</CODE> - Bad startup file permissions are
 732         fatal, for example shared SSL certificate and key files with world-
 733         read permissions</LI>
 734
 735 </UL>
 736
 737 <P>Multiple errors can be listed, and the form "-kind" can be used with
 738 <CODE>all</CODE> to remove specific kinds of errors. The default setting is
 739 <CODE>@CUPS_FATAL_ERRORS@</CODE>.</P>
 740
 741
 742 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.18</SPAN><A NAME="FileDevice">FileDevice</A></H2>
 743
 744 <H3>Examples</H3>
 745
 746 <PRE CLASS="command">
 747 FileDevice Yes
 748 FileDevice No
 749 </PRE>
 750
 751 <H3>Description</H3>
 752
 753 <P>The <CODE>FileDevice</CODE> directive determines whether the
 754 scheduler allows new printers to be added using device URIs of
 755 the form <CODE>file:/filename</CODE>. File devices are most often
 756 used to test new printer drivers and do not support raw file
 757 printing.</P>
 758
 759 <P>The default setting is <CODE>No</CODE>.</P>
 760
 761 <BLOCKQUOTE><B>Note:</B>
 762
 763 <P>File devices are managed by the scheduler. Since the
 764 scheduler normally runs as the root user, file devices
 765 can be used to overwrite system files and potentially
 766 gain unauthorized access to the system. If you must
 767 create printers using file devices, we recommend that
 768 you set the <CODE>FileDevice</CODE> directive to
 769 <CODE>Yes</CODE> for only as long as you need to add the
 770 printers to the system, and then reset the directive to
 771 <CODE>No</CODE>.</P>
 772
 773 </BLOCKQUOTE>
 774
 775
 776 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.3</SPAN><A NAME="FilterLimit">FilterLimit</A></H2>
 777
 778 <H3>Examples</H3>
 779
 780 <PRE CLASS="command">
 781 FilterLimit 0
 782 FilterLimit 200
 783 FilterLimit 1000
 784 </PRE>
 785
 786 <H3>Description</H3>
 787
 788 <P>The <CODE>FilterLimit</CODE> directive sets the maximum cost
 789 of all running job filters. It can be used to limit the number of
 790 filter programs that are run on a server to minimize disk,
 791 memory, and CPU resource problems. A limit of 0 disables filter
 792 limiting.</P>
 793
 794 <P>An average print to a non-PostScript printer needs a filter
 795 limit of about 200. A PostScript printer needs about half that
 796 (100). Setting the limit below these thresholds will effectively
 797 limit the scheduler to printing a single job at any time.</P>
 798
 799 <P>The default limit is 0.</P>
 800
 801
 802 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.16</SPAN><A NAME="FilterNice">FilterNice</A></H2>
 803
 804 <H3>Examples</H3>
 805
 806 <PRE CLASS="command">
 807 FilterNice 0
 808 FilterNice 10
 809 FilterNice 19
 810 </PRE>
 811
 812 <H3>Description</H3>
 813
 814 <P>The <CODE>FilterNice</CODE> directive sets the <B>nice(1)</B>
 815 value to assign to filter processes. The nice value ranges from
 816 0, the highest priority, to 19, the lowest priority. The default
 817 is 0.</P>
 818
 819
 820 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.3</SPAN><A NAME="FontPath">FontPath</A></H2>
 821
 822 <H3>Examples</H3>
 823
 824 <PRE CLASS="command">
 825 FontPath /foo/bar/fonts
 826 FontPath /usr/share/cups/fonts:/foo/bar/fonts
 827 </PRE>
 828
 829 <H3>Description</H3>
 830
 831 <P>The <CODE>FontPath</CODE> directive specifies the font path to
 832 use when searching for fonts. The default font path is
 833 <CODE>/usr/share/cups/fonts</CODE>.</P>
 834
 835
 836 <H2 CLASS="title"><A NAME="Group">Group</A></H2>
 837
 838 <H3>Examples</H3>
 839
 840 <PRE CLASS="command">
 841 Group lp
 842 Group nobody
 843 </PRE>
 844
 845 <H3>Description</H3>
 846
 847 <P>The <CODE>Group</CODE> directive specifies the UNIX group that
 848 filter and CGI programs run as. The default group is
 849 system-specific but is usually <CODE>lp</CODE> or
 850 <CODE>nobody</CODE>.</P>
 851
 852
 853 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.6/OS X 10.8</SPAN><A NAME="GSSServiceName">GSSServiceName</A></H2>
 854
 855 <H3>Examples</H3>
 856
 857 <PRE CLASS="command">
 858 GSSServiceName http
 859 GSSServiceName ipp
 860 </PRE>
 861
 862 <H3>Description</H3>
 863
 864 <P>The <CODE>GSSServiceName</CODE> directive sets the Kerberos service name to use. The default is <CODE>@CUPS_DEFAULT_GSSSERVICE_NAME@</CODE> for compatibility with Microsoft Windows.</P>
 865
 866
 867 <H2 CLASS="title"><A NAME="HostNameLookups">HostNameLookups</A></H2>
 868
 869 <H3>Examples</H3>
 870
 871 <PRE CLASS="command">
 872 HostNameLookups On
 873 HostNameLookups Off
 874 HostNameLookups Double
 875 </PRE>
 876
 877 <H3>Description</H3>
 878
 879 <P>The <CODE>HostNameLookups</CODE> directive controls whether or
 880 not CUPS looks up the hostname for connecting clients. The
 881 <CODE>Double</CODE> setting causes CUPS to verify that the
 882 hostname resolved from the address matches one of the addresses
 883 returned for that hostname. <CODE>Double</CODE> lookups also
 884 prevent clients with unregistered addresses from connecting to
 885 your server.</P>
 886
 887 <P>The default is <CODE>Off</CODE> to avoid the potential server
 888 performance problems with hostname lookups. Set this option to
 889 <CODE>On</CODE> or <CODE>Double</CODE> only if absolutely
 890 required.</P>
 891
 892
 893 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.9</SPAN><A NAME="Include">Include</A></H2>
 894
 895 <H3>Examples</H3>
 896
 897 <PRE CLASS="command">
 898 Include filename
 899 Include /foo/bar/filename
 900 </PRE>
 901
 902 <H3>Description</H3>
 903
 904 <P>The <CODE>Include</CODE> directive includes the named file in
 905 the <CODE>cupsd.conf</CODE> file. If no leading path is provided,
 906 the file is assumed to be relative to the <A
 907 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory.</P>
 908
 909
 910 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.5</SPAN><A NAME="JobPrivateAccess">JobPrivateAccess</A></H2>
 911
 912 <H3>Examples</H3>
 913
 914 <PRE CLASS="command">
 915 JobPrivateAccess all
 916 JobPrivateAccess default
 917 JobPrivateAccess {user|@group|@ACL|@OWNER|@SYSTEM}+
 918 </PRE>
 919
 920 <H3>Description</H3>
 921
 922 <P>The <CODE>JobPrivateAccess</CODE> directive specifies the access list for a
 923 job's private values. The "default" access list is "@OWNER @SYSTEM". "@ACL" maps
 924 to the printer's requesting-user-name-allowed or requesting-user-name-denied
 925 values.</P>
 926
 927 <P>The <CODE>JobPrivateAccess</CODE> directive must appear inside a <A
 928 HREF="#Policy"><CODE>Policy</CODE></A> section.</P>
 929
 930
 931 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.5</SPAN><A NAME="JobPrivateValues">JobPrivateValues</A></H2>
 932
 933 <H3>Examples</H3>
 934
 935 <PRE CLASS="command">
 936 JobPrivateValues all
 937 JobPrivateValues default
 938 JobPrivateValues none
 939 JobPrivateValues attribute-name-1 [ ... attribute-name-N ]
 940 </PRE>
 941
 942 <H3>Description</H3>
 943
 944 <P>The <CODE>JobPrivateValues</CODE> directive specifies the list of job values
 945 to make private. The "default" values are "job-name",
 946 "job-originating-host-name", "job-originating-user-name", and "phone".</P>
 947
 948 <P>The <CODE>JobPrivateValues</CODE> directive must appear inside a <A
 949 HREF="#Policy"><CODE>Policy</CODE></A> section.</P>
 950
 951
 952 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="JobRetryInterval">JobRetryInterval</A></H2>
 953
 954 <H3>Examples</H3>
 955
 956 <PRE CLASS="command">
 957 JobRetryInterval 1w
 958 JobRetryInterval 1d
 959 JobRetryInterval 1h
 960 JobRetryInterval 1m
 961 JobRetryInterval 30
 962 </PRE>
 963
 964 <H3>Description</H3>
 965
 966 <P>The <CODE>JobRetryInterval</CODE> directive specifies the amount of time to wait before retrying a job in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix). This is typically used for fax queues but can also be used with normal print queues whose error policy is <CODE>retry-job</CODE> or <CODE>retry-current-job</CODE>.</P>
 967
 968 <P>The default is <CODE>30</CODE> (30 seconds).</P>
 969
 970
 971 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/OS X 10.6</SPAN><A NAME="JobKillDelay">JobKillDelay</A></H2>
 972
 973 <H3>Examples</H3>
 974
 975 <PRE CLASS="command">
 976 JobKillDelay 1w
 977 JobKillDelay 1d
 978 JobKillDelay 1h
 979 JobKillDelay 1m
 980 JobKillDelay 30
 981 </PRE>
 982
 983 <H3>Description</H3>
 984
 985 <P>The <CODE>JobKillDelay</CODE> directive specifies the amount of time to wait before killing the filters and backend associated with a canceled or held job in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P>
 986
 987 <P>The default is <CODE>30</CODE> (30 seconds).</P>
 988
 989
 990 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="JobRetryLimit">JobRetryLimit</A></H2>
 991
 992 <H3>Examples</H3>
 993
 994 <PRE CLASS="command">
 995 JobRetryLimit 5
 996 JobRetryLimit 50
 997 </PRE>
 998
 999 <H3>Description</H3>
1000
1001 <P>The <CODE>JobRetryLimit</CODE> directive specifies the maximum
1002 number of times the scheduler will try to print a job. This is
1003 typically used for fax queues but can also be used with normal
1004 print queues whose error policy is <CODE>retry-job</CODE>. The
1005 default is 5 times.</P>
1006
1007
1008 <H2 CLASS="title"><A NAME="KeepAlive">KeepAlive</A></H2>
1009
1010 <H3>Examples</H3>
1011
1012 <PRE CLASS="command">
1013 KeepAlive On
1014 KeepAlive Off
1015 </PRE>
1016
1017 <H3>Description</H3>
1018
1019 <P>The <CODE>KeepAlive</CODE> directive controls whether or not
1020 to support persistent HTTP connections. The default is
1021 <CODE>On</CODE>.</P>
1022
1023 <P>HTTP/1.1 clients automatically support persistent connections,
1024 while HTTP/1.0 clients must specifically request them using the
1025 <CODE>Keep-Alive</CODE> attribute in the <CODE>Connection:</CODE>
1026 field of each request.</P>
1027
1028
1029 <H2 CLASS="title"><A NAME="KeepAliveTimeout">KeepAliveTimeout</A></H2>
1030
1031 <H3>Examples</H3>
1032
1033 <PRE CLASS="command">
1034 KeepAliveTimeout 1w
1035 KeepAliveTimeout 1d
1036 KeepAliveTimeout 1h
1037 KeepAliveTimeout 1m
1038 KeepAliveTimeout 30
1039 </PRE>
1040
1041 <H3>Description</H3>
1042
1043 <P>The <CODE>KeepAliveTimeout</CODE> directive controls how long a persistent HTTP connection will remain open after the last request in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P>
1044
1045 <P>The default is <CODE>30</CODE> (30 seconds).</P>
1046
1047
1048 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="Limit">Limit (Location)</A></H2>
1049
1050 <H3>Examples</H3>
1051
1052 <PRE CLASS="command">
1053 &lt;Location /path&gt;
1054   &lt;Limit GET POST&gt;
1055   ...
1056   &lt;/Limit&gt;
1057
1058   &lt;Limit ALL&gt;
1059   ...
1060   &lt;/Limit&gt;
1061 &lt;/Location&gt;
1062 </PRE>
1063
1064 <H3>Description</H3>
1065
1066 <P>The <CODE>Limit</CODE> directive groups access control
1067 directives for specific types of HTTP requests and must appear
1068 inside a <A HREF="#Location"><CODE>Location</CODE></A> section.
1069 Access can be limited for individual request types
1070 (<CODE>DELETE</CODE>, <CODE>GET</CODE>, <CODE>HEAD</CODE>,
1071 <CODE>OPTIONS</CODE>, <CODE>POST</CODE>, <CODE>PUT</CODE>, and
1072 <CODE>TRACE</CODE>) or for all request types (<CODE>ALL</CODE>).
1073 The request type names are case-sensitive for compatibility with
1074 Apache.</P>
1075
1076
1077 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="LimitIPP">Limit (Policy)</A></H2>
1078
1079 <H3>Examples</H3>
1080
1081 <PRE CLASS="command">
1082 &lt;Policy name&gt;
1083   &lt;Limit CUPS-Add-Modify-Printer CUPS-Delete-Printer&gt;
1084   ...
1085   &lt;/Limit&gt;
1086
1087   &lt;Limit All&gt;
1088   ...
1089   &lt;/Limit&gt;
1090 &lt;/Policy&gt;
1091 </PRE>
1092
1093 <H3>Description</H3>
1094
1095 <P>When included in <A HREF="#Policy"><CODE>Policy</CODE></A>
1096 sections, the <CODE>Limit</CODE> directive groups access control
1097 directives for specific IPP operations. Multiple operations can
1098 be listed, separated by spaces. Table 2 lists the supported
1099 operations.</P>
1100
1101 <DIV CLASS="table"><TABLE SUMMARY="Supported IPP Operations">
1102 <CAPTION>Table 2: <A NAME="TABLE2">Supported IPP Operations</A></CAPTION>
1103 <THEAD>
1104 <TR>
1105         <TH>Operation Name</TH>
1106         <TH>Description</TH>
1107 </TR>
1108 </THEAD>
1109 <TBODY>
1110 <TR>
1111         <TD>All</TD>
1112         <TD>All operations - used as the default limit for
1113         operations that are not listed</TD>
1114 </TR>
1115 <TR>
1116         <TD>Cancel-Job</TD>
1117         <TD>Cancel a job</TD>
1118 </TR>
1119 <TR>
1120         <TD>Cancel-Subscription</TD>
1121         <TD>Cancel a subscription</TD>
1122 </TR>
1123 <TR>
1124         <TD>Create-Job</TD>
1125         <TD>Create a new, empty job</TD>
1126 </TR>
1127 <TR>
1128         <TD>Create-Job-Subscription</TD>
1129         <TD>Creates a notification subscription on a job</TD>
1130 </TR>
1131 <TR>
1132         <TD>Create-Printer-Subscription</TD>
1133         <TD>Creates a notification subscription on a printer</TD>
1134 </TR>
1135 <TR>
1136         <TD>CUPS-Accept-Jobs</TD>
1137         <TD>Sets the printer-is-accepting-jobs value for a printer to true</TD>
1138 </TR>
1139 <TR>
1140         <TD>CUPS-Add-Modify-Class</TD>
1141         <TD>Adds or modifies a class</TD>
1142 </TR>
1143 <TR>
1144         <TD>CUPS-Add-Modify-Printer</TD>
1145         <TD>Adds or modifies a printer</TD>
1146 </TR>
1147 <TR>
1148         <TD>CUPS-Authenticate-Job</TD>
1149         <TD>Authenticates a job for printing</TD>
1150 </TR>
1151 <TR>
1152         <TD>CUPS-Delete-Class</TD>
1153         <TD>Deletes a class</TD>
1154 </TR>
1155 <TR>
1156         <TD>CUPS-Delete-Printer</TD>
1157         <TD>Deletes a printer</TD>
1158 </TR>
1159 <TR>
1160         <TD>CUPS-Get-Classes</TD>
1161         <TD>Gets a list of classes</TD>
1162 </TR>
1163 <TR>
1164         <TD>CUPS-Get-Default</TD>
1165         <TD>Gets the (network/server) default printer or class</TD>
1166 </TR>
1167 <TR>
1168         <TD>CUPS-Get-Devices</TD>
1169         <TD>Gets a list of available devices</TD>
1170 </TR>
1171 <TR>
1172         <TD>CUPS-Get-PPDs</TD>
1173         <TD>Gets a list of available manufacturers or drivers</TD>
1174 </TR>
1175 <TR>
1176         <TD>CUPS-Get-Printers</TD>
1177         <TD>Gets a list of printers and/or classes</TD>
1178 </TR>
1179 <TR>
1180         <TD>CUPS-Move-Job</TD>
1181         <TD>Moves a job to a new destination</TD>
1182 </TR>
1183 <TR>
1184         <TD>CUPS-Reject-Jobs</TD>
1185         <TD>Sets the printer-is-accepting-jobs value for a printer to false</TD>
1186 </TR>
1187 <TR>
1188         <TD>CUPS-Set-Default</TD>
1189         <TD>Sets the network/server default printer or class</TD>
1190 </TR>
1191 <TR>
1192         <TD>Disable-Printer</TD>
1193         <TD>Sets the printer-state value for a printer to stopped</TD>
1194 </TR>
1195 <TR>
1196         <TD>Enable-Printer</TD>
1197         <TD>Sets the printer-state value for a printer to idle/processing</TD>
1198 </TR>
1199 <TR>
1200         <TD>Get-Job-Attributes</TD>
1201         <TD>Gets information about a job</TD>
1202 </TR>
1203 <TR>
1204         <TD>Get-Jobs</TD>
1205         <TD>Gets a list of jobs</TD>
1206 </TR>
1207 <TR>
1208         <TD>Get-Notifications</TD>
1209         <TD>Gets a list of events</TD>
1210 </TR>
1211 <TR>
1212         <TD>Get-Printer-Attributes</TD>
1213         <TD>Gets information about a printer or class</TD>
1214 </TR>
1215 <TR>
1216         <TD>Get-Subscription-Attributes</TD>
1217         <TD>Gets information about a notification subscription</TD>
1218 </TR>
1219 <TR>
1220         <TD>Get-Subscriptions</TD>
1221         <TD>Gets a list of notification subscriptions</TD>
1222 </TR>
1223 <TR>
1224         <TD>Hold-Job</TD>
1225         <TD>Holds a job for printing</TD>
1226 </TR>
1227 <TR>
1228         <TD>Pause-Printer</TD>
1229         <TD>Sets the printer-state value for a printer to stopped</TD>
1230 </TR>
1231 <TR>
1232         <TD>Print-Job</TD>
1233         <TD>Creates a job with a single file for printing</TD>
1234 </TR>
1235 <TR>
1236         <TD>Purge-Jobs</TD>
1237         <TD>Removes all jobs from a printer</TD>
1238 </TR>
1239 <TR>
1240         <TD>Release-Job</TD>
1241         <TD>Releases a previously held job for printing</TD>
1242 </TR>
1243 <TR>
1244         <TD>Renew-Subscription</TD>
1245         <TD>Renews a notification subscription</TD>
1246 </TR>
1247 <TR>
1248         <TD>Restart-Job</TD>
1249         <TD>Reprints a job</TD>
1250 </TR>
1251 <TR>
1252         <TD>Resume-Printer</TD>
1253         <TD>Sets the printer-state value for a printer to idle/processing</TD>
1254 </TR>
1255 <TR>
1256         <TD>Send-Document</TD>
1257         <TD>Adds a file to an job created with Create-Job</TD>
1258 </TR>
1259 <TR>
1260         <TD>Set-Job-Attributes</TD>
1261         <TD>Changes job options</TD>
1262 </TR>
1263 <TR>
1264         <TD>Validate-Job</TD>
1265         <TD>Validates job options prior to printing</TD>
1266 </TR>
1267 </TBODY>
1268 </TABLE></DIV>
1269
1270
1271 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="LimitExcept">LimitExcept</A></H2>
1272
1273 <H3>Examples</H3>
1274
1275 <PRE CLASS="command">
1276 &lt;Location /path&gt;
1277   &lt;LimitExcept GET POST&gt;
1278   ...
1279   &lt;/LimitExcept&gt;
1280 &lt;/Location&gt;
1281 </PRE>
1282
1283 <H3>Description</H3>
1284
1285 <P>The <CODE>LimitExcept</CODE> directive groups access control
1286 directives for specific types of HTTP requests and must appear
1287 inside a <A HREF="#Location"><CODE>Location</CODE></A> section.
1288 Unlike the <A HREF="#Limit"><CODE>Limit</CODE></A> directive,
1289 <CODE>LimitExcept</CODE> restricts access for all requests
1290 <I>except</I> those listed on the <CODE>LimitExcept</CODE>
1291 line.</P>
1292
1293
1294 <H2 CLASS="title"><A NAME="LimitRequestBody">LimitRequestBody</A></H2>
1295
1296 <H3>Examples</H3>
1297
1298 <PRE CLASS="command">
1299 LimitRequestBody 10485760
1300 LimitRequestBody 10m
1301 LimitRequestBody 0
1302 </PRE>
1303
1304 <H3>Description</H3>
1305
1306 <P>The <CODE>LimitRequestBody</CODE> directive controls the
1307 maximum size of print files, IPP requests, and HTML form data in
1308 HTTP POST requests. The default limit is 0 which disables the
1309 limit check.</P>
1310
1311
1312 <H2 CLASS="title"><A NAME="Listen">Listen</A></H2>
1313
1314 <H3>Examples</H3>
1315
1316 <PRE CLASS="command">
1317 Listen 127.0.0.1:631
1318 Listen 192.0.2.1:631
1319 Listen [::1]:631
1320 Listen *:631
1321 </PRE>
1322
1323 <H3>Description</H3>
1324
1325 <P>The <CODE>Listen</CODE> directive specifies a network address
1326 and port to listen for connections. Multiple <CODE>Listen</CODE>
1327 directives can be provided to listen on multiple addresses.</P>
1328
1329 <P>The <CODE>Listen</CODE> directive is similar to the <A
1330 HREF="#Port"><CODE>Port</CODE></A> directive but allows you to
1331 restrict access to specific interfaces or networks.</P>
1332
1333
1334 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="ListenBackLog">ListenBackLog</A></H2>
1335
1336 <H3>Examples</H3>
1337
1338 <PRE CLASS="command">
1339 ListenBackLog 5
1340 ListenBackLog 10
1341 </PRE>
1342
1343 <H3>Description</H3>
1344
1345 <P>The <CODE>ListenBackLog</CODE> directive sets the maximum
1346 number of pending connections the scheduler will allow. This
1347 normally only affects very busy servers that have reached the <A
1348 HREF="#MaxClients"><CODE>MaxClients</CODE></A> limit, but can
1349 also be triggered by large numbers of simultaneous connections.
1350 When the limit is reached, the operating system will refuse
1351 additional connections until the scheduler can accept the pending
1352 ones. The default is the OS-defined default limit, typically
1353 either 5 for older operating systems or 128 for newer operating
1354 systems.</P>
1355
1356
1357 <H2 CLASS="title"><A NAME="Location">Location</A></H2>
1358
1359 <H3>Examples</H3>
1360
1361 <PRE CLASS="command">
1362 &lt;Location /&gt;
1363 ...
1364 &lt;/Location&gt;
1365
1366 &lt;Location /admin&gt;
1367 ...
1368 &lt;/Location&gt;
1369
1370 &lt;Location /admin/conf&gt;
1371 ...
1372 &lt;/Location&gt;
1373
1374 &lt;Location /admin/log&gt;
1375 ...
1376 &lt;/Location&gt;
1377
1378 &lt;Location /classes&gt;
1379 ...
1380 &lt;/Location&gt;
1381
1382 &lt;Location /classes/name&gt;
1383 ...
1384 &lt;/Location&gt;
1385
1386 &lt;Location /jobs&gt;
1387 ...
1388 &lt;/Location&gt;
1389
1390 &lt;Location /printers&gt;
1391 ...
1392 &lt;/Location&gt;
1393
1394 &lt;Location /printers/name&gt;
1395 ...
1396 &lt;/Location&gt;
1397
1398 </PRE>
1399
1400 <H3>Description</H3>
1401
1402 <P>The <CODE>Location</CODE> directive specifies access control
1403 and authentication options for the specified HTTP resource or
1404 path.  The  <A HREF="#Allow"><CODE>Allow</CODE></A>,  <A
1405 HREF="#AuthType"><CODE>AuthType</CODE></A>,  <A
1406 HREF="#Deny"><CODE>Deny</CODE></A>,  <A
1407 HREF="#Encryption"><CODE>Encryption</CODE></A>,  <A
1408 HREF="#Limit"><CODE>Limit</CODE></A>,  <A
1409 HREF="#LimitExcept"><CODE>LimitExcept</CODE></A>,  <A
1410 HREF="#Order"><CODE>Order</CODE></A>,  <A
1411 HREF="#Require"><CODE>Require</CODE></A>, and <A
1412 HREF="#Satisfy"><CODE>Satisfy</CODE></A> directives may all
1413 appear inside a location.</P>
1414
1415 <P>Note that more specific resources override the less specific
1416 ones. So the directives inside the <CODE>/printers/name</CODE>
1417 location will override ones from <CODE>/printers</CODE>.
1418 Directives inside <CODE>/printers</CODE> will override ones from
1419 <CODE>/</CODE>. None of the directives are inherited.</P>
1420
1421 <DIV CLASS="table"><TABLE SUMMARY="Common Locations on the Server">
1422 <CAPTION>Table 3: <A NAME="TABLE3">Common Locations on the Server</A></CAPTION>
1423 <THEAD>
1424 <TR><TH>Location</TH><TH>Description</TH></TR>
1425 </THEAD>
1426 <TBODY>
1427 <TR><TD><CODE>/</CODE></TD><TD>The path for all get operations (get-printers, get-jobs, etc.)</TD></TR>
1428 <TR><TD><CODE>/admin</CODE></TD><TD>The path for all administration operations (add-printer, delete-printer, start-printer, etc.)</TD></TR>
1429 <TR><TD><CODE>/admin/conf</CODE></TD><TD>The path for access to the CUPS configuration files (cupsd.conf, client.conf, etc.)</TD></TR>
1430 <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>
1431 <TR><TD><CODE>/classes</CODE></TD><TD>The path for all classes</TD></TR>
1432 <TR><TD><CODE>/classes/name</CODE></TD><TD>The resource for class <CODE>name</CODE></TD></TR>
1433 <TR><TD><CODE>/jobs</CODE></TD><TD>The path for all jobs (hold-job, release-job, etc.)</TD></TR>
1434 <TR><TD><CODE>/jobs/id</CODE></TD><TD>The resource for job <CODE>id</CODE></TD></TR>
1435 <TR><TD><CODE>/printers</CODE></TD><TD>The path for all printers</TD></TR>
1436 <TR><TD><CODE>/printers/name</CODE></TD><TD>The path for printer <CODE>name</CODE></TD></TR>
1437 <TR><TD><CODE>/printers/name.ppd</CODE></TD><TD>The PPD file path for printer <CODE>name</CODE></TD></TR>
1438 </TBODY>
1439 </TABLE></DIV>
1440
1441
1442 <H2 CLASS="title"><A NAME="LogDebugHistory">LogDebugHistory</A></H2>
1443
1444 <H3>Examples</H3>
1445
1446 <PRE CLASS="command">
1447 LogDebugHistory 0
1448 LogDebugHistory 200
1449 </PRE>
1450
1451 <H3>Description</H3>
1452
1453 <P>When <A HREF="#LogLevel"><CODE>LogLevel</CODE></A> is not set to
1454 <CODE>debug</CODE> or <CODE>debug2</CODE>, the <CODE>LogDebugHistory</CODE>
1455 directive specifies the number of debugging messages that are logged when an
1456 error occurs during printing. The default is 200 messages. A value of 0
1457 disables debugging history entirely and is not recommended.</P>
1458
1459
1460 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.15</SPAN><A NAME="LogFilePerm">LogFilePerm</A></H2>
1461
1462 <H3>Examples</H3>
1463
1464 <PRE CLASS="command">
1465 LogFilePerm 0644
1466 LogFilePerm 0600
1467 </PRE>
1468
1469 <H3>Description</H3>
1470
1471 <P>The <CODE>LogFilePerm</CODE> directive specifies the
1472 permissions to use when writing log files. The default
1473 is @CUPS_LOG_FILE_PERM@.</P>
1474
1475
1476 <H2 CLASS="title"><A NAME="LogLevel">LogLevel</A></H2>
1477
1478 <H3>Examples</H3>
1479
1480 <PRE CLASS="command">
1481 LogLevel none
1482 LogLevel emerg
1483 LogLevel alert
1484 LogLevel crit
1485 LogLevel error
1486 LogLevel warn
1487 LogLevel notice
1488 LogLevel info
1489 LogLevel debug
1490 LogLevel debug2
1491 </PRE>
1492
1493 <H3>Description</H3>
1494
1495 <P>The <CODE>LogLevel</CODE> directive specifies the level of
1496 logging for the <A HREF="#ErrorLog"><CODE>ErrorLog</CODE></A>
1497 file. The following values are recognized (each level logs
1498 everything under the preceding levels):</P>
1499
1500 <UL>
1501
1502         <LI><CODE>none</CODE> - Log nothing</LI>
1503
1504         <LI><CODE>emerg</CODE> - Log emergency conditions that
1505         prevent the server from running</LI>
1506
1507         <LI><CODE>alert</CODE> - Log alerts that must be handled
1508         immediately</LI>
1509
1510         <LI><CODE>crit</CODE> - Log critical errors that don't
1511         prevent the server from running</LI>
1512
1513         <LI><CODE>error</CODE> - Log general errors</LI>
1514
1515         <LI><CODE>warn</CODE> - Log errors and warnings</LI>
1516
1517         <LI><CODE>notice</CODE> - Log temporary error conditions</LI>
1518
1519         <LI><CODE>info</CODE> - Log all requests and state
1520         changes</LI>
1521
1522         <LI><CODE>debug</CODE> - Log basic debugging
1523         information</LI>
1524
1525         <LI><CODE>debug2</CODE> - Log all debugging
1526         information</LI>
1527
1528 </UL>
1529
1530 <p>The default <code>LogLevel</code> is <code>@CUPS_LOG_LEVEL@</code>.</p>
1531
1532
1533 <H2 CLASS="title"><A NAME="LogTimeFormat">LogTimeFormat</A></H2>
1534
1535 <H3>Examples</H3>
1536
1537 <PRE CLASS="command">
1538 LogTimeFormat standard
1539 LogTimeFormat usecs
1540 </PRE>
1541
1542 <H3>Description</H3>
1543
1544 <P>The <CODE>LogTimeFormat</CODE> directive specifies the format used for the
1545 date and time in the log files. <CODE>Standard</CODE> uses the standard Apache
1546 Common Log Format date and time while <CODE>usecs</CODE> adds microseconds.
1547 The default is <CODE>standard</CODE>.</P>
1548
1549
1550 <H2 CLASS="title"><A NAME="MaxClients">MaxClients</A></H2>
1551
1552 <H3>Examples</H3>
1553
1554 <PRE CLASS="command">
1555 MaxClients 100
1556 MaxClients 1024
1557 </PRE>
1558
1559 <H3>Description</H3>
1560
1561 <P>The <CODE>MaxClients</CODE> directive controls the maximum
1562 number of simultaneous clients that will be allowed by the
1563 server. The default is 100 clients.</P>
1564
1565 <BLOCKQUOTE><B>Note:</B>
1566
1567 <P>Since each print job requires a file descriptor for the status
1568 pipe, the scheduler internally limits the <CODE>MaxClients</CODE>
1569 value to 1/3 of the available file descriptors to avoid possible
1570 problems when printing large numbers of jobs.</P>
1571
1572 </BLOCKQUOTE>
1573
1574
1575 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.18</SPAN><A NAME="MaxClientsPerHost">MaxClientsPerHost</A></H2>
1576
1577 <H3>Examples</H3>
1578
1579 <PRE CLASS="command">
1580 MaxClientsPerHost 10
1581 </PRE>
1582
1583 <H3>Description</H3>
1584
1585 <P>The <CODE>MaxClientsPerHost</CODE> directive controls the
1586 maximum number of simultaneous clients that will be allowed from
1587 a single host by the server. The default is the
1588 <CODE>MaxClients</CODE> value.</P>
1589
1590 <P>This directive provides a small measure of protection against
1591 Denial of Service attacks from a single host.</P>
1592
1593
1594 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.16</SPAN><A NAME="MaxCopies">MaxCopies</A></H2>
1595
1596 <H3>Examples</H3>
1597
1598 <PRE CLASS="command">
1599 MaxCopies 100
1600 MaxCopies 65535
1601 </PRE>
1602
1603 <H3>Description</H3>
1604
1605 <P>The <CODE>MaxCopies</CODE> directive controls the maximum
1606 number of copies that a user can print of a job. The default is
1607 @CUPS_MAX_COPIES@ copies.</P>
1608
1609 <BLOCKQUOTE><B>Note:</B>
1610
1611 <P>Most HP PCL laser printers internally limit the number of
1612 copies to 100.</P>
1613
1614 </BLOCKQUOTE>
1615
1616
1617 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.6/OS X 10.8</SPAN><A NAME="MaxHoldTime">MaxHoldTime</A></H2>
1618
1619 <H3>Examples</H3>
1620
1621 <PRE CLASS="command">
1622 MaxHoldTime 10800
1623 MaxHoldTime 3h
1624 MaxHoldTime 180m
1625 MaxHoldTime 0
1626 </PRE>
1627
1628 <H3>Description</H3>
1629
1630 <P>The <CODE>MaxHoldTime</CODE> directive controls the maximum number of seconds allowed for a job to remain in the "indefinite" hold state. The job is canceled automatically if it remains held indefinitely longer than the specified time interval in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P>
1631
1632 <p>The default setting is <CODE>0</CODE> which disables this functionality.</P>
1633
1634
1635 <H2 CLASS="title"><A NAME="MaxJobs">MaxJobs</A></H2>
1636
1637 <H3>Examples</H3>
1638
1639 <PRE CLASS="command">
1640 MaxJobs 100
1641 MaxJobs 9999
1642 MaxJobs 0
1643 </PRE>
1644
1645 <H3>Description</H3>
1646
1647 <P>The <CODE>MaxJobs</CODE> directive controls the maximum number
1648 of jobs that are kept in memory. Once the number of jobs reaches
1649 the limit, the oldest completed job is automatically purged from
1650 the system to make room for the new one. If all of the known jobs
1651 are still pending or active then the new job will be
1652 rejected.</P>
1653
1654 <P>Setting the maximum size to 0 disables this functionality. The
1655 default setting is 500.</P>
1656
1657
1658 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="MaxJobsPerPrinter">MaxJobsPerPrinter</A></H2>
1659
1660 <H3>Examples</H3>
1661
1662 <PRE CLASS="command">
1663 MaxJobsPerPrinter 100
1664 MaxJobsPerPrinter 9999
1665 MaxJobsPerPrinter 0
1666 </PRE>
1667
1668 <H3>Description</H3>
1669
1670 <P>The <CODE>MaxJobsPerPrinter</CODE> directive controls the
1671 maximum number of active jobs that are allowed for each printer
1672 or class. Once a printer or class reaches the limit, new jobs
1673 will be rejected until one of the active jobs is completed,
1674 stopped, aborted, or canceled.</P>
1675
1676 <P>Setting the maximum to 0 disables this functionality. The
1677 default setting is 0.</P>
1678
1679
1680 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="MaxJobsPerUser">MaxJobsPerUser</A></H2>
1681
1682 <H3>Examples</H3>
1683
1684 <PRE CLASS="command">
1685 MaxJobsPerUser 100
1686 MaxJobsPerUser 9999
1687 MaxJobsPerUser 0
1688 </PRE>
1689
1690 <H3>Description</H3>
1691
1692 <P>The <CODE>MaxJobsPerUser</CODE> directive controls the maximum
1693 number of active jobs that are allowed for each user. Once a user
1694 reaches the limit, new jobs will be rejected until one of the
1695 active jobs is completed, stopped, aborted, or canceled.</P>
1696
1697 <P>Setting the maximum to 0 disables this functionality. The
1698 default setting is 0.</P>
1699
1700
1701 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.6/OS X 10.8</SPAN><A NAME="MaxJobTime">MaxJobTime</A></H2>
1702
1703 <H3>Examples</H3>
1704
1705 <PRE CLASS="command">
1706 MaxJobTime 10800
1707 MaxJobTime 3h
1708 MaxJobTime 180m
1709 MaxJobTime 0
1710 </PRE>
1711
1712 <H3>Description</H3>
1713
1714 <P>The <CODE>MaxJobTime</CODE> directive controls the maximum number of
1715 seconds allowed for a job to complete printing before it is considered "stuck".
1716 The job is canceled automatically if it takes longer than the specified time to complete in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P>
1717
1718 <p>Setting the maximum time to <CODE>0</CODE> disables this functionality. The default setting is <CODE>3h</CODE> (3 hours).</P>
1719
1720
1721 <H2 CLASS="title"><A NAME="MaxLogSize">MaxLogSize</A></H2>
1722
1723 <H3>Examples</H3>
1724
1725 <PRE CLASS="command">
1726 MaxLogSize 1048576
1727 MaxLogSize 1m
1728 MaxLogSize 0
1729 </PRE>
1730
1731 <H3>Description</H3>
1732
1733 <P>The <CODE>MaxLogSize</CODE> directive controls the maximum
1734 size of each log file. Once a log file reaches or exceeds the
1735 maximum size it is closed and renamed to <VAR>filename.O</VAR>.
1736 This allows you to rotate the logs automatically. The default
1737 size is 1048576 bytes (1MB).</P>
1738
1739 <P>Setting the maximum size to 0 disables log rotation.</P>
1740
1741
1742 <H2 CLASS="title"><SPAN CLASS="info">Deprecated</SPAN><A NAME="MaxRequestSize">MaxRequestSize</A></H2>
1743
1744 <H3>Examples</H3>
1745
1746 <PRE CLASS="command">
1747 MaxRequestSize 10485760
1748 MaxRequestSize 10m
1749 MaxRequestSize 0
1750 </PRE>
1751
1752 <H3>Description</H3>
1753
1754 <P>The <CODE>MaxRequestSize</CODE> directive controls the maximum
1755 size of print files, IPP requests, and HTML form data in HTTP
1756 POST requests. The default limit is 0 which disables the limit
1757 check.</P>
1758
1759 <P><B>This directive is deprecated and will be removed in a
1760 future CUPS release.</B> Use the <A
1761 HREF="#LimitRequestBody"><CODE>LimitRequestBody</CODE></A>
1762 directive instead.</P>
1763
1764
1765 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/OS X 10.6</SPAN><A NAME="MultipleOperationTimeout">MultipleOperationTimeout</A></H2>
1766
1767 <H3>Examples</H3>
1768
1769 <PRE CLASS="command">
1770 MultipleOperationTimeout 1w
1771 MultipleOperationTimeout 1d
1772 MultipleOperationTimeout 1h
1773 MultipleOperationTimeout 5m
1774 MultipleOperationTimeout 300
1775 </PRE>
1776
1777 <H3>Description</H3>
1778
1779 <P>The <CODE>MultipleOperationTimeout</CODE> directive sets the maximum amount of time between files in a multi-file print job in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P>
1780
1781 <P>The default is <CODE>5m</CODE> (five minutes).</P>
1782
1783
1784 <H2 CLASS="title"><A NAME="Order">Order</A></H2>
1785
1786 <H3>Examples</H3>
1787
1788 <PRE CLASS="command">
1789 &lt;Location /path&gt;
1790   ...
1791   Order Allow,Deny
1792   Order Deny,Allow
1793 &lt;/Location&gt;
1794 </PRE>
1795
1796 <H3>Description</H3>
1797
1798 <P>The <CODE>Order</CODE> directive defines the default access
1799 control. The following values are supported:</P>
1800
1801 <UL>
1802
1803         <LI><CODE>allow,deny</CODE> - Deny requests by default,
1804         then check the <A HREF="#Allow"><CODE>Allow</CODE></A>
1805         lines followed by the <A
1806         HREF="#Deny"><CODE>Deny</CODE></A> lines</LI>
1807
1808         <LI><CODE>deny,allow</CODE> - Allow requests by default,
1809         then check the <A HREF="#Deny"><CODE>Deny</CODE></A>
1810         lines followed by the <A
1811         HREF="#Allow"><CODE>Allow</CODE></A> lines</LI>
1812
1813 </UL>
1814
1815 <P>The <CODE>Order</CODE> directive must appear inside a <A
1816 HREF="#Location"><CODE>Location</CODE></A> or <A
1817 HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
1818
1819
1820 <H2 CLASS="title"><A NAME="PageLog">PageLog</A></H2>
1821
1822 <H3>Examples</H3>
1823
1824 <PRE CLASS="command">
1825 PageLog /var/log/cups/page_log
1826 PageLog /var/log/cups/page_log-%s
1827 PageLog syslog
1828 </PRE>
1829
1830 <H3>Description</H3>
1831
1832 <P>The <CODE>PageLog</CODE> directive sets the name of the page
1833 log file. If the filename is not absolute then it is assumed to
1834 be relative to the <A
1835 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
1836 default page log file is <VAR>@CUPS_LOGDIR@/page_log</VAR>.</P>
1837
1838 <P>The server name can be included in the filename by using
1839 <CODE>%s</CODE> in the name.</P>
1840
1841 <P>The special name "syslog" can be used to send the page
1842 information to the system log instead of a plain file.</P>
1843
1844
1845 <H2 CLASS="title"><A NAME="PageLogFormat">PageLogFormat</A></H2>
1846
1847 <H3>Examples</H3>
1848
1849 <PRE CLASS="command">
1850 PageLogFormat %p %u %j %T %P %C %{job-billing} %{job-originating-host-name} %{job-name} %{media} %{sides}
1851 PageLogFormat PAGE %p %u %j %P %C %{job-billing} %{job-originating-host-name}
1852 </PRE>
1853
1854 <H3>Description</H3>
1855
1856 <P>The <CODE>PageLogFormat</CODE> directive sets the format of lines
1857 that are logged to the page log file. Sequences beginning with percent (%)
1858 characters are replaced with the corresponding information, while all other
1859 characters are copied literally. The following percent sequences are
1860 recognized:</P>
1861
1862 <UL>
1863
1864         <LI><CODE>%%</CODE>: Inserts a single percent character.</LI>
1865
1866         <LI><CODE>%{name}</CODE>: Inserts the value of the specified IPP
1867         attribute.</LI>
1868
1869         <LI><CODE>%C</CODE>: Inserts the number of copies for the current page.</LI>
1870
1871         <LI><CODE>%P</CODE>: Inserts the current page number.</LI>
1872
1873         <LI><CODE>%T</CODE>: Inserts the current date and time in common log
1874         format.</LI>
1875
1876         <LI><CODE>%j</CODE>: Inserts the job ID.</LI>
1877
1878         <LI><CODE>%p</CODE>: Inserts the printer name.</LI>
1879
1880         <LI><CODE>%u</CODE>: Inserts the username.</LI>
1881
1882 </UL>
1883
1884 <P>The default is "%p %u %j %T %P %C %{job-billing} %{job-originating-host-name} %{job-name} %{media} %{sides}".</P>
1885
1886
1887 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="PassEnv">PassEnv</A></H2>
1888
1889 <H3>Examples</H3>
1890
1891 <PRE CLASS="command">
1892 PassEnv MY_ENV_VARIABLE
1893 </PRE>
1894
1895 <H3>Description</H3>
1896
1897 <P>The <CODE>PassEnv</CODE> directive specifies an environment
1898 variable that should be passed to child processes. Normally, the
1899 scheduler only passes the <CODE>DYLD_LIBRARY_PATH</CODE>,
1900 <CODE>LD_ASSUME_KERNEL</CODE>, <CODE>LD_LIBRARY_PATH</CODE>,
1901 <CODE>LD_PRELOAD</CODE>, <CODE>NLSPATH</CODE>,
1902 <CODE>SHLIB_PATH</CODE>, <CODE>TZ</CODE>, and <CODE>VGARGS</CODE>
1903 environment variables to child processes.</P>
1904
1905
1906 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="Policy">Policy</A></H2>
1907
1908 <H3>Examples</H3>
1909
1910 <PRE CLASS="command">
1911 &lt;Policy name&gt;
1912   &lt;Limit operation ... operation&gt;
1913   ...
1914   &lt;/Limit&gt;
1915   &lt;Limit operation ... operation&gt;
1916   ...
1917   &lt;/Limit&gt;
1918   &lt;Limit All&gt;
1919   ...
1920   &lt;/Limit&gt;
1921 &lt;/Policy&gt;
1922 </PRE>
1923
1924 <H3>Description</H3>
1925
1926 <P>The <CODE>Policy</CODE> directive specifies IPP operation
1927 access control limits. Each policy contains 1 or more <A
1928 HREF="#LimitIPP"><CODE>Limit</CODE></A> sections to set the
1929 access control limits for specific operations - user limits,
1930 authentication, encryption, and allowed/denied addresses,
1931 domains, or hosts. The <CODE>&lt;Limit All&gt;</CODE> section
1932 specifies the default access control limits for operations that
1933 are not listed.</P>
1934
1935 <P>Policies are named and associated with printers via the
1936 printer's operation policy setting
1937 (<CODE>printer-op-policy</CODE>). The default policy for the
1938 scheduler is specified using the <A
1939 HREF="#DefaultPolicy"><CODE>DefaultPolicy</CODE></A>
1940 directive.</P>
1941
1942
1943 <H2 CLASS="title"><A NAME="Port">Port</A></H2>
1944
1945 <H3>Examples</H3>
1946
1947 <PRE CLASS="command">
1948 Port 631
1949 Port 80
1950 </PRE>
1951
1952 <H3>Description</H3>
1953
1954 <P>The <CODE>Port</CODE> directive specifies a port to listen on.
1955 Multiple <CODE>Port</CODE> lines can be specified to listen on
1956 multiple ports. The <CODE>Port</CODE> directive is equivalent to
1957 "<CODE>Listen *:nnn</CODE>". The default port is 631.</P>
1958
1959 <BLOCKQUOTE><B>Note:</B>
1960
1961 <P>On systems that support IPv6, this directive will bind to both
1962 the IPv4 and IPv6 wildcard address.</P>
1963
1964 </BLOCKQUOTE>
1965
1966
1967 <H2 CLASS="title"><A NAME="PreserveJobHistory">PreserveJobHistory</A></H2>
1968
1969 <H3>Examples</H3>
1970
1971 <PRE CLASS="command">
1972 PreserveJobHistory On
1973 PreserveJobHistory Off
1974 PreserveJobHistory 1w
1975 PreserveJobHistory 7d
1976 PreserveJobHistory 168h
1977 PreserveJobHistory 10080m
1978 PreserveJobHistory 604800
1979 </PRE>
1980
1981 <H3>Description</H3>
1982
1983 <P>The <CODE>PreserveJobHistory</CODE> directive controls whether the history of completed, canceled, or aborted print jobs is retained by the scheduler. A value of <CODE>On</CODE> preserves job information until the administrator purges it with the <CODE>cancel</CODE> command. A value of <CODE>Off</CODE> removes the job information as soon as each job is completed, canceled, or aborted. Numeric values preserve job information for the specified number of seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P>
1984
1985 <P>The default value is <CODE>On</CODE>.</P>
1986
1987 <BLOCKQUOTE><B>Note:</B>
1988
1989 <P>The <A HREF="#MaxJobs"><CODE>MaxJobs</CODE></A>, <A HREF="#MaxJobsPerPrinter"><CODE>MaxJobsPerPrinter</CODE></A>, and <A HREF="#MaxJobsPerUser"><CODE>MaxJobsPerUser</CODE></A> directives can cause job history to be discarded to make room for new jobs.</P>
1990
1991 </BLOCKQUOTE>
1992
1993
1994 <H2 CLASS="title"><A NAME="PreserveJobFiles">PreserveJobFiles</A></H2>
1995
1996 <H3>Examples</H3>
1997
1998 <PRE CLASS="command">
1999 PreserveJobFiles On
2000 PreserveJobFiles Off
2001 PreserveJobFiles 1w
2002 PreserveJobFiles 7d
2003 PreserveJobFiles 168h
2004 PreserveJobFiles 10080m
2005 PreserveJobFiles 604800
2006 </PRE>
2007
2008 <H3>Description</H3>
2009
2010 <P>The <CODE>PreserveJobFiles</CODE> directive controls whether the document files of completed, canceled, or aborted print jobs are retained. Jobs can be restarted (and reprinted) as desired until they are purged.</P>
2011
2012 <P>A value of <CODE>On</CODE> preserves job files until the administrator purges them with the <CODE>cancel</CODE> command. A value of <CODE>Off</CODE> removes the job files as soon as each job is completed, canceled, or aborted. Numeric values preserve job files for the specified number of seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P>
2013
2014 <P>The default value is <CODE>1d</CODE> (one day).</P>
2015
2016 <BLOCKQUOTE><B>Note:</B>
2017
2018 <P>The <A HREF="#MaxJobs"><CODE>MaxJobs</CODE></A>, <A HREF="#MaxJobsPerPrinter"><CODE>MaxJobsPerPrinter</CODE></A>, <A HREF="#MaxJobsPerUser"><CODE>MaxJobsPerUser</CODE></A>, and <A HREF="#PreserveJobHistory"><CODE>PreserveJobHistory</CODE></A> directives can cause job files to be discarded sooner than specified.</P>
2019
2020 </BLOCKQUOTE>
2021
2022
2023 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.21</SPAN><A NAME="ReloadTimeout">ReloadTimeout</A></H2>
2024
2025 <H3>Examples</H3>
2026
2027 <PRE CLASS="command">
2028 ReloadTimeout 0
2029 ReloadTimeout 30
2030 </PRE>
2031
2032 <H3>Description</H3>
2033
2034 <P>The <CODE>ReloadTimeout</CODE> directive specifies the number
2035 of seconds the scheduler will wait for active jobs to complete
2036 before doing a restart. The default is 30 seconds.</P>
2037
2038
2039 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="Require">Require</A></H2>
2040
2041 <H3>Examples</H3>
2042
2043 <PRE CLASS="command">
2044 &lt;Location /path&gt;
2045   ...
2046   Require group foo bar
2047   Require user john mary
2048   Require valid-user
2049   Require user @groupname
2050   Require user @SYSTEM
2051   Require user @OWNER
2052 &lt;/Location&gt;
2053 </PRE>
2054
2055 <H3>Description</H3>
2056
2057 <P>The <CODE>Require</CODE> directive specifies that
2058 authentication is required for the resource. The
2059 <CODE>group</CODE> keyword specifies that the authenticated user
2060 must be a member of one or more of the named groups that
2061 follow.</P>
2062
2063 <P>The <CODE>user</CODE> keyword specifies that the
2064 authenticated user must be one of the named users or groups that
2065 follow. Group names are specified using the "@" prefix.</P>
2066
2067 <P>The <CODE>valid-user</CODE> keyword specifies that any
2068 authenticated user may access the resource.</P>
2069
2070 <P>The default is to do no authentication. This directive must
2071 appear inside a <A HREF="#Location"><CODE>Location</CODE></A> or
2072 <A HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
2073
2074
2075 <H2 CLASS="title"><A NAME="RIPCache">RIPCache</A></H2>
2076
2077 <H3>Examples</H3>
2078
2079 <PRE CLASS="command">
2080 RIPCache 128m
2081 RIPCache 1g
2082 RIPCache 2048k
2083 </PRE>
2084
2085 <H3>Description</H3>
2086
2087 <P>The <CODE>RIPCache</CODE> directive sets the size of the
2088 memory cache used by Raster Image Processor ("RIP") filters such
2089 as <CODE>imagetoraster</CODE> and <CODE>pstoraster</CODE>. The
2090 size can be suffixed with a "k" for kilobytes, "m" for megabytes,
2091 or "g" for gigabytes. The default cache size is "128m", or 128
2092 megabytes.</P>
2093
2094
2095 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.16</SPAN><A NAME="RootCertDuration">RootCertDuration</A></H2>
2096
2097 <H3>Examples</H3>
2098
2099 <PRE CLASS="command">
2100 RootCertDuration 0
2101 RootCertDuration 1w
2102 RootCertDuration 1d
2103 RootCertDuration 1h
2104 RootCertDuration 5m
2105 RootCertDuration 300
2106 </PRE>
2107
2108 <H3>Description</H3>
2109
2110 <P>The <CODE>RootCertDuration</CODE> directive specifies the amount of time the <EM>root certificate</EM> remains valid in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix). The scheduler will generate a new certificate as needed when the given time interval has expired. If set to 0, the root certificate is generated only once on startup or on a restart.</P>
2111
2112 <P>The default is <CODE>5m</CODE> (five minutes).</P>
2113
2114
2115 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="Satisfy">Satisfy</A></H2>
2116
2117 <H3>Examples</H3>
2118
2119 <PRE CLASS="command">
2120 &lt;Location /path&gt;
2121   ...
2122   Satisfy all
2123   Satisfy any
2124 &lt;/Location&gt;
2125 </PRE>
2126
2127 <H3>Description</H3>
2128
2129 <P>The <CODE>Satisfy</CODE> directive specifies whether all
2130 conditions must be satisfied to allow access to the resource. If
2131 set to <CODE>all</CODE>, then all authentication and access
2132 control conditions must be satisfied to allow access.</P>
2133
2134 <P>Setting <CODE>Satisfy</CODE> to <CODE>any</CODE> allows a user
2135 to gain access if the authentication or access control
2136 requirements are satisfied. For example, you might require
2137 authentication for remote access, but allow local access without
2138 authentication.</P>
2139
2140 <P>The default is <CODE>all</CODE>. This directive must appear
2141 inside a <A HREF="#Location"><CODE>Location</CODE></A> or <A
2142 HREF="#Limit"><CODE>Limit</CODE></A> section.</P>
2143
2144
2145 <H2 CLASS="title"><A NAME="ServerAdmin">ServerAdmin</A></H2>
2146
2147 <H3>Examples</H3>
2148
2149 <PRE CLASS="command">
2150 ServerAdmin user@host
2151 ServerAdmin root@foo.bar.com
2152 </PRE>
2153
2154 <H3>Description</H3>
2155
2156 <P>The <CODE>ServerAdmin</CODE> directive identifies the email
2157 address for the administrator on the system. By default the
2158 administrator email address is <CODE>root@server</CODE>, where
2159 <CODE>server</CODE> is the <A
2160 HREF="#ServerName"><CODE>ServerName</CODE></A>.</P>
2161
2162
2163 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.3.10</SPAN><A NAME="ServerAlias">ServerAlias</A></H2>
2164
2165 <H3>Examples</H3>
2166
2167 <PRE CLASS="command">
2168 ServerAlias althost
2169 ServerAlias foo.example.com
2170 ServerAlias bar.example.com
2171 ServerAlias one.example.com two.example.com
2172 ServerAlias *
2173 </PRE>
2174
2175 <H3>Description</H3>
2176
2177 <P>The <CODE>ServerAlias</CODE> directive specifies alternate names that the server is known by. By default it contains a list of all aliases associated with the <A HREF="#ServerName"><CODE>ServerName</CODE></A>. The special name "*" can be used to allow any hostname when accessing CUPS via an external network interfaces.</P>
2178
2179 <BLOCKQUOTE><B>Note</B>
2180
2181 <P>The <CODE>ServerAlias</CODE> directive is used for HTTP Host header
2182 validation when clients connect to the scheduler from external interfaces.
2183 Using the special name "*" can expose your system to known browser-based
2184 DNS rebinding attacks, even when accessing sites through a firewall. If the
2185 auto-discovery of alternate names does not work, we recommend listing each
2186 alternate name with a ServerAlias directive instead of using "*".</P>
2187
2188 </BLOCKQUOTE>
2189
2190
2191 <H2 CLASS="title"><A NAME="ServerName">ServerName</A></H2>
2192
2193 <H3>Examples</H3>
2194
2195 <PRE CLASS="command">
2196 ServerName foo.example.com
2197 ServerName myserver.example.com
2198 </PRE>
2199
2200 <H3>Description</H3>
2201
2202 <P>The <CODE>ServerName</CODE> directive specifies the hostname
2203 that is reported to clients. By default the server name is the
2204 hostname.</P>
2205
2206
2207 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.21</SPAN><A NAME="ServerTokens">ServerTokens</A></H2>
2208
2209 <H3>Examples</H3>
2210
2211 <PRE CLASS="command">
2212 ServerTokens None
2213 ServerTokens ProductOnly
2214 ServerTokens Major
2215 ServerTokens Minor
2216 ServerTokens Minimal
2217 ServerTokens OS
2218 ServerTokens Full
2219 </PRE>
2220
2221 <H3>Description</H3>
2222
2223 <P>The <CODE>ServerTokens</CODE> directive specifies the
2224 information that is included in the <CODE>Server:</CODE> header
2225 of all HTTP responses. Table 4 lists the token name along with
2226 the text that is returned. The default is
2227 <CODE>Minimal</CODE>.</P>
2228
2229 <DIV CLASS="table"><TABLE SUMMARY="ServerToken Names and Values">
2230 <CAPTION>Table 4: <A NAME="TABLE4">ServerToken Names and Values</A></CAPTION>
2231 <THEAD>
2232 <TR>
2233         <TH>Name</TH>
2234         <TH>Value</TH>
2235 </TR>
2236 </THEAD>
2237 <TBODY>
2238 <TR>
2239         <TD>None</TD>
2240         <TD>No <CODE>Server:</CODE> header is returned</TD>
2241 </TR>
2242 <TR>
2243         <TD>ProductOnly</TD>
2244         <TD>"CUPS"</TD>
2245 </TR>
2246 <TR>
2247         <TD>Major</TD>
2248         <TD>"CUPS 1"</TD>
2249 </TR>
2250 <TR>
2251         <TD>Minor</TD>
2252         <TD>"CUPS 1.2"</TD>
2253 </TR>
2254 <TR>
2255         <TD>Minimal</TD>
2256         <TD>"CUPS 1.2.N" where N is the patch release</TD>
2257 </TR>
2258 <TR>
2259         <TD>OS</TD>
2260         <TD>"CUPS 1.2.N (UNAME)" where N is the patch release and
2261         UNAME is the output of the <B>uname(1)</B> command</TD>
2262 </TR>
2263 <TR>
2264         <TD>Full</TD>
2265         <TD>"CUPS 1.2.N (UNAME) IPP/1.1" where N is the patch
2266         release and UNAME is the output of the <B>uname(1)</B>
2267         command</TD>
2268 </TR>
2269 </TBODY>
2270 </TABLE></DIV>
2271
2272
2273 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="SetEnv">SetEnv</A></H2>
2274
2275 <H3>Examples</H3>
2276
2277 <PRE CLASS="command">
2278 SetEnv PATH /usr/lib/cups/filter:/bin:/usr/bin:/usr/local/bin
2279 SetEnv MY_ENV_VAR foo
2280 </PRE>
2281
2282 <H3>Description</H3>
2283
2284 <P>The <CODE>SetEnv</CODE> directive specifies an environment
2285 variable that should be passed to child processes.</P>
2286
2287
2288 <H2 CLASS="title"><A NAME="SSLListen">SSLListen</A></H2>
2289
2290 <H3>Examples</H3>
2291
2292 <PRE CLASS="command">
2293 SSLListen 127.0.0.1:443
2294 SSLListen 192.0.2.1:443
2295 </PRE>
2296
2297 <H3>Description</H3>
2298
2299 <P>The <CODE>SSLListen</CODE> directive specifies a network
2300 address and port to listen for secure connections. Multiple
2301 <CODE>SSLListen</CODE> directives can be provided to listen on
2302 multiple addresses.</P>
2303
2304 <P>The <CODE>SSLListen</CODE> directive is similar to the <A
2305 HREF="#SSLPort"><CODE>SSLPort</CODE></A> directive but allows you
2306 to restrict access to specific interfaces or networks.</P>
2307
2308
2309 <H2 CLASS="title"><A NAME="SSLOptions">SSLOptions</A></H2>
2310
2311 <H3>Examples</H3>
2312
2313 <PRE CLASS="command">
2314 SSLOptions None
2315 SSLOptions NoEmptyFragments
2316 </PRE>
2317
2318 <H3>Description</H3>
2319
2320 <P>The <CODE>SSLOptions</CODE> directive specifies additional SSL/TLS
2321 protocol options to use for encrypted connected. Currently only two
2322 options are supported - <code>None</code> (the default) for the most
2323 secure mode and <code>NoEmptyFragments</code> to allow CUPS to work with
2324 Microsoft Windows with the FIPS conformance mode enabled.</p>
2325
2326
2327 <H2 CLASS="title"><A NAME="SSLPort">SSLPort</A></H2>
2328
2329 <H3>Examples</H3>
2330
2331 <PRE CLASS="command">
2332 SSLPort 443
2333 </PRE>
2334
2335 <H3>Description</H3>
2336
2337 <P>The <CODE>SSLPort</CODE> directive specifies a port to listen
2338 on for secure connections. Multiple <CODE>SSLPort</CODE> lines
2339 can be specified to listen on multiple ports.</P>
2340
2341
2342 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.6</SPAN><A NAME="StrictConformance">StrictConformance</A></H2>
2343
2344 <H3>Examples</H3>
2345
2346 <PRE CLASS="command">
2347 StrictConformance No
2348 StrictConformance Yes
2349 </PRE>
2350
2351 <H3>Description</H3>
2352
2353 <P>The <CODE>StrictConformance</CODE> directive specifies whether the scheduler
2354 requires strict IPP conformance for client requests, for example to not allow
2355 document attributes in a Create-Job request. The default is
2356 <code>No</code>.</P>
2357
2358
2359 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.5</SPAN><A NAME="SubscriptionPrivateAccess">SubscriptionPrivateAccess</A></H2>
2360
2361 <H3>Examples</H3>
2362
2363 <PRE CLASS="command">
2364 SubscriptionPrivateAccess all
2365 SubscriptionPrivateAccess default
2366 SubscriptionPrivateAccess {user|@group|@ACL|@OWNER|@SYSTEM}+
2367 </PRE>
2368
2369 <H3>Description</H3>
2370
2371 <P>The <CODE>SubscriptionPrivateAccess</CODE> directive specifies the access list for a
2372 subscription's private values. The "default" access list is "@OWNER @SYSTEM".
2373 "@ACL" maps to the printer's requesting-user-name-allowed or
2374 requesting-user-name-denied values.</P>
2375
2376 <P>The <CODE>SubscriptionPrivateAccess</CODE> directive must appear inside a <A
2377 HREF="#Policy"><CODE>Policy</CODE></A> section.</P>
2378
2379
2380 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.5</SPAN><A NAME="SubscriptionPrivateValues">SubscriptionPrivateValues</A></H2>
2381
2382 <H3>Examples</H3>
2383
2384 <PRE CLASS="command">
2385 SubscriptionPrivateValues all
2386 SubscriptionPrivateValues default
2387 SubscriptionPrivateValues none
2388 SubscriptionPrivateValues attribute-name-1 [ ... attribute-name-N ]
2389 </PRE>
2390
2391 <H3>Description</H3>
2392
2393 <P>The <CODE>SubscriptionPrivateValues</CODE> directive specifies the list of
2394 subscription values to make private. The "default" values are "notify-events",
2395 "notify-pull-method", "notify-recipient-uri", "notify-subscriber-user-name", and
2396 "notify-user-data".</P>
2397
2398 <P>The <CODE>SubscriptionPrivateValues</CODE> directive must appear inside a <A
2399 HREF="#Policy"><CODE>Policy</CODE></A> section.</P>
2400
2401
2402 <H2 CLASS="title"><A NAME="Timeout">Timeout</A></H2>
2403
2404 <H3>Examples</H3>
2405
2406 <PRE CLASS="command">
2407 Timeout 1w
2408 Timeout 1d
2409 Timeout 1h
2410 Timeout 5m
2411 Timeout 300
2412 </PRE>
2413
2414 <H3>Description</H3>
2415
2416 <P>The <CODE>Timeout</CODE> directive controls the amount of time
2417 to wait before an active HTTP or IPP request times out in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P>
2418
2419 <P>The default timeout is <CODE>5m</CODE> (five minutes).</P>
2420
2421
2422 <H2 CLASS="title"><SPAN CLASS="INFO">CUPS 1.5</SPAN><A NAME="WebInterface">WebInterface</A></H2>
2423
2424 <H3>Examples</H3>
2425
2426 <PRE CLASS="command">
2427 WebInterface yes
2428 WebInterface no
2429 </PRE>
2430
2431 <H3>Description</H3>
2432
2433 <P>The <CODE>WebInterface</CODE> directive specifies whether the web interface is enabled. The default value is <CODE>@CUPS_WEBIF@</CODE>.</P>
2434
2435 </BODY>
2436 </HTML>