Greatly simplify the man page handling.
[thirdparty/cups.git] / man / cups-files.conf.5
CommitLineData
c41769ff 1.\"
c390f212 2.\" cups-files.conf man page for CUPS.
c41769ff 3.\"
87030afb 4.\" Copyright © 2007-2019 by Apple Inc.
ee347e17 5.\" Copyright © 1997-2006 by Easy Software Products.
c41769ff 6.\"
ee347e17
MS
7.\" Licensed under Apache License v2.0. See the file "LICENSE" for more
8.\" information.
c41769ff 9.\"
87030afb 10.TH cups-files.conf 5 "CUPS" "26 April 2019" "Apple Inc."
c41769ff 11.SH NAME
c390f212 12cups\-files.conf \- file and directory configuration file for cups
c41769ff 13.SH DESCRIPTION
c390f212
MS
14The \fBcups\-files.conf\fR file configures the files and directories used by the CUPS scheduler,
15.BR cupsd (8).
16It is normally located in the \fI/etc/cups\fR directory.
c41769ff 17.LP
c390f212 18Each line in the file can be a configuration directive, a blank line, or a comment.
25d0c3fe
MS
19Configuration directives typically consist of a name and zero or more values separated by whitespace.
20The configuration directive name and values are case-insensitive.
c390f212
MS
21Comment lines start with the # character.
22.SS DIRECTIVES
23The following directives are understood by
24.BR cupsd (8):
37d9646b 25.\"#AccessLog
c41769ff 26.TP 5
25d0c3fe 27\fBAccessLog\fR
c41769ff 28.TP 5
25d0c3fe 29\fBAccessLog \fIfilename\fR
c390f212 30.TP 5
c59e07c6
MS
31\fBAccessLog stderr\fR
32.TP 5
c390f212 33\fBAccessLog syslog\fR
c41769ff 34Defines the access log filename.
c390f212 35Specifying a blank filename disables access log generation.
c59e07c6 36The value "stderr" causes log entries to be sent to the standard error file when the scheduler is running in the foreground, or to the system log daemon when run in the background.
25d0c3fe 37The value "syslog" causes log entries to be sent to the system log daemon.
c390f212
MS
38The server name may be included in filenames using the string "%s", for example:
39.nf
40
41 AccessLog /var/log/cups/%s-access_log
42
43.fi
25d0c3fe 44The default is "/var/log/cups/access_log".
7c7347a3
MS
45.\"#CacheDir
46.TP 5
47\fBCacheDir \fIdirectory\fR
48Specifies the directory to use for long-lived temporary (cache) files.
49The default is "/var/spool/cups/cache" or "/var/cache/cups" depending on the platform.
37d9646b 50.\"#ConfigFilePerm
c41769ff 51.TP 5
c390f212
MS
52\fBConfigFilePerm \fImode\fR
53Specifies the permissions for all configuration files that the scheduler writes.
8072030b 54The default is "0644" on macOS and "0640" on all other operating systems.
b4a8492a 55.LP
25d0c3fe 56\fBNote:\fR The permissions for the \fIprinters.conf\fR file are currently masked to only allow access from the scheduler user (typically root).
c390f212
MS
57This is done because printer device URIs sometimes contain sensitive authentication information that should not be generally known on the system.
58There is no way to disable this security feature.
efed0562
MS
59.\"#CreateSelfSignedCerts
60.TP 5
61\fBCreateSelfSignedCerts yes\fR
62.TP 5
63\fBCreateSelfSignedCerts no\fR
64Specifies whether the scheduler automatically creates self-signed certificates for client connections using TLS.
65The default is yes.
37d9646b 66.\"#DataDir
c41769ff 67.TP 5
c390f212 68\fBDataDir \fIpath\fR
25d0c3fe
MS
69Specifies the directory where data files can be found.
70The default is usually "/usr/share/cups".
37d9646b 71.\"#DocumentRoot
c41769ff 72.TP 5
c390f212 73\fBDocumentRoot \fIdirectory\fR
25d0c3fe
MS
74Specifies the root directory for the CUPS web interface content.
75The default is usually "/usr/share/doc/cups".
37d9646b 76.\"#ErrorLog
25d0c3fe
MS
77.TP 5
78\fBErrorLog\fR
c41769ff 79.TP 5
25d0c3fe 80\fBErrorLog \fIfilename\fR
c41769ff 81.TP 5
c59e07c6
MS
82\fBErrorLog stderr\fR
83.TP 5
c390f212
MS
84\fBErrorLog syslog\fR
85Defines the error log filename.
c390f212 86Specifying a blank filename disables error log generation.
c59e07c6 87The value "stderr" causes log entries to be sent to the standard error file when the scheduler is running in the foreground, or to the system log daemon when run in the background.
25d0c3fe 88The value "syslog" causes log entries to be sent to the system log daemon.
c390f212
MS
89The server name may be included in filenames using the string "%s", for example:
90.nf
91
92 ErrorLog /var/log/cups/%s-error_log
93
94.fi
25d0c3fe 95The default is "/var/log/cups/error_log".
37d9646b 96.\"#FatalErrors
c41769ff 97.TP 5
c390f212 98\fBFatalErrors none\fR
c41769ff 99.TP 5
25d0c3fe 100\fBFatalErrors all \fI\-kind \fR[ ... \fI\-kind \fR]
c41769ff 101.TP 5
25d0c3fe 102\fBFatalErrors \fIkind \fR[ ... \fIkind \fR]
c390f212 103Specifies which errors are fatal, causing the scheduler to exit.
25d0c3fe 104The default is "config".
c390f212
MS
105The \fIkind\fR strings are:
106.RS 5
c41769ff 107.TP 5
c390f212
MS
108.B none
109No errors are fatal.
c41769ff 110.TP 5
c390f212
MS
111.B all
112All of the errors below are fatal.
c41769ff 113.TP 5
c390f212
MS
114.B browse
115Browsing initialization errors are fatal, for example failed connections to the DNS-SD daemon.
116.TP 5
117.B config
118Configuration file syntax errors are fatal.
119.TP 5
120.B listen
121Listen or Port errors are fatal, except for IPv6 failures on the loopback or "any" addresses.
122.TP 5
123.B log
124Log file creation or write errors are fatal.
c41769ff 125.TP 5
c390f212
MS
126.B permissions
127Bad startup file permissions are fatal, for example shared TLS certificate and key files with world-read permissions.
128.RE
37d9646b 129.\"#Group
c390f212 130.TP 5
c390f212
MS
131\fBGroup \fIgroup-name-or-number\fR
132Specifies the group name or ID that will be used when executing external programs.
25d0c3fe 133The default group is operating system specific but is usually "lp" or "nobody".
37d9646b 134.\"#LogFilePerm
c41769ff 135.TP 5
c390f212 136\fBLogFilePerm \fImode\fR
25d0c3fe
MS
137Specifies the permissions of all log files that the scheduler writes.
138The default is "0644".
37d9646b 139.\"#PageLog
c41769ff 140.TP 5
c390f212 141\fBPageLog \fR[ \fIfilename\fR ]
c41769ff 142.TP 5
c59e07c6
MS
143\fBPageLog stderr\fR
144.TP 5
c390f212
MS
145\fBPageLog syslog\fR
146Defines the page log filename.
c59e07c6 147The value "stderr" causes log entries to be sent to the standard error file when the scheduler is running in the foreground, or to the system log daemon when run in the background.
c390f212
MS
148The value "syslog" causes log entries to be sent to the system log daemon.
149Specifying a blank filename disables page log generation.
150The server name may be included in filenames using the string "%s", for example:
151.nf
152
153 PageLog /var/log/cups/%s-page_log
154
155.fi
25d0c3fe 156The default is "/var/log/cups/page_log".
d47f6aec
MS
157.\"#PassEnv
158.TP 5
159\fBPassEnv \fIvariable \fR[ ... \fIvariable \fR]
160Passes the specified environment variable(s) to child processes.
161Note: the standard CUPS filter and backend environment variables cannot be overridden using this directive.
37d9646b 162.\"#RemoteRoot
c41769ff 163.TP 5
c390f212
MS
164\fBRemoteRoot \fIusername\fR
165Specifies the username that is associated with unauthenticated accesses by clients claiming to be the root user.
25d0c3fe 166The default is "remroot".
37d9646b 167.\"#RequestRoot
c41769ff 168.TP 5
c390f212
MS
169\fBRequestRoot \fIdirectory\fR
170Specifies the directory that contains print jobs and other HTTP request data.
25d0c3fe 171The default is "/var/spool/cups".
37d9646b 172.\"#Sandboxing
c41769ff 173.TP 5
c390f212 174\fBSandboxing relaxed\fR
8fe0183a 175.TP 5
c390f212
MS
176\fBSandboxing strict\fR
177Specifies the level of security sandboxing that is applied to print filters, backends, and other child processes of the scheduler.
178The default is "strict".
8072030b 179This directive is currently only used/supported on macOS.
37d9646b 180.\"#ServerBin
8fe0183a 181.TP 5
c390f212
MS
182\fBServerBin \fIdirectory\fR
183Specifies the directory containing the backends, CGI programs, filters, helper programs, notifiers, and port monitors.
25d0c3fe 184The default is "/usr/lib/cups" or "/usr/libexec/cups" depending on the platform.
37d9646b 185.\"#ServerKeychain
c41769ff 186.TP 5
c390f212 187\fBServerKeychain \fIpath\fR
8fe0183a 188Specifies the location of TLS certificates and private keys.
8072030b
MS
189The default is "/Library/Keychains/System.keychain" on macOS and "/etc/cups/ssl" on all other operating systems.
190macOS uses its keychain database to store certificates and keys while other platforms use separate files in the specified directory, *.crt for PEM-encoded certificates and *.key for PEM-encoded private keys.
37d9646b 191.\"#ServerRoot
c41769ff 192.TP 5
c390f212
MS
193\fBServerRoot \fIdirectory\fR
194Specifies the directory containing the server configuration files.
25d0c3fe 195The default is "/etc/cups".
d47f6aec
MS
196.\"#SetEnv
197.TP 5
198\fBSetEnv \fIvariable value\fR
199Set the specified environment variable to be passed to child processes.
200Note: the standard CUPS filter and backend environment variables cannot be overridden using this directive.
7c7347a3
MS
201.\"#StateDir
202.TP 5
203\fBStateDir \fIdirectory\fR
204Specifies the directory to use for PID and local certificate files.
205The default is "/var/run/cups" or "/etc/cups" depending on the platform.
37d9646b 206.\"#SyncOnClose
c41769ff 207.TP 5
c390f212 208\fBSyncOnClose Yes\fR
8a259669 209.TP 5
c390f212
MS
210\fBSyncOnClose No\fR
211Specifies whether the scheduler calls
212.BR fsync (2)
25d0c3fe
MS
213after writing configuration or state files.
214The default is "No".
37d9646b 215.\"#SystemGroup
8a259669 216.TP 5
25d0c3fe 217\fBSystemGroup \fIgroup-name \fR[ ... \fIgroup-name\fR ]
c390f212 218Specifies the group(s) to use for \fI@SYSTEM\fR group authentication.
25d0c3fe 219The default contains "admin", "lpadmin", "root", "sys", and/or "system".
37d9646b 220.\"#TempDir
c41769ff 221.TP 5
c390f212 222\fBTempDir \fIdirectory\fR
7c7347a3 223Specifies the directory where short-term temporary files are stored.
25d0c3fe 224The default is "/var/spool/cups/tmp".
37d9646b 225.\"#User
c41769ff 226.TP 5
c390f212 227\fBUser \fIusername\fR
c41769ff 228Specifies the user name or ID that is used when running external programs.
25d0c3fe 229The default is "lp".
7c7347a3
MS
230.SS DEPRECATED DIRECTIVES
231The following directives are deprecated and will be removed from a future version of CUPS:
c6990c1e
MS
232.\"#FileDevice
233.TP 5
234\fBFileDevice Yes\fR
235.TP 5
236\fBFileDevice No\fR
237Specifies whether the file pseudo-device can be used for new printer queues.
238The URI "file:///dev/null" is always allowed.
239File devices cannot be used with "raw" print queues - a PPD file is required.
240The specified file is overwritten for every print job.
241Writing to directories is not supported.
7c7347a3
MS
242.\"#FontPath
243.TP 5
244\fBFontPath \fIdirectory[:...:directoryN]\fR
245Specifies a colon separated list of directories where fonts can be found.
246On Linux the
247.BR font-config (1)
248mechanism is used instead.
249On macOS the Font Book application manages system-installed fonts.
250.\"#LPDConfigFile
251.TP 5
252\fB LPDConfigFile \fIfilename\fR
253Specifies the LPD service configuration file to update.
254.\"#Printcap
255.TP 5
256\fBPrintcap \fIfilename\fR
257Specifies a file that is filled with a list of local print queues.
258.\"#PrintcapFormat
259.TP 5
260\fBPrintcapFormat bsd\fR
261.TP 5
262\fBPrintcapFormat plist\fR
263.TP 5
264\fBPrintcapFormat solaris\fR
265Specifies the format to use for the Printcap file.
266"bsd" is the historical LPD printcap file format.
267"plist" is the Apple plist file format.
268"solaris" is the historical Solaris LPD printcap file format.
269.\"#SMBConfigFile
270.TP 5
271\fBSMBConfigFile \fIfilename\fR
272Specifies the SMB service configuration file to update.
ee347e17
MS
273.SH NOTES
274The scheduler MUST be restarted manually after making changes to the \fBcups-files.conf\fR file.
275On Linux this is typically done using the
276.BR systemctl (8)
277command, while on macOS the
278.BR launchctl (8)
279command is used instead.
c41769ff 280.SH SEE ALSO
c390f212
MS
281.BR classes.conf (5),
282.BR cups (1),
283.BR cupsd (8),
284.BR cupsd.conf (5),
285.BR mime.convs (5),
286.BR mime.types (5),
287.BR printers.conf (5),
288.BR subscriptions.conf (5),
289CUPS Online Help (http://localhost:631/help)
c41769ff 290.SH COPYRIGHT
87030afb 291Copyright \[co] 2007-2019 by Apple Inc.