ref-cups-files-conf.html.in [plain text]
<HTML>
<!-- SECTION: References -->
<HEAD>
<TITLE>cups-files.conf</TITLE>
<LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
</HEAD>
<BODY>
<H1 CLASS="title">cups-files.conf</H1>
<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>
<H2 CLASS="title"><A NAME="AccessLog">AccessLog</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
AccessLog /var/log/cups/access_log
AccessLog /var/log/cups/access_log-%s
AccessLog syslog
</PRE>
<H3>Description</H3>
<P>The <CODE>AccessLog</CODE> directive sets the name of the
access log file. If the filename is not absolute then it is
assumed to be relative to the <A
HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
access log file is stored in "common log format" and can be used
by any web access reporting tool to generate a report on CUPS
server activity.</P>
<P>The server name can be included in the filename by using
<CODE>%s</CODE> in the name.</P>
<P>The special name "syslog" can be used to send the access
information to the system log instead of a plain file.</P>
<P>The default access log file is
<VAR>@CUPS_LOGDIR@/access_log</VAR>.</P>
<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.15</SPAN><A NAME="ConfigFilePerm">ConfigFilePerm</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
ConfigFilePerm 0644
ConfigFilePerm 0640
</PRE>
<H3>Description</H3>
<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>
<BLOCKQUOTE><B>Note:</B>
<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>
</BLOCKQUOTE>
<H2 CLASS="title"><A NAME="DataDir">DataDir</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
DataDir /usr/share/cups
</PRE>
<H3>Description</H3>
<P>The <CODE>DataDir</CODE> directive sets the directory to use
for data files.</P>
<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="DefaultAuthType">DefaultAuthType</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
DefaultAuthType Basic
DefaultAuthType BasicDigest
DefaultAuthType Digest
DefaultAuthType Negotiate
</PRE>
<H3>Description</H3>
<P>The <CODE>DefaultAuthType</CODE> directive specifies the type
of authentication to use for IPP operations that require a
username. The default is <CODE>Basic</CODE>.</P>
<H2 CLASS="title"><A NAME="DocumentRoot">DocumentRoot</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
DocumentRoot /usr/share/doc/cups
DocumentRoot /foo/bar/doc/cups
</PRE>
<H3>Description</H3>
<P>The <CODE>DocumentRoot</CODE> directive specifies the location
of web content for the HTTP server in CUPS. If an absolute path
is not specified then it is assumed to be relative to the <A
HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
default directory is <VAR>@CUPS_DOCROOT@</VAR>.</P>
<P>Documents are first looked up in a sub-directory for the
primary language requested by the client (e.g.
<VAR>@CUPS_DOCROOT@/fr/...</VAR>) and then directly under
the <CODE>DocumentRoot</CODE> directory (e.g.
<VAR>@CUPS_DOCROOT@/...</VAR>), so it is possible to
localize the web content by providing subdirectories for each
language needed.</P>
<H2 CLASS="title"><A NAME="ErrorLog">ErrorLog</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
ErrorLog /var/log/cups/error_log
ErrorLog /var/log/cups/error_log-%s
ErrorLog syslog
</PRE>
<H3>Description</H3>
<P>The <CODE>ErrorLog</CODE> directive sets the name of the error
log file. If the filename is not absolute then it is assumed to
be relative to the <A
HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
default error log file is <VAR>@CUPS_LOGDIR@/error_log</VAR>.</P>
<P>The server name can be included in the filename by using
<CODE>%s</CODE> in the name.</P>
<P>The special name "syslog" can be used to send the error
information to the system log instead of a plain file.</P>
<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/OS X 10.6</SPAN><A NAME="FatalErrors">FatalErrors</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
FatalErrors none
FatalErrors all
FatalErrors browse
FatalErrors config
FatalErrors listen
FatalErrors log
FatalErrors permissions
FatalErrors all -permissions
FatalErrors config permissions log
</PRE>
<H3>Description</H3>
<P>The <CODE>FatalErrors</CODE> directive determines whether certain kinds of
errors are fatal. The following kinds of errors are currently recognized:</P>
<UL>
<LI><CODE>none</CODE> - No errors are fatal</LI>
<LI><CODE>all</CODE> - All of the errors below are fatal</LI>
<LI><CODE>browse</CODE> - Browsing initialization errors are fatal,
for example failed binding to the CUPS browse port or failed connections
to LDAP servers</LI>
<LI><CODE>config</CODE> - Configuration file syntax errors are
fatal</LI>
<LI><CODE>listen</CODE> - Listen or Port errors are fatal, except for
IPv6 failures on the loopback or "any" addresses</LI>
<LI><CODE>log</CODE> - Log file creation or write errors are fatal</LI>
<LI><CODE>permissions</CODE> - Bad startup file permissions are
fatal, for example shared SSL certificate and key files with world-
read permissions</LI>
</UL>
<P>Multiple errors can be listed, and the form "-kind" can be used with
<CODE>all</CODE> to remove specific kinds of errors. The default setting is
<CODE>@CUPS_FATAL_ERRORS@</CODE>.</P>
<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.18</SPAN><A NAME="FileDevice">FileDevice</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
FileDevice Yes
FileDevice No
</PRE>
<H3>Description</H3>
<P>The <CODE>FileDevice</CODE> directive determines whether the
scheduler allows new printers to be added using device URIs of
the form <CODE>file:/filename</CODE>. File devices are most often
used to test new printer drivers and do not support raw file
printing.</P>
<P>The default setting is <CODE>No</CODE>.</P>
<BLOCKQUOTE><B>Note:</B>
<P>File devices are managed by the scheduler. Since the
scheduler normally runs as the root user, file devices
can be used to overwrite system files and potentially
gain unauthorized access to the system. If you must
create printers using file devices, we recommend that
you set the <CODE>FileDevice</CODE> directive to
<CODE>Yes</CODE> for only as long as you need to add the
printers to the system, and then reset the directive to
<CODE>No</CODE>.</P>
</BLOCKQUOTE>
<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.3</SPAN><A NAME="FontPath">FontPath</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
FontPath /foo/bar/fonts
FontPath /usr/share/cups/fonts:/foo/bar/fonts
</PRE>
<H3>Description</H3>
<P>The <CODE>FontPath</CODE> directive specifies the font path to
use when searching for fonts. The default font path is
<CODE>/usr/share/cups/fonts</CODE>.</P>
<H2 CLASS="title"><A NAME="Group">Group</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
Group lp
Group nobody
</PRE>
<H3>Description</H3>
<P>The <CODE>Group</CODE> directive specifies the UNIX group that
filter and CGI programs run as. The default group is
system-specific but is usually <CODE>lp</CODE> or
<CODE>nobody</CODE>.</P>
<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.15</SPAN><A NAME="LogFilePerm">LogFilePerm</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
LogFilePerm 0644
LogFilePerm 0600
</PRE>
<H3>Description</H3>
<P>The <CODE>LogFilePerm</CODE> directive specifies the
permissions to use when writing log files. The default
is @CUPS_LOG_FILE_PERM@.</P>
<H2 CLASS="title"><A NAME="PageLog">PageLog</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
PageLog /var/log/cups/page_log
PageLog /var/log/cups/page_log-%s
PageLog syslog
</PRE>
<H3>Description</H3>
<P>The <CODE>PageLog</CODE> directive sets the name of the page
log file. If the filename is not absolute then it is assumed to
be relative to the <A
HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
default page log file is <VAR>@CUPS_LOGDIR@/page_log</VAR>.</P>
<P>The server name can be included in the filename by using
<CODE>%s</CODE> in the name.</P>
<P>The special name "syslog" can be used to send the page
information to the system log instead of a plain file.</P>
<H2 CLASS="title"><A NAME="Printcap">Printcap</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
Printcap
Printcap /etc/printcap
Printcap /etc/printers.conf
Printcap /Library/Preferences/org.cups.printers.plist
</PRE>
<H3>Description</H3>
<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>@CUPS_DEFAULT_PRINTCAP@</VAR>.</P>
<P>When a filename is specified (e.g. <VAR>@CUPS_DEFAULT_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>
<H2 CLASS="title"><A NAME="PrintcapFormat">PrintcapFormat</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
PrintcapFormat BSD
PrintcapFormat Solaris
PrintcapFormat plist
</PRE>
<H3>Description</H3>
<P>The <CODE>PrintcapFormat</CODE> directive controls the output format of the
printcap file. The default is to generate the plist format on OS X, the
Solaris format on Solaris, and the BSD format on other operating systems.</P>
<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.3</SPAN><A NAME="RemoteRoot">RemoteRoot</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
RemoteRoot remroot
RemoteRoot root
</PRE>
<H3>Description</H3>
<P>The <CODE>RemoteRoot</CODE> directive sets the username for
unauthenticated root requests from remote hosts. The default
username is <VAR>remroot</VAR>. Setting <CODE>RemoteRoot</CODE>
to <VAR>root</VAR> effectively disables this security
mechanism.</P>
<H2 CLASS="title"><A NAME="RequestRoot">RequestRoot</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
RequestRoot /var/spool/cups
RequestRoot /foo/bar/spool/cups
</PRE>
<H3>Description</H3>
<P>The <CODE>RequestRoot</CODE> directive sets the directory for
incoming IPP requests and HTML forms. If an absolute path is not
provided then it is assumed to be relative to the <A
HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
default request directory is <VAR>@CUPS_REQUESTS@</VAR>.</P>
<H2 CLASS="title"><A NAME="ServerBin">ServerBin</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
ServerBin /usr/lib/cups
ServerBin /foo/bar/lib/cups
</PRE>
<H3>Description</H3>
<P>The <CODE>ServerBin</CODE> directive sets the directory for
server-run executables. If an absolute path is not provided then
it is assumed to be relative to the <A
HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory. The
default executable directory is <VAR>/usr/lib/cups</VAR>,
<VAR>/usr/lib32/cups</VAR>, or <VAR>/usr/libexec/cups</VAR>
depending on the operating system.</P>
<H2 CLASS="title"><A NAME="ServerCertificate">ServerCertificate</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
ServerCertificate /etc/cups/ssl/server.crt
</PRE>
<H3>Description</H3>
<P>The <CODE>ServerCertificate</CODE> directive specifies the
location of the SSL certificate file used by the server when
negotiating encrypted connections. The certificate must not be
encrypted (password protected) since the scheduler normally runs
in the background and will be unable to ask for a password.</P>
<P>The default certificate file is
<VAR>/etc/cups/ssl/server.crt</VAR>.</P>
<H2 CLASS="title"><A NAME="ServerKey">ServerKey</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
ServerKey /etc/cups/ssl/server.key
</PRE>
<H3>Description</H3>
<P>The <CODE>ServerKey</CODE> directive specifies the location of
the SSL private key file used by the server when negotiating
encrypted connections.</P>
<P>The default key file is
<VAR>/etc/cups/ssl/server.crt</VAR>.</P>
<H2 CLASS="title"><A NAME="ServerRoot">ServerRoot</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
ServerRoot /etc/cups
ServerRoot /foo/bar/cups
</PRE>
<H3>Description</H3>
<P>The <CODE>ServerRoot</CODE> directive specifies the absolute
path to the server configuration and state files. It is also used
to resolve relative paths in the <VAR>cupsd.conf</VAR> file. The
default server directory is <VAR>/etc/cups</VAR>.</P>
<H2 CLASS="title"><A NAME="SystemGroup">SystemGroup</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
SystemGroup lpadmin
SystemGroup sys
SystemGroup system
SystemGroup root
SystemGroup root lpadmin
</PRE>
<H3>Description</H3>
<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>@CUPS_SYSTEM_GROUPS@</CODE>.</P>
<H2 CLASS="title"><A NAME="TempDir">TempDir</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
TempDir /var/tmp
TempDir /foo/bar/tmp
</PRE>
<H3>Description</H3>
<P>The <CODE>TempDir</CODE> directive specifies an absolute path
for the directory to use for temporary files. The default
directory is <VAR>@CUPS_REQUESTS@/tmp</VAR>.</P>
<P>Temporary directories must be world-writable and should have
the "sticky" permission bit enabled so that other users cannot
delete filter temporary files. The following commands will create
an appropriate temporary directory called
<VAR>/foo/bar/tmp</VAR>:</P>
<PRE CLASS="command">
<KBD>mkdir /foo/bar/tmp</KBD>
<KBD>chmod a+rwxt /foo/bar/tmp</KBD>
</PRE>
<H2 CLASS="title"><A NAME="User">User</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
User lp
User guest
</PRE>
<H3>Description</H3>
<P>The <CODE>User</CODE> directive specifies the UNIX user that
filter and CGI programs run as. The default user is
<CODE>@CUPS_USER@</CODE>.</P>
<BLOCKQUOTE><B>Note:</B>
<P>You may not use user <CODE>root</CODE>, as that would expose
the system to unacceptable security risks. The scheduler will
automatically choose user <CODE>nobody</CODE> if you specify a
user whose ID is 0.</P>
</BLOCKQUOTE>
</BODY>
</HTML>