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>@CUPS_LOGDIR@/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 @CUPS_CONFIG_FILE_PERM@.</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>@CUPS_DOCROOT@</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>@CUPS_DOCROOT@/fr/...</VAR>) and then directly under
  97 the <CODE>DocumentRoot</CODE> directory (e.g.
  98 <VAR>@CUPS_DOCROOT@/...</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>@CUPS_LOGDIR@/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>@CUPS_FATAL_ERRORS@</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 @CUPS_LOG_FILE_PERM@.</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>@CUPS_LOGDIR@/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
 300 printcap file is automatically generated and updated with a list
 301 of available printers. If specified with no value, then no
 302 printcap file will be generated. The default is to generate a
 303 file named <VAR>@CUPS_DEFAULT_PRINTCAP@</VAR>.</P>
 304
 305 <P>When a filename is specified (e.g. <VAR>@CUPS_DEFAULT_PRINTCAP@</VAR>),
 306 the printcap file is written whenever a printer is added or
 307 removed. The printcap file can then be used by applications that
 308 are hardcoded to look at the printcap file for the available
 309 printers.</P>
 310
 311
 312 <H2 CLASS="title"><A NAME="PrintcapFormat">PrintcapFormat</A></H2>
 313
 314 <H3>Examples</H3>
 315
 316 <PRE CLASS="command">
 317 PrintcapFormat BSD
 318 PrintcapFormat Solaris
 319 PrintcapFormat plist
 320 </PRE>
 321
 322 <H3>Description</H3>
 323
 324 <P>The <CODE>PrintcapFormat</CODE> directive controls the output format of the
 325 printcap file. The default is to generate the plist format on OS X, the
 326 Solaris format on Solaris, and the BSD format on other operating systems.</P>
 327
 328
 329 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.3</SPAN><A NAME="RemoteRoot">RemoteRoot</A></H2>
 330
 331 <H3>Examples</H3>
 332
 333 <PRE CLASS="command">
 334 RemoteRoot remroot
 335 RemoteRoot root
 336 </PRE>
 337
 338 <H3>Description</H3>
 339
 340 <P>The <CODE>RemoteRoot</CODE> directive sets the username for
 341 unauthenticated root requests from remote hosts. The default
 342 username is <VAR>remroot</VAR>. Setting <CODE>RemoteRoot</CODE>
 343 to <VAR>root</VAR> effectively disables this security
 344 mechanism.</P>
 345
 346
 347 <H2 CLASS="title"><A NAME="RequestRoot">RequestRoot</A></H2>
 348
 349 <H3>Examples</H3>
 350
 351 <PRE CLASS="command">
 352 RequestRoot /var/spool/cups
 353 RequestRoot /foo/bar/spool/cups
 354 </PRE>
 355
 356 <H3>Description</H3>
 357
 358 <P>The <CODE>RequestRoot</CODE> directive sets the directory for
 359 incoming IPP requests and HTML forms. If an absolute path is not
 360 provided then it is assumed to be relative to the <A
 361 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
 362 default request directory is <VAR>@CUPS_REQUESTS@</VAR>.</P>
 363
 364
 365 <H2 CLASS="title"><A NAME="ServerBin">ServerBin</A></H2>
 366
 367 <H3>Examples</H3>
 368
 369 <PRE CLASS="command">
 370 ServerBin /usr/lib/cups
 371 ServerBin /foo/bar/lib/cups
 372 </PRE>
 373
 374 <H3>Description</H3>
 375
 376 <P>The <CODE>ServerBin</CODE> directive sets the directory for
 377 server-run executables. If an absolute path is not provided then
 378 it is assumed to be relative to the <A
 379 HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
 380 default executable directory is <VAR>/usr/lib/cups</VAR>,
 381 <VAR>/usr/lib32/cups</VAR>, or <VAR>/usr/libexec/cups</VAR>
 382 depending on the operating system.</P>
 383
 384
 385 <H2 CLASS="title"><A NAME="ServerCertificate">ServerCertificate</A></H2>
 386
 387 <H3>Examples</H3>
 388
 389 <PRE CLASS="command">
 390 ServerCertificate /etc/cups/ssl/server.crt
 391 </PRE>
 392
 393 <H3>Description</H3>
 394
 395 <P>The <CODE>ServerCertificate</CODE> directive specifies the
 396 location of the SSL certificate file used by the server when
 397 negotiating encrypted connections. The certificate must not be
 398 encrypted (password protected) since the scheduler normally runs
 399 in the background and will be unable to ask for a password.</P>
 400
 401 <P>The default certificate file is
 402 <VAR>/etc/cups/ssl/server.crt</VAR>.</P>
 403
 404
 405 <H2 CLASS="title"><A NAME="ServerKey">ServerKey</A></H2>
 406
 407 <H3>Examples</H3>
 408
 409 <PRE CLASS="command">
 410 ServerKey /etc/cups/ssl/server.key
 411 </PRE>
 412
 413 <H3>Description</H3>
 414
 415 <P>The <CODE>ServerKey</CODE> directive specifies the location of
 416 the SSL private key file used by the server when negotiating
 417 encrypted connections.</P>
 418
 419 <P>The default key file is
 420 <VAR>/etc/cups/ssl/server.crt</VAR>.</P>
 421
 422
 423 <H2 CLASS="title"><A NAME="ServerRoot">ServerRoot</A></H2>
 424
 425 <H3>Examples</H3>
 426
 427 <PRE CLASS="command">
 428 ServerRoot /etc/cups
 429 ServerRoot /foo/bar/cups
 430 </PRE>
 431
 432 <H3>Description</H3>
 433
 434 <P>The <CODE>ServerRoot</CODE> directive specifies the absolute
 435 path to the server configuration and state files. It is also used
 436 to resolve relative paths in the <VAR>cupsd.conf</VAR> file. The
 437 default server directory is <VAR>/etc/cups</VAR>.</P>
 438
 439
 440 <H2 CLASS="title"><A NAME="SystemGroup">SystemGroup</A></H2>
 441
 442 <H3>Examples</H3>
 443
 444 <PRE CLASS="command">
 445 SystemGroup lpadmin
 446 SystemGroup sys
 447 SystemGroup system
 448 SystemGroup root
 449 SystemGroup root lpadmin
 450 </PRE>
 451
 452 <H3>Description</H3>
 453
 454 <P>The <CODE>SystemGroup</CODE> directive specifies the system
 455 administration group for <CODE>System</CODE> authentication.
 456 Multiple groups can be listed, separated with spaces. The default
 457 group list is <CODE>@CUPS_SYSTEM_GROUPS@</CODE>.</P>
 458
 459
 460 <H2 CLASS="title"><A NAME="TempDir">TempDir</A></H2>
 461
 462 <H3>Examples</H3>
 463
 464 <PRE CLASS="command">
 465 TempDir /var/tmp
 466 TempDir /foo/bar/tmp
 467 </PRE>
 468
 469 <H3>Description</H3>
 470
 471 <P>The <CODE>TempDir</CODE> directive specifies an absolute path
 472 for the directory to use for temporary files. The default
 473 directory is <VAR>@CUPS_REQUESTS@/tmp</VAR>.</P>
 474
 475 <P>Temporary directories must be world-writable and should have
 476 the "sticky" permission bit enabled so that other users cannot
 477 delete filter temporary files. The following commands will create
 478 an appropriate temporary directory called
 479 <VAR>/foo/bar/tmp</VAR>:</P>
 480
 481 <PRE CLASS="command">
 482 <KBD>mkdir /foo/bar/tmp</KBD>
 483 <KBD>chmod a+rwxt /foo/bar/tmp</KBD>
 484 </PRE>
 485
 486
 487 <H2 CLASS="title"><A NAME="User">User</A></H2>
 488
 489 <H3>Examples</H3>
 490
 491 <PRE CLASS="command">
 492 User lp
 493 User guest
 494 </PRE>
 495
 496 <H3>Description</H3>
 497
 498 <P>The <CODE>User</CODE> directive specifies the UNIX user that
 499 filter and CGI programs run as. The default user is
 500 <CODE>@CUPS_USER@</CODE>.</P>
 501
 502 <BLOCKQUOTE><B>Note:</B>
 503
 504 <P>You may not use user <CODE>root</CODE>, as that would expose
 505 the system to unacceptable security risks. The scheduler will
 506 automatically choose user <CODE>nobody</CODE> if you specify a
 507 user whose ID is 0.</P>
 508
 509 </BLOCKQUOTE>
 510
 511
 512 </BODY>
 513 </HTML>