doc/help/ref-cups-files-conf.html.in

   1 <HTML>
   2 <!-- SECTION: References -->
   3 <HEAD>
   4         <TITLE>cups-files.conf</TITLE>
   5         <LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
   6 </HEAD>
   7 <BODY>
   8
   9 <H1 CLASS="title">cups-files.conf</H1>
  10
  11 <P>The <VAR>/etc/cups/cups-files.conf</VAR> file contains configuration <I>directives</I> that control the files, directories. users. and groups that are used by the CUPS scheduler, <CODE>cupsd(8)</CODE>. Each directive is listed on a line by itself followed by its value. Comments are introduced using the number sign ("#") character at the beginning of a line.</P>
  12
  13 <H2 CLASS="title"><A NAME="AccessLog">AccessLog</A></H2>
  14
  15 <H3>Examples</H3>
  16
  17 <PRE CLASS="command">
  18 AccessLog /var/log/cups/access_log
  19 AccessLog /var/log/cups/access_log-%s
  20 AccessLog syslog
  21 </PRE>
  22
  23 <H3>Description</H3>
  24
  25 <P>The <CODE>AccessLog</CODE> directive sets the name of the
  26 access log file. If the filename is not absolute then it is
  27 assumed to be relative to the <A
  28 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
  29 access log file is stored in "common log format" and can be used
  30 by any web access reporting tool to generate a report on CUPS
  31 server activity.</P>
  32
  33 <P>The server name can be included in the filename by using
  34 <CODE>%s</CODE> in the name.</P>
  35
  36 <P>The special name "syslog" can be used to send the access
  37 information to the system log instead of a plain file.</P>
  38
  39 <P>The default access log file is
  40 <VAR>/var/log/access_log</VAR>.</P>
  41
  42
  43 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.15</SPAN><A NAME="ConfigFilePerm">ConfigFilePerm</A></H2>
  44
  45 <H3>Examples</H3>
  46
  47 <PRE CLASS="command">
  48 ConfigFilePerm 0644
  49 ConfigFilePerm 0640
  50 </PRE>
  51
  52 <H3>Description</H3>
  53
  54 <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 644 on OS X and 640 on all other operating systems.</P>
  55
  56 <BLOCKQUOTE><B>Note:</B>
  57
  58 <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>
  59
  60 </BLOCKQUOTE>
  61
  62
  63 <H2 CLASS="title"><A NAME="DataDir">DataDir</A></H2>
  64
  65 <H3>Examples</H3>
  66
  67 <PRE CLASS="command">
  68 DataDir /usr/share/cups
  69 </PRE>
  70
  71 <H3>Description</H3>
  72
  73 <P>The <CODE>DataDir</CODE> directive sets the directory to use
  74 for data files.</P>
  75
  76
  77 <H2 CLASS="title"><A NAME="DocumentRoot">DocumentRoot</A></H2>
  78
  79 <H3>Examples</H3>
  80
  81 <PRE CLASS="command">
  82 DocumentRoot /usr/share/doc/cups
  83 DocumentRoot /foo/bar/doc/cups
  84 </PRE>
  85
  86 <H3>Description</H3>
  87
  88 <P>The <CODE>DocumentRoot</CODE> directive specifies the location
  89 of web content for the HTTP server in CUPS. If an absolute path
  90 is not specified then it is assumed to be relative to the <A
  91 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
  92 default directory is <VAR>/usr/share/doc/cups</VAR>.</P>
  93
  94 <P>Documents are first looked up in a sub-directory for the
  95 primary language requested by the client (e.g.
  96 <VAR>/usr/share/doc/cups/fr/...</VAR>) and then directly under
  97 the <CODE>DocumentRoot</CODE> directory (e.g.
  98 <VAR>/usr/share/doc/cups/...</VAR>), so it is possible to
  99 localize the web content by providing subdirectories for each
 100 language needed.</P>
 101
 102
 103 <H2 CLASS="title"><A NAME="ErrorLog">ErrorLog</A></H2>
 104
 105 <H3>Examples</H3>
 106
 107 <PRE CLASS="command">
 108 ErrorLog /var/log/cups/error_log
 109 ErrorLog /var/log/cups/error_log-%s
 110 ErrorLog syslog
 111 </PRE>
 112
 113 <H3>Description</H3>
 114
 115 <P>The <CODE>ErrorLog</CODE> directive sets the name of the error
 116 log file. If the filename is not absolute then it is assumed to
 117 be relative to the <A
 118 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
 119 default error log file is <VAR>/var/log/cups/error_log</VAR>.</P>
 120
 121 <P>The server name can be included in the filename by using
 122 <CODE>%s</CODE> in the name.</P>
 123
 124 <P>The special name "syslog" can be used to send the error
 125 information to the system log instead of a plain file.</P>
 126
 127
 128 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/OS X 10.6</SPAN><A NAME="FatalErrors">FatalErrors</A></H2>
 129
 130 <H3>Examples</H3>
 131
 132 <PRE CLASS="command">
 133 FatalErrors none
 134 FatalErrors all
 135 FatalErrors browse
 136 FatalErrors config
 137 FatalErrors listen
 138 FatalErrors log
 139 FatalErrors permissions
 140 FatalErrors all -permissions
 141 FatalErrors config permissions log
 142 </PRE>
 143
 144 <H3>Description</H3>
 145
 146 <P>The <CODE>FatalErrors</CODE> directive determines whether certain kinds of
 147 errors are fatal. The following kinds of errors are currently recognized:</P>
 148
 149 <UL>
 150
 151         <LI><CODE>none</CODE> - No errors are fatal</LI>
 152
 153         <LI><CODE>all</CODE> - All of the errors below are fatal</LI>
 154
 155         <LI><CODE>browse</CODE> - Browsing initialization errors are fatal,
 156         for example failed binding to the CUPS browse port or failed connections
 157         to LDAP servers</LI>
 158
 159         <LI><CODE>config</CODE> - Configuration file syntax errors are
 160         fatal</LI>
 161
 162         <LI><CODE>listen</CODE> - Listen or Port errors are fatal, except for
 163         IPv6 failures on the loopback or "any" addresses</LI>
 164
 165         <LI><CODE>log</CODE> - Log file creation or write errors are fatal</LI>
 166
 167         <LI><CODE>permissions</CODE> - Bad startup file permissions are
 168         fatal, for example shared SSL certificate and key files with world-
 169         read permissions</LI>
 170
 171 </UL>
 172
 173 <P>Multiple errors can be listed, and the form "-kind" can be used with
 174 <CODE>all</CODE> to remove specific kinds of errors. The default setting is
 175 <CODE>config</CODE>.</P>
 176
 177
 178 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.18</SPAN><A NAME="FileDevice">FileDevice</A></H2>
 179
 180 <H3>Examples</H3>
 181
 182 <PRE CLASS="command">
 183 FileDevice Yes
 184 FileDevice No
 185 </PRE>
 186
 187 <H3>Description</H3>
 188
 189 <P>The <CODE>FileDevice</CODE> directive determines whether the
 190 scheduler allows new printers to be added using device URIs of
 191 the form <CODE>file:/filename</CODE>. File devices are most often
 192 used to test new printer drivers and do not support raw file
 193 printing.</P>
 194
 195 <P>The default setting is <CODE>No</CODE>.</P>
 196
 197 <BLOCKQUOTE><B>Note:</B>
 198
 199 <P>File devices are managed by the scheduler. Since the
 200 scheduler normally runs as the root user, file devices
 201 can be used to overwrite system files and potentially
 202 gain unauthorized access to the system. If you must
 203 create printers using file devices, we recommend that
 204 you set the <CODE>FileDevice</CODE> directive to
 205 <CODE>Yes</CODE> for only as long as you need to add the
 206 printers to the system, and then reset the directive to
 207 <CODE>No</CODE>.</P>
 208
 209 </BLOCKQUOTE>
 210
 211
 212 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.3</SPAN><A NAME="FontPath">FontPath</A></H2>
 213
 214 <H3>Examples</H3>
 215
 216 <PRE CLASS="command">
 217 FontPath /foo/bar/fonts
 218 FontPath /usr/share/cups/fonts:/foo/bar/fonts
 219 </PRE>
 220
 221 <H3>Description</H3>
 222
 223 <P>The <CODE>FontPath</CODE> directive specifies the font path to
 224 use when searching for fonts. The default font path is
 225 <CODE>/usr/share/cups/fonts</CODE>.</P>
 226
 227
 228 <H2 CLASS="title"><A NAME="Group">Group</A></H2>
 229
 230 <H3>Examples</H3>
 231
 232 <PRE CLASS="command">
 233 Group lp
 234 Group nobody
 235 </PRE>
 236
 237 <H3>Description</H3>
 238
 239 <P>The <CODE>Group</CODE> directive specifies the UNIX group that
 240 filter and CGI programs run as. The default group is
 241 system-specific but is usually <CODE>lp</CODE> or
 242 <CODE>nobody</CODE>.</P>
 243
 244
 245 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.15</SPAN><A NAME="LogFilePerm">LogFilePerm</A></H2>
 246
 247 <H3>Examples</H3>
 248
 249 <PRE CLASS="command">
 250 LogFilePerm 0644
 251 LogFilePerm 0600
 252 </PRE>
 253
 254 <H3>Description</H3>
 255
 256 <P>The <CODE>LogFilePerm</CODE> directive specifies the
 257 permissions to use when writing log files. The default
 258 is 644.</P>
 259
 260
 261 <H2 CLASS="title"><A NAME="PageLog">PageLog</A></H2>
 262
 263 <H3>Examples</H3>
 264
 265 <PRE CLASS="command">
 266 PageLog /var/log/cups/page_log
 267 PageLog /var/log/cups/page_log-%s
 268 PageLog syslog
 269 </PRE>
 270
 271 <H3>Description</H3>
 272
 273 <P>The <CODE>PageLog</CODE> directive sets the name of the page
 274 log file. If the filename is not absolute then it is assumed to
 275 be relative to the <A
 276 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
 277 default page log file is <VAR>/var/log/cups/page_log</VAR>.</P>
 278
 279 <P>The server name can be included in the filename by using
 280 <CODE>%s</CODE> in the name.</P>
 281
 282 <P>The special name "syslog" can be used to send the page
 283 information to the system log instead of a plain file.</P>
 284
 285
 286 <H2 CLASS="title"><A NAME="Printcap">Printcap</A></H2>
 287
 288 <H3>Examples</H3>
 289
 290 <PRE CLASS="command">
 291 Printcap
 292 Printcap /etc/printcap
 293 Printcap /etc/printers.conf
 294 Printcap /Library/Preferences/org.cups.printers.plist
 295 </PRE>
 296
 297 <H3>Description</H3>
 298
 299 <P>The <CODE>Printcap</CODE> directive controls whether or not a printcap file is automatically generated and updated with a list of available printers. If specified with no value, then no printcap file will be generated. The default is to generate a file named <VAR>/Library/Preferences.org.cups.printers.plist</VAR> on OS X and <VAR>/etc/printcap</VAR> on all other operating systems.</P>
 300
 301 <P>When a filename is specified (e.g. <VAR>/etc/printcap</VAR>), the printcap file is written whenever a printer is added or removed. The printcap file can then be used by applications that are hardcoded to look at the printcap file for the available printers.</P>
 302
 303
 304 <H2 CLASS="title"><A NAME="PrintcapFormat">PrintcapFormat</A></H2>
 305
 306 <H3>Examples</H3>
 307
 308 <PRE CLASS="command">
 309 PrintcapFormat BSD
 310 PrintcapFormat Solaris
 311 PrintcapFormat plist
 312 </PRE>
 313
 314 <H3>Description</H3>
 315
 316 <P>The <CODE>PrintcapFormat</CODE> directive controls the output format of the
 317 printcap file. The default is to generate the plist format on OS X, the
 318 Solaris format on Solaris, and the BSD format on other operating systems.</P>
 319
 320
 321 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.3</SPAN><A NAME="RemoteRoot">RemoteRoot</A></H2>
 322
 323 <H3>Examples</H3>
 324
 325 <PRE CLASS="command">
 326 RemoteRoot remroot
 327 RemoteRoot root
 328 </PRE>
 329
 330 <H3>Description</H3>
 331
 332 <P>The <CODE>RemoteRoot</CODE> directive sets the username for
 333 unauthenticated root requests from remote hosts. The default
 334 username is <VAR>remroot</VAR>. Setting <CODE>RemoteRoot</CODE>
 335 to <VAR>root</VAR> effectively disables this security
 336 mechanism.</P>
 337
 338
 339 <H2 CLASS="title"><A NAME="RequestRoot">RequestRoot</A></H2>
 340
 341 <H3>Examples</H3>
 342
 343 <PRE CLASS="command">
 344 RequestRoot /var/spool/cups
 345 RequestRoot /foo/bar/spool/cups
 346 </PRE>
 347
 348 <H3>Description</H3>
 349
 350 <P>The <CODE>RequestRoot</CODE> directive sets the directory for
 351 incoming IPP requests and HTML forms. If an absolute path is not
 352 provided then it is assumed to be relative to the <A
 353 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
 354 default request directory is <VAR>/var/spool/cups</VAR>.</P>
 355
 356
 357 <H2 CLASS="title"><SPAN CLASS="info">CUPS 2.0</SPAN><A NAME="Sandboxing">Sandboxing</A> (OS X Only)</H2>
 358
 359 <H3>Examples</H3>
 360
 361 <PRE CLASS="command">
 362 Sandboxing off
 363 Sandboxing relaxed
 364 Sandboxing strict
 365 </PRE>
 366
 367 <H3>Description</H3>
 368
 369 <P>The <CODE>Sandboxing</CODE> directive sets the default level of security sandboxing that is applied to print filters, backend, and other child processes. The default value is <CODE>strict</CODE>. Sandboxing is currently only supported on OS X.</P>
 370
 371
 372 <H2 CLASS="title"><A NAME="ServerBin">ServerBin</A></H2>
 373
 374 <H3>Examples</H3>
 375
 376 <PRE CLASS="command">
 377 ServerBin /usr/lib/cups
 378 ServerBin /foo/bar/lib/cups
 379 </PRE>
 380
 381 <H3>Description</H3>
 382
 383 <P>The <CODE>ServerBin</CODE> directive sets the directory for
 384 server-run executables. If an absolute path is not provided then
 385 it is assumed to be relative to the <A
 386 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
 387 default executable directory is <VAR>/usr/lib/cups</VAR>,
 388 <VAR>/usr/lib32/cups</VAR>, or <VAR>/usr/libexec/cups</VAR>
 389 depending on the operating system.</P>
 390
 391
 392 <H2 CLASS="title"><SPAN CLASS="info">CUPS 2.0</SPAN><A NAME="ServerKeychain">ServerKeychain</A></H2>
 393
 394 <H3>Examples</H3>
 395
 396 <PRE CLASS="command">
 397 ServerKeychain /etc/cups/ssl
 398 ServerKeychain /Library/Keychains/system.keychain
 399 </PRE>
 400
 401 <H3>Description</H3>
 402
 403 <P>The <CODE>ServerKeychain</CODE> directive specifies the location of TLS certificates and private keys used when negotiating encrypted connections.</P>
 404
 405 <P>The default keychain is system-specific.</P>
 406
 407
 408 <H2 CLASS="title"><A NAME="ServerRoot">ServerRoot</A></H2>
 409
 410 <H3>Examples</H3>
 411
 412 <PRE CLASS="command">
 413 ServerRoot /etc/cups
 414 ServerRoot /foo/bar/cups
 415 </PRE>
 416
 417 <H3>Description</H3>
 418
 419 <P>The <CODE>ServerRoot</CODE> directive specifies the absolute
 420 path to the server configuration and state files. It is also used
 421 to resolve relative paths in the <VAR>cupsd.conf</VAR> file. The
 422 default server directory is <VAR>/etc/cups</VAR>.</P>
 423
 424
 425 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.6.4</SPAN><A NAME="SyncOnClose">SyncOnClose</A></H2>
 426
 427 <H3>Examples</H3>
 428
 429 <PRE CLASS="command">
 430 SyncOnClose No
 431 SyncOnClose Yes
 432 </PRE>
 433
 434 <H3>Description</H3>
 435
 436 <P>The <CODE>SyncOnClose</CODE> directive determines whether the scheduler
 437 flushes changes to configuration and state files to disk. The default is
 438 <CODE>No</CODE> which relies on the operating system to schedule a suitable
 439 time to write changes to disk.</P>
 440
 441 <BLOCKQUOTE><B>Note:</B>
 442
 443 <P>Setting <CODE>SyncOnClose</CODE> to <CODE>Yes</CODE> makes the scheduler use the <CODE>fsync(2)</CODE> system call to write all changes to disk, however the drive or network file system server may still delay writing data to disk. Do not depend on this functionality to prevent data loss in the event of unexpected hardware failure.</P>
 444
 445 <P>Enabling <CODE>SyncOnClose</CODE> may also cause the scheduler to periodically become unresponsive while it waits for changes to be written.</P>
 446
 447 </BLOCKQUOTE>
 448
 449
 450 <H2 CLASS="title"><A NAME="SystemGroup">SystemGroup</A></H2>
 451
 452 <H3>Examples</H3>
 453
 454 <PRE CLASS="command">
 455 SystemGroup lpadmin
 456 SystemGroup sys
 457 SystemGroup system
 458 SystemGroup root
 459 SystemGroup root lpadmin
 460 </PRE>
 461
 462 <H3>Description</H3>
 463
 464 <P>The <CODE>SystemGroup</CODE> directive specifies the system administration group for <CODE>System</CODE> authentication. Multiple groups can be listed, separated with spaces. The default group list is <CODE>admin</CODE> on OS X and <CODE>lpadmin</CODE>, <CODE>root</CODE>, <CODE>sys</CODE>, and/or <CODE>system</CODE> on other operating systems.</P>
 465
 466
 467 <H2 CLASS="title"><A NAME="TempDir">TempDir</A></H2>
 468
 469 <H3>Examples</H3>
 470
 471 <PRE CLASS="command">
 472 TempDir /var/tmp
 473 TempDir /foo/bar/tmp
 474 </PRE>
 475
 476 <H3>Description</H3>
 477
 478 <P>The <CODE>TempDir</CODE> directive specifies an absolute path
 479 for the directory to use for temporary files. The default
 480 directory is <VAR>/var/spool/cups/tmp</VAR>.</P>
 481
 482 <P>Temporary directories must be world-writable and should have
 483 the "sticky" permission bit enabled so that other users cannot
 484 delete filter temporary files. The following commands will create
 485 an appropriate temporary directory called
 486 <VAR>/foo/bar/tmp</VAR>:</P>
 487
 488 <PRE CLASS="command">
 489 <KBD>mkdir /foo/bar/tmp</KBD>
 490 <KBD>chmod a+rwxt /foo/bar/tmp</KBD>
 491 </PRE>
 492
 493 <BLOCKQUOTE><B>Note:</B>
 494
 495 <P>The <CODE>TempDir</CODE> cannot be pointed at a standard system temporary directory such as <VAR>/tmp</VAR> or <VAR>/var/tmp</VAR> for security reasons.</P></BLOCKQUOTE>
 496
 497
 498 <H2 CLASS="title"><A NAME="User">User</A></H2>
 499
 500 <H3>Examples</H3>
 501
 502 <PRE CLASS="command">
 503 User lp
 504 User guest
 505 </PRE>
 506
 507 <H3>Description</H3>
 508
 509 <P>The <CODE>User</CODE> directive specifies the UNIX user that filter and CGI programs run as. The default user is <CODE>_lp</CODE>, <CODE>lp</CODE>, or <CODE>nobody</CODE> (whichever is found first).</P>
 510
 511 <BLOCKQUOTE><B>Note:</B>
 512
 513 <P>You may not use user <CODE>root</CODE>, as that would expose
 514 the system to unacceptable security risks. The scheduler will
 515 automatically choose user <CODE>nobody</CODE> if you specify a
 516 user whose ID is 0.</P>
 517
 518 </BLOCKQUOTE>
 519
 520
 521 </BODY>
 522 </HTML>