2 <!-- SECTION: References -->
4 <TITLE>cups-files.conf
</TITLE>
5 <LINK REL=
"STYLESHEET" TYPE=
"text/css" HREF=
"../cups-printable.css">
9 <H1 CLASS=
"title">cups-files.conf
</H1>
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>
13 <H2 CLASS=
"title"><A NAME=
"AccessLog">AccessLog
</A></H2>
18 AccessLog /var/log/cups/access_log
19 AccessLog /var/log/cups/access_log-%s
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
33 <P>The server name can be included in the filename by using
34 <CODE>%s
</CODE> in the name.
</P>
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>
39 <P>The default access log file is
40 <VAR>/var/log/access_log
</VAR>.
</P>
43 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.1.15</SPAN><A NAME=
"ConfigFilePerm">ConfigFilePerm
</A></H2>
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>
56 <BLOCKQUOTE><B>Note:
</B>
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>
63 <H2 CLASS=
"title"><A NAME=
"DataDir">DataDir
</A></H2>
68 DataDir /usr/share/cups
73 <P>The
<CODE>DataDir
</CODE> directive sets the directory to use
77 <H2 CLASS=
"title"><A NAME=
"DocumentRoot">DocumentRoot
</A></H2>
82 DocumentRoot /usr/share/doc/cups
83 DocumentRoot /foo/bar/doc/cups
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>
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
103 <H2 CLASS=
"title"><A NAME=
"ErrorLog">ErrorLog
</A></H2>
107 <PRE CLASS=
"command">
108 ErrorLog /var/log/cups/error_log
109 ErrorLog /var/log/cups/error_log-%s
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>
121 <P>The server name can be included in the filename by using
122 <CODE>%s
</CODE> in the name.
</P>
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>
128 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.4/OS X
10.6</SPAN><A NAME=
"FatalErrors">FatalErrors
</A></H2>
132 <PRE CLASS=
"command">
139 FatalErrors permissions
140 FatalErrors all -permissions
141 FatalErrors config permissions log
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>
151 <LI><CODE>none
</CODE> - No errors are fatal
</LI>
153 <LI><CODE>all
</CODE> - All of the errors below are fatal
</LI>
155 <LI><CODE>browse
</CODE> - Browsing initialization errors are fatal,
156 for example failed binding to the CUPS browse port or failed connections
159 <LI><CODE>config
</CODE> - Configuration file syntax errors are
162 <LI><CODE>listen
</CODE> - Listen or Port errors are fatal, except for
163 IPv6 failures on the loopback or
"any" addresses
</LI>
165 <LI><CODE>log
</CODE> - Log file creation or write errors are fatal
</LI>
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>
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>
178 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.1.18</SPAN><A NAME=
"FileDevice">FileDevice
</A></H2>
182 <PRE CLASS=
"command">
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
195 <P>The default setting is
<CODE>No
</CODE>.
</P>
197 <BLOCKQUOTE><B>Note:
</B>
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
212 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.1.3</SPAN><A NAME=
"FontPath">FontPath
</A></H2>
216 <PRE CLASS=
"command">
217 FontPath /foo/bar/fonts
218 FontPath /usr/share/cups/fonts:/foo/bar/fonts
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>
228 <H2 CLASS=
"title"><A NAME=
"Group">Group
</A></H2>
232 <PRE CLASS=
"command">
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>
245 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.1.15</SPAN><A NAME=
"LogFilePerm">LogFilePerm
</A></H2>
249 <PRE CLASS=
"command">
256 <P>The
<CODE>LogFilePerm
</CODE> directive specifies the
257 permissions to use when writing log files. The default
261 <H2 CLASS=
"title"><A NAME=
"PageLog">PageLog
</A></H2>
265 <PRE CLASS=
"command">
266 PageLog /var/log/cups/page_log
267 PageLog /var/log/cups/page_log-%s
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>
279 <P>The server name can be included in the filename by using
280 <CODE>%s
</CODE> in the name.
</P>
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>
286 <H2 CLASS=
"title"><A NAME=
"Printcap">Printcap
</A></H2>
290 <PRE CLASS=
"command">
292 Printcap /etc/printcap
293 Printcap /etc/printers.conf
294 Printcap /Library/Preferences/org.cups.printers.plist
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>
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>
304 <H2 CLASS=
"title"><A NAME=
"PrintcapFormat">PrintcapFormat
</A></H2>
308 <PRE CLASS=
"command">
310 PrintcapFormat Solaris
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>
321 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.1.3</SPAN><A NAME=
"RemoteRoot">RemoteRoot
</A></H2>
325 <PRE CLASS=
"command">
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
339 <H2 CLASS=
"title"><A NAME=
"RequestRoot">RequestRoot
</A></H2>
343 <PRE CLASS=
"command">
344 RequestRoot /var/spool/cups
345 RequestRoot /foo/bar/spool/cups
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>
357 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
2.0</SPAN><A NAME=
"Sandboxing">Sandboxing
</A> (OS X Only)
</H2>
361 <PRE CLASS=
"command">
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>
372 <H2 CLASS=
"title"><A NAME=
"ServerBin">ServerBin
</A></H2>
376 <PRE CLASS=
"command">
377 ServerBin /usr/lib/cups
378 ServerBin /foo/bar/lib/cups
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>
392 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
2.0</SPAN><A NAME=
"ServerKeychain">ServerKeychain
</A></H2>
396 <PRE CLASS=
"command">
397 ServerKeychain /etc/cups/ssl
398 ServerKeychain /Library/Keychains/system.keychain
403 <P>The
<CODE>ServerKeychain
</CODE> directive specifies the location of TLS certificates and private keys used when negotiating encrypted connections.
</P>
405 <P>The default keychain is system-specific.
</P>
408 <H2 CLASS=
"title"><A NAME=
"ServerRoot">ServerRoot
</A></H2>
412 <PRE CLASS=
"command">
414 ServerRoot /foo/bar/cups
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>
425 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.6.4</SPAN><A NAME=
"SyncOnClose">SyncOnClose
</A></H2>
429 <PRE CLASS=
"command">
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>
441 <BLOCKQUOTE><B>Note:
</B>
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>
445 <P>Enabling
<CODE>SyncOnClose
</CODE> may also cause the scheduler to periodically become unresponsive while it waits for changes to be written.
</P>
450 <H2 CLASS=
"title"><A NAME=
"SystemGroup">SystemGroup
</A></H2>
454 <PRE CLASS=
"command">
459 SystemGroup root lpadmin
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>
467 <H2 CLASS=
"title"><A NAME=
"TempDir">TempDir
</A></H2>
471 <PRE CLASS=
"command">
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>
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>
488 <PRE CLASS=
"command">
489 <KBD>mkdir /foo/bar/tmp
</KBD>
490 <KBD>chmod a+rwxt /foo/bar/tmp
</KBD>
493 <BLOCKQUOTE><B>Note:
</B>
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>
498 <H2 CLASS=
"title"><A NAME=
"User">User
</A></H2>
502 <PRE CLASS=
"command">
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>
511 <BLOCKQUOTE><B>Note:
</B>
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>