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"><A NAME="ServerBin">ServerBin</A></H2>
 358
 359 <H3>Examples</H3>
 360
 361 <PRE CLASS="command">
 362 ServerBin /usr/lib/cups
 363 ServerBin /foo/bar/lib/cups
 364 </PRE>
 365
 366 <H3>Description</H3>
 367
 368 <P>The <CODE>ServerBin</CODE> directive sets the directory for
 369 server-run executables. If an absolute path is not provided then
 370 it is assumed to be relative to the <A
 371 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
 372 default executable directory is <VAR>/usr/lib/cups</VAR>,
 373 <VAR>/usr/lib32/cups</VAR>, or <VAR>/usr/libexec/cups</VAR>
 374 depending on the operating system.</P>
 375
 376
 377 <H2 CLASS="title"><A NAME="ServerCertificate">ServerCertificate</A></H2>
 378
 379 <H3>Examples</H3>
 380
 381 <PRE CLASS="command">
 382 ServerCertificate /etc/cups/ssl/server.crt
 383 </PRE>
 384
 385 <H3>Description</H3>
 386
 387 <P>The <CODE>ServerCertificate</CODE> directive specifies the
 388 location of the SSL certificate file used by the server when
 389 negotiating encrypted connections. The certificate must not be
 390 encrypted (password protected) since the scheduler normally runs
 391 in the background and will be unable to ask for a password.</P>
 392
 393 <P>The default certificate file is
 394 <VAR>/etc/cups/ssl/server.crt</VAR>.</P>
 395
 396
 397 <H2 CLASS="title"><A NAME="ServerKey">ServerKey</A></H2>
 398
 399 <H3>Examples</H3>
 400
 401 <PRE CLASS="command">
 402 ServerKey /etc/cups/ssl/server.key
 403 </PRE>
 404
 405 <H3>Description</H3>
 406
 407 <P>The <CODE>ServerKey</CODE> directive specifies the location of
 408 the SSL private key file used by the server when negotiating
 409 encrypted connections.</P>
 410
 411 <P>The default key file is
 412 <VAR>/etc/cups/ssl/server.crt</VAR>.</P>
 413
 414
 415 <H2 CLASS="title"><A NAME="ServerRoot">ServerRoot</A></H2>
 416
 417 <H3>Examples</H3>
 418
 419 <PRE CLASS="command">
 420 ServerRoot /etc/cups
 421 ServerRoot /foo/bar/cups
 422 </PRE>
 423
 424 <H3>Description</H3>
 425
 426 <P>The <CODE>ServerRoot</CODE> directive specifies the absolute
 427 path to the server configuration and state files. It is also used
 428 to resolve relative paths in the <VAR>cupsd.conf</VAR> file. The
 429 default server directory is <VAR>/etc/cups</VAR>.</P>
 430
 431
 432 <H2 CLASS="title"><A NAME="SystemGroup">SystemGroup</A></H2>
 433
 434 <H3>Examples</H3>
 435
 436 <PRE CLASS="command">
 437 SystemGroup lpadmin
 438 SystemGroup sys
 439 SystemGroup system
 440 SystemGroup root
 441 SystemGroup root lpadmin
 442 </PRE>
 443
 444 <H3>Description</H3>
 445
 446 <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>
 447
 448
 449 <H2 CLASS="title"><A NAME="TempDir">TempDir</A></H2>
 450
 451 <H3>Examples</H3>
 452
 453 <PRE CLASS="command">
 454 TempDir /var/tmp
 455 TempDir /foo/bar/tmp
 456 </PRE>
 457
 458 <H3>Description</H3>
 459
 460 <P>The <CODE>TempDir</CODE> directive specifies an absolute path
 461 for the directory to use for temporary files. The default
 462 directory is <VAR>/var/spool/cups/tmp</VAR>.</P>
 463
 464 <P>Temporary directories must be world-writable and should have
 465 the "sticky" permission bit enabled so that other users cannot
 466 delete filter temporary files. The following commands will create
 467 an appropriate temporary directory called
 468 <VAR>/foo/bar/tmp</VAR>:</P>
 469
 470 <PRE CLASS="command">
 471 <KBD>mkdir /foo/bar/tmp</KBD>
 472 <KBD>chmod a+rwxt /foo/bar/tmp</KBD>
 473 </PRE>
 474
 475 <BLOCKQUOTE><B>Note:</B>
 476
 477 <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>
 478
 479
 480 <H2 CLASS="title"><A NAME="User">User</A></H2>
 481
 482 <H3>Examples</H3>
 483
 484 <PRE CLASS="command">
 485 User lp
 486 User guest
 487 </PRE>
 488
 489 <H3>Description</H3>
 490
 491 <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>
 492
 493 <BLOCKQUOTE><B>Note:</B>
 494
 495 <P>You may not use user <CODE>root</CODE>, as that would expose
 496 the system to unacceptable security risks. The scheduler will
 497 automatically choose user <CODE>nobody</CODE> if you specify a
 498 user whose ID is 0.</P>
 499
 500 </BLOCKQUOTE>
 501
 502
 503 </BODY>
 504 </HTML>