client.conf

title: client.conf(5)

text:
# client.conf(5)

## NAME
client.conf - client configuration file for cups (deprecated on macos)

## DESCRIPTION
The client.conf file configures the CUPS client and is normally located in the /etc/cups and/or ~/.cups directories. Each line in the file can be a configuration directive, a blank line, or a comment. Comment lines start with the # character.

Note: Starting with macOS 10.7, this file is only used by command-line and X11 applications plus the IPP backend. The ServerName directive is not supported on macOS at all. Starting with macOS 10.12, all applications can access these settings in the /Library/Preferences/org.cups.PrintingPrefs.plist file instead. See the NOTES section below for more information.

### DIRECTIVES
The following directives are understood by the client. Consult the online help for detailed descriptions:

AllowAnyRoot Yes

AllowAnyRoot No

Specifies whether to allow TLS with certificates that have not been signed by a trusted Certificate Authority. The default is "Yes".

AllowExpiredCerts Yes

AllowExpiredCerts No

Specifies whether to allow TLS with expired certificates. The default is "No".

DigestOptions DenyMD5

DigestOptions None

Specifies HTTP Digest authentication options. DenyMD5 disables support for the original MD5 hash algorithm.

Encryption IfRequested

Encryption Never

Encryption Required

Specifies the level of encryption that should be used.

GSSServiceName name

Specifies the Kerberos service name that is used for authentication, typically "host", "http", or "ipp". CUPS adds the remote hostname ("name@server.example.com") for you. The default name is "http".

ServerName hostname-or-ip-address[:port]

ServerName /domain/socket

Specifies the address and optionally the port to use when connecting to the server. Note: This directive is not supported on macOS 10.7 or later.

ServerName hostname-or-ip-address[:port]/version=1.1

Specifies the address and optionally the port to use when connecting to a server running CUPS 1.3.12 and earlier.

SSLOptions [AllowDH] [AllowRC4] [AllowSSL3] [DenyCBC] [DenyTLS1.0] [MaxTLS1.0] [MaxTLS1.1] [MaxTLS1.2] [MaxTLS1.3] [MinTLS1.0] [MinTLS1.1] [MinTLS1.2] [MinTLS1.3] [NoSystem]

SSLOptions None

Sets encryption options (only in /etc/cups/client.conf). By default, CUPS only supports encryption using TLS v1.0 or higher using known secure cipher suites. Security is reduced when Allow options are used. Security is enhanced when Deny options are used. The AllowDH option enables cipher suites using plain Diffie-Hellman key negotiation (not supported on systems using GNU TLS). The AllowRC4 option enables the 128-bit RC4 cipher suites, which are required for some older clients. The AllowSSL3 option enables SSL v3.0, which is required for some older clients that do not support TLS v1.0. The DenyCBC option disables all CBC cipher suites. The DenyTLS1.0 option disables TLS v1.0 support - this sets the minimum protocol version to TLS v1.1. The MinTLS options set the minimum TLS version to support. The MaxTLS options set the maximum TLS version to support. The NoSystem option disables applying system cryptographic policy. Not all operating systems support TLS 1.3 at this time.

TrustOnFirstUse Yes

TrustOnFirstUse No

Specifies whether to trust new TLS certificates by default. The default is "Yes".

User name

Specifies the default user name to use for requests.

UserAgentTokens None

UserAgentTokens ProductOnly

UserAgentTokens Major

UserAgentTokens Minor

UserAgentTokens Minimal

UserAgentTokens OS

UserAgentTokens Full

Specifies what information is included in the User-Agent header of HTTP requests. "None" disables the User-Agent header. "ProductOnly" reports "CUPS". "Major" reports "CUPS/major IPP/2". "Minor" reports "CUPS/major.minor IPP/2.1". "Minimal" reports "CUPS/major.minor.patch IPP/2.1". "OS" reports "CUPS/major.minor.path (osname osversion) IPP/2.1". "Full" reports "CUPS/major.minor.path (osname osversion; architecture) IPP/2.1". The default is "Minimal".

ValidateCerts Yes

ValidateCerts No

Specifies whether to only allow TLS with certificates whose common name matches the hostname. The default is "No".

## NOTES
The client.conf file is deprecated on macOS and will no longer be supported in a future version of CUPS. Configuration settings can instead be viewed or changed using the defaults(1) command:

```
defaults write /Library/Preferences/org.cups.PrintingPrefs.plist Encryption Required
defaults write /Library/Preferences/org.cups.PrintingPrefs.plist TrustOnFirstUse -bool NO
defaults read /Library/Preferences/org.cups.PrintingPrefs.plist Encryption
```

On Linux and other systems using GNU TLS, the /etc/cups/ssl/site.crl file, if present, provides a list of revoked X.509 certificates and is used when validating certificates.

## SEE ALSO
cups(1), default(1), CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2025 by OpenPrinting.


cups-files.conf

package: cups

title: cups-files.conf(5)

text:
# cups-files.conf(5)

## NAME
cups-files.conf - file and directory configuration file for cups

## DESCRIPTION
The cups-files.conf file configures the files and directories used by the CUPS scheduler, cupsd(8). It is normally located in the /etc/cups directory.

Each line in the file can be a configuration directive, a blank line, or a comment. Configuration directives typically consist of a name and zero or more values separated by whitespace. The configuration directive name and values are case-insensitive. Comment lines start with the # character.

### DIRECTIVES
The following directives are understood by cupsd(8):

AccessLog

AccessLog filename

AccessLog stderr

AccessLog syslog

Defines the access log filename. Specifying a blank filename disables access log generation. The 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. The value "syslog" causes log entries to be sent to the system log daemon. The server name may be included in filenames using the string "%s", for example:

```
    AccessLog /var/log/cups/%s-access_log

```

The default is "/var/log/cups/access_log".

CacheDir directory

Specifies the directory to use for long-lived temporary (cache) files. The default is "/var/spool/cups/cache" or "/var/cache/cups" depending on the platform.

ConfigFilePerm mode

Specifies the permissions for all configuration files that the scheduler writes. The default is "0644" on macOS and "0640" on all other operating systems.

Note: The permissions for the printers.conf file are currently 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.

CreateSelfSignedCerts yes

CreateSelfSignedCerts no

Specifies whether the scheduler automatically creates self-signed certificates for client connections using TLS. The default is yes.

DataDir path

Specifies the directory where data files can be found. The default is usually "/usr/share/cups".

DocumentRoot directory

Specifies the root directory for the CUPS web interface content. The default is usually "/usr/share/doc/cups".

ErrorLog

ErrorLog filename

ErrorLog stderr

ErrorLog syslog

Defines the error log filename. Specifying a blank filename disables error log generation. The 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. The value "syslog" causes log entries to be sent to the system log daemon. The server name may be included in filenames using the string "%s", for example:

```
    ErrorLog /var/log/cups/%s-error_log

```

The default is "/var/log/cups/error_log".

FatalErrors none

FatalErrors all -kind [ ... -kind ]

FatalErrors kind [ ... kind ]

Specifies which errors are fatal, causing the scheduler to exit. The default is "config". The kind strings are:

none

No errors are fatal.

all

All of the errors below are fatal.

browse

Browsing initialization errors are fatal, for example failed connections to the DNS-SD daemon.

config

Configuration file syntax errors are fatal.

listen

Listen or Port errors are fatal, except for IPv6 failures on the loopback or "any" addresses.

log

Log file creation or write errors are fatal.

permissions

Bad startup file permissions are fatal, for example shared TLS certificate and key files with world-read permissions.

Group group-name-or-number

Specifies the group name or ID that will be used when executing external programs. The default group is operating system specific but is usually "lp" or "nobody".

LogFileGroup group-name-or-number

Specifies the group name or ID that will be used for log files. The default group is operating system specific but is usually "lp" or "nobody".

LogFilePerm mode

Specifies the permissions of all log files that the scheduler writes. The default is "0644".

PageLog [ filename ]

PageLog stderr

PageLog syslog

Defines the page log filename. The 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. The value "syslog" causes log entries to be sent to the system log daemon. Specifying a blank filename disables page log generation. The server name may be included in filenames using the string "%s", for example:

```
    PageLog /var/log/cups/%s-page_log

```

The default is "/var/log/cups/page_log".

PassEnv variable [ ... variable ]

Passes the specified environment variable(s) to child processes. Note: the standard CUPS filter and backend environment variables cannot be overridden using this directive.

PeerCred off

PeerCred on

PeerCred root-only

Specifies whether peer credentials are used for authorization when communicating over the UNIX domain socket. When on, the peer credentials of any user are accepted for authorization. The value off disables the use of peer credentials entirely, while the value root-only allows peer credentials only for the root user. Note: for security reasons, the on setting is reduced to root-only for authorization of PUT requests.

RemoteRoot username

Specifies the username that is associated with unauthenticated accesses by clients claiming to be the root user. The default is "remroot".

RequestRoot directory

Specifies the directory that contains print jobs and other HTTP request data. The default is "/var/spool/cups".

Sandboxing relaxed

Sandboxing strict

Specifies the level of security sandboxing that is applied to print filters, backends, and other child processes of the scheduler. The default is "strict". This directive is currently only used/supported on macOS.

ServerBin directory

Specifies the directory containing the backends, CGI programs, filters, helper programs, notifiers, and port monitors. The default is "/usr/lib/cups" or "/usr/libexec/cups" depending on the platform.

ServerKeychain path

Specifies the location of TLS certificates and private keys. The default is "/Library/Keychains/System.keychain" on macOS and "/etc/cups/ssl" on all other operating systems. macOS 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.

ServerRoot directory

Specifies the directory containing the server configuration files. The default is "/etc/cups".

SetEnv variable value

Set the specified environment variable to be passed to child processes. Note: the standard CUPS filter and backend environment variables cannot be overridden using this directive.

StateDir directory

Specifies the directory to use for PID and local certificate files. The default is "/var/run/cups" or "/etc/cups" depending on the platform.

StripUserDomain Yes

StripUserDomain No

Specifies whether to remove domain from user name during local user authentication (e.g., "user@example.com" –> "user"). This practice can be beneficial for maintaining compatibility with older versions of Kerberos. However, enabling this option can have negative consequences. It may result in confusion between domain and local users with identical names, potentially leading to incorrect assignment of user permissions and unintentional permission escalation, thus creating a security risk. Therefore, it is advisable to avoid using this option in most cases.

SyncOnClose Yes

SyncOnClose No

Specifies whether the scheduler calls fsync(2) after writing configuration or state files.

SystemGroup group-name [ ... group-name ]

Specifies the group(s) to use for @SYSTEM group authentication. The default contains "admin", "lpadmin", "root", "sys", and/or "system".

TempDir directory

Specifies the directory where short-term temporary files are stored. The default is "/var/spool/cups/tmp".

User username

Specifies the user name or ID that is used when running external programs. The default is "lp".

### DEPRECATED DIRECTIVES
The following directives are deprecated and will be removed from a future version of CUPS:

FileDevice Yes

FileDevice No

Specifies whether the file pseudo-device can be used for new printer queues. The URI "file:///dev/null" is always allowed. File devices cannot be used with "raw" print queues - a PPD file is required. The specified file is overwritten for every print job. Writing to directories is not supported.

Printcap filename

Specifies a file that is filled with a list of local print queues.

PrintcapFormat bsd

PrintcapFormat plist

PrintcapFormat solaris

Specifies the format to use for the Printcap file. "bsd" is the historical LPD printcap file format. "plist" is the Apple plist file format. "solaris" is the historical Solaris LPD printcap file format.

## NOTES
The scheduler MUST be restarted manually after making changes to the cups-files.conf file. On Linux this is typically done using the systemctl(8) command, while on macOS the launchctl(8) command is used instead.

## SEE ALSO
classes.conf(5), cups(1), cupsd(8), cupsd.conf(5), mime.convs(5), mime.types(5), printers.conf(5), subscriptions.conf(5), CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2025 by OpenPrinting.


cups-snmp.conf

title: cups-snmp.conf(5)

text:
# cups-snmp.conf(5)

## NAME
snmp.conf - snmp configuration file for cups (deprecated)

## DESCRIPTION
The snmp.conf file configures how the standard CUPS network backends (http, https, ipp, ipps, lpd, snmp, and socket) access printer information using SNMPv1 and is normally located in the /etc/cups directory. Each line in the file can be a configuration directive, a blank line, or a comment. Comment lines start with the # character.

The Community and DebugLevel directives are used by all backends. The remainder apply only to the SNMP backend - cups-snmp(8).

## DIRECTIVES
The following directives are understood by the CUPS network backends:

Address @IF(name)

Address @LOCAL

Address address

Sends SNMP broadcast queries (for discovery) to the specified address(es). There is no default for the broadcast address.

Community name

Specifies the community name to use. Only a single community name may be specified. The default community name is "public". If no name is specified, all SNMP functions are disabled.

DebugLevel number

Specifies the logging level from 0 (none) to 3 (everything). Typically only used for debugging (thus the name). The default debug level is 0.

DeviceURI "regular expression" device-uri [... device-uri]

Specifies one or more device URIs that should be used for a given make and model string. The regular expression is used to match the detected make and model, and the device URI strings must be of the form "scheme://%s[:port]/[path]", where "%s" represents the detected address or hostname. There are no default device URI matching rules.

HostNameLookups on

HostNameLookups off

Specifies whether the addresses of printers should be converted to hostnames or left as numeric IP addresses. The default is "off".

MaxRunTime seconds

Specifies the maximum number of seconds that the SNMP backend will scan the network for printers. The default is 120 seconds (2 minutes).

## NOTES
CUPS backends are deprecated and will no longer be supported in a future feature release of CUPS. Printers that do not support IPP can be supported using applications such as ippeveprinter(1).

## SEE ALSO
cups-snmp(8), CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2024 by OpenPrinting.


cupsd-logs

title: cupsd-logs(5)

text:
# cupsd-logs(5)

## NAME
cupsd-logs - cupsd log files (access_log, error_log, and page_log)

## DESCRIPTION
cupsd(8) normally maintains three log files: access_log to track requests that are submitted to the scheduler, error_log to track progress and errors, and page_log to track pages that are printed. Configuration directives in cupsd.conf(5) and cups-files.conf(5) control what information is logged and where it is stored.

### ACCESS LOG FILE FORMAT
The access_log file lists each HTTP resource that is accessed by a web browser or client. Each line is in an extended version of the so-called "Common Log Format" used by many web servers and web reporting tools:

```
    host group user date-time "method resource version" status bytes

      ipp-operation ipp-status
```

For example:

```
    10.0.1.2 - - [01/Dec/2005:21:50:28 +0000] "POST / HTTP/1.1" 200 317

      CUPS-Get-Printers successful-ok-ignored-or-substituted-attributes

    localhost - - [01/Dec/2005:21:50:32 +0000] "GET /admin HTTP/1.1"

      200 0 - -

    localhost - - [01/Dec/2005:21:50:32 +0000] "POST / HTTP/1.1"

      200 157 CUPS-Get-Printers

      successful-ok-ignored-or-substituted-attributes

    localhost - - [01/Dec/2005:21:50:32 +0000] "POST / HTTP/1.1"

      200 1411 CUPS-Get-Devices -

    localhost - - [01/Dec/2005:21:50:32 +0000] "GET /admin HTTP/1.1"

      200 6667 - -
```

The host field will normally only be an IP address unless you have enabled the HostNameLookups directive in the cupsd.conf file or if the IP address corresponds to your local machine.

The group field always contains "-".

The user field is the authenticated username of the requesting user. If no username and password is supplied for the request then this field contains "-".

The date-time field is the date and time of the request in local time and is in the format "[DD/MON/YYYY:HH:MM:SS +ZZZZ]".

The method field is the HTTP method used: "GET", "HEAD", "OPTIONS", "POST", or "PUT". "GET" requests are used to get files from the server, both for the web interface and to get configuration and log files. "HEAD" requests are used to get information about a resource prior to a "GET". "OPTIONS" requests are used to upgrade connections to TLS encryption. "POST" requests are used for web interface forms and IPP requests. "PUT" requests are used to upload configuration files.

The resource field is the filename of the requested resource.

The version field is the HTTP specification version used by the client. For CUPS clients this will always be "HTTP/1.1".

The status field contains the HTTP result status of the request, as follows:

200

Successful operation.

201

File created/modified successfully.

304

The requested file has not changed.

400

Bad HTTP request; typically this means that you have a malicious program trying to access your server.

401

Unauthorized, authentication (username + password) is required.

403

Access is forbidden; typically this means that a client tried to access a file or resource they do not have permission to access.

404

The file or resource does not exist.

405

URL access method is not allowed; typically this means you have a web browser using your server as a proxy.

413

Request too large; typically this means that a client tried to print a file larger than the MaxRequestSize allows.

426

Upgrading to TLS-encrypted connection.

500

Server error; typically this happens when the server is unable to open/create a file - consult the error_log file for details.

501

The client requested encryption but encryption support is not enabled/compiled in.

505

HTTP version number not supported; typically this means that you have a malicious program trying to access your server.

The bytes field contains the number of bytes in the request. For POST requests the bytes field contains the number of bytes of non-IPP data that is received from the client.

The ipp-operation field contains either "-" for non-IPP requests or the IPP operation name for POST requests containing an IPP request.

The ipp-status field contains either "-" for non-IPP requests or the IPP status code name for POST requests containing an IPP response.

### ERROR LOG FILE FORMAT
The error_log file lists messages from the scheduler - errors, warnings, etc. The LogLevel directive in the cupsd.conf(5) file controls which messages are logged:

```
    level date-time message
```

For example:

```
    I [20/May/1999:19:18:28 +0000] [Job 1] Queued on 'DeskJet' by 'mike'.

    D [20/May/1999:19:18:28 +0000] [Job 1] argv[0]="DeskJet"

    D [20/May/1999:19:18:28 +0000] [Job 1] argv[1]="1"

    D [20/May/1999:19:18:28 +0000] [Job 1] argv[2]="mike"

    D [20/May/1999:19:18:28 +0000] [Job 1] argv[3]="myjob"

    D [20/May/1999:19:18:28 +0000] [Job 1] argv[4]="1"

    D [20/May/1999:19:18:28 +0000] [Job 1] argv[5]="media=

      na_letter_8.5x11in sides=one-sided"

    D [20/May/1999:19:18:28 +0000] [Job 1] argv[6]="/var/spool/cups/

      d000001-001"

    I [20/May/1999:19:21:02 +0000] [Job 2] Queued on 'DeskJet' by 'mike'.

    I [20/May/1999:19:22:24 +0000] [Job 2] Canceled by 'mike'.
```

The level field contains the type of message:

A

Alert message (LogLevel alert)

C

Critical error message (LogLevel crit)

D

Debugging message (LogLevel debug)

d

Detailed debugging message (LogLevel debug2)

E

Normal error message (LogLevel error)

I

Informational message (LogLevel info)

N

Notice message (LogLevel notice)

W

Warning message (LogLevel warn)

X

Emergency error message (LogLevel emerg)

The date-time field contains the date and time of when the page started printing. The format of this field is identical to the data-time field in the access_log file.

The message field contains a free-form textual message. Messages from job filters are prefixed with "[Job NNN]" where "NNN" is the job ID.

### PAGE LOG FILE FORMAT
The page_log file lists the total number of pages (sheets) that are printed. By default, each line contains the following information:

```
    printer user job-id date-time total num-sheets job-billing

      job-originating-host-name job-name media sides
```

For example the entry for a two page job called "myjob" might look like:

```
    DeskJet root 1 [20/May/1999:19:21:06 +0000] total 2 acme-123

      localhost myjob na_letter_8.5x11in one-sided
```

The PageLogFormat directive in the cupsd.conf(5) file can be used to change this information.

The printer field contains the name of the printer that printed the page. If you send a job to a printer class, this field will contain the name of the printer that was assigned the job.

The user field contains the name of the user (the IPP requesting-user-name attribute) that submitted this file for printing.

The job-id field contains the job number of the page being printed.

The date-time field contains the date and time of when the page started printing. The format of this field is identical to the data-time field in the access_log file.

The num-sheets field provides the total number of pages (sheets) that have been printed on for the job.

The job-billing field contains a copy of the job-billing or job-account-id attributes provided with the IPP Create-Job or Print-Job requests or "-" if neither was provided.

The job-originating-host-name field contains the hostname or IP address of the client that printed the job.

The job-name field contains a copy of the job-name attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided.

The media field contains a copy of the media or media-col/media-size attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided.

The sides field contains a copy of the sides attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided.

## SEE ALSO
cupsd(8), cupsd.conf(5), cups-files.conf(5), CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2024 by OpenPrinting.


cupsd.conf

title: cupsd.conf(5)

summary: server configuration file for cups

text:
# cupsd.conf(5)

## NAME
cupsd.conf - server configuration file for cups

## DESCRIPTION
The cupsd.conf file configures the CUPS scheduler, cupsd(8). It is normally located in the /etc/cups directory. Each line in the file can be a configuration directive, a blank line, or a comment. Configuration directives typically consist of a name and zero or more values separated by whitespace. The configuration directive name and values are case-insensitive. Comment lines start with the # character.

### TOP-LEVEL DIRECTIVES
The following top-level directives are understood by cupsd(8):

AccessLogLevel config

AccessLogLevel actions

AccessLogLevel all

Specifies the logging level for the AccessLog file. The "config" level logs when printers and classes are added, deleted, or modified and when configuration files are accessed or updated. The "actions" level logs when print jobs are submitted, held, released, modified, or canceled, and any of the conditions for "config". The "all" level logs all requests. The default access log level is "actions".

AutoPurgeJobs Yes

AutoPurgeJobs No

Specifies whether to purge job history data automatically when it is no longer required for quotas. The default is "No".

BrowseDNSSDSubTypes_subtype[,...]

Specifies a list of Bonjour sub-types to advertise for each shared printer. For example, "BrowseDNSSDSubTypes _cups,_print" will tell network clients that both CUPS sharing and IPP Everywhere are supported. The default is "_cups" which is necessary for printer sharing to work between systems using CUPS.

BrowseLocalProtocols all

BrowseLocalProtocols dnssd

BrowseLocalProtocols none

Specifies which protocols to use for local printer sharing. The default is "dnssd" on systems that support Bonjour and "none" otherwise.

BrowseWebIF Yes

BrowseWebIF No

Specifies whether the CUPS web interface is advertised. The default is "No".

Browsing Yes

Browsing No

Specifies whether shared printers are advertised. The default is "No".

DefaultAuthType Basic

Specifies the default type of authentication to use. The default is "Basic".

DefaultEncryption Never

DefaultEncryption IfRequested

DefaultEncryption Required

Specifies whether encryption will be used for authenticated requests. The default is "Required".

DefaultLanguage locale

Specifies the default language to use for text and web content. The default is "en".

DefaultPaperSize Auto

DefaultPaperSize None

DefaultPaperSize sizename

Specifies the default paper size for new print queues. "Auto" uses a locale-specific default, while "None" specifies there is no default paper size. Specific size names are typically "Letter" or "A4". The default is "Auto". Note: The default paper size must use a size name from the PPD file and not a PWG self-describing media size name.

DefaultPolicy policy-name

Specifies the default access policy to use. The default access policy is "default".

DefaultShared Yes

DefaultShared No

Specifies whether local printers are shared by default. The default is "Yes".

DirtyCleanInterval seconds

Specifies the delay for updating of configuration and state files. A value of 0 causes the update to happen as soon as possible, typically within a few milliseconds. The default value is "30".

DNSSDHostNamehostname.example.com

Specifies the fully-qualified domain name for the server that is used for Bonjour sharing. The default is typically the server's ".local" hostname.

ErrorPolicy abort-job

Specifies that a failed print job should be aborted (discarded) unless otherwise specified for the printer.

ErrorPolicy retry-current-job

Specifies that a failed print job should be retried immediately unless otherwise specified for the printer.

ErrorPolicy retry-job

Specifies that a failed print job should be retried at a later time unless otherwise specified for the printer.

ErrorPolicy stop-printer

Specifies that a failed print job should stop the printer unless otherwise specified for the printer. The 'stop-printer' error policy is the default.

FilterLimit limit

Specifies the maximum cost of filters that are run concurrently, which can be used to minimize disk, memory, and CPU resource problems. A limit of 0 disables filter limiting. An average print to a non-PostScript printer needs a filter limit of about 200. A PostScript printer needs about half that (100). Setting the limit below these thresholds will effectively limit the scheduler to printing a single job at any time. The default limit is "0".

FilterNice nice-value

Specifies the scheduling priority ( nice(8) value) of filters that are run to print a job. The nice value ranges from 0, the highest priority, to 19, the lowest priority. The default is 0.

HostNameLookups On

HostNameLookups Off

HostNameLookups Double

Specifies whether to do reverse lookups on connecting clients. The "Double" setting causes cupsd(8) to verify that the hostname resolved from the address matches one of the addresses returned for that hostname. Double lookups also prevent clients with unregistered addresses from connecting to your server. The default is "Off" to avoid the potential server performance problems with hostname lookups. Only set this option to "On" or "Double" if absolutely required.

IdleExitTimeout seconds

Specifies the length of time to wait before shutting down due to inactivity. The default is "60" seconds. Note: Only applicable when cupsd(8) is run on-demand (e.g., with -l).

JobKillDelay seconds

Specifies the number of seconds to wait before killing the filters and backend associated with a canceled or held job. The default is "300".

JobRetryInterval seconds

Specifies the interval between retries of jobs in seconds. This is typically used for fax queues but can also be used with normal print queues whose error policy is "retry-job". The default is "300".

JobRetryLimit count

Specifies the number of retries that are done for jobs. This is typically used for fax queues but can also be used with normal print queues whose error policy is "retry-job". The default is "5".

KeepAlive Yes

KeepAlive No

Specifies whether to support HTTP keep-alive connections. The default is "Yes".

<Limit operation ...> ... </Limit>

Specifies the IPP operations that are being limited inside a Policy section. IPP operation names are listed below in the section "IPP OPERATION NAMES".

<Limit method ...> ... </Limit>

<LimitExcept method ...> ... </LimitExcept>

Specifies the HTTP methods that are being limited inside a Location section. HTTP method names are listed below in the section "HTTP METHOD NAMES".

LimitRequestBody size

Specifies the maximum size of print files, IPP requests, and HTML form data. The default is "0" which disables the limit check.

Listen ipv4-address:port

Listen [ipv6-address]:port

Listen *:port

Listen /path/to/domain/socket

Listens to the specified address and port or domain socket path for connections. Multiple Listen directives can be provided to listen on multiple addresses. The Listen directive is similar to the Port directive but allows you to restrict access to specific interfaces or networks. Note: "Listen *:port" and "Port port" effectively listen on all IP addresses, so you cannot combine them with Listen directives for explicit IPv4 or IPv6 addresses on the same port.

<Location /path> ... </Location>

Specifies access control for the named location. Paths are documented below in the section "LOCATION PATHS".

LogDebugHistory number

Specifies the number of debugging messages that are retained for logging if an error occurs in a print job. Debug messages are logged regardless of the LogLevel setting.

LogLevel none

LogLevel emerg

LogLevel alert

LogLevel crit

LogLevel error

LogLevel warn

LogLevel notice

LogLevel info

LogLevel debug

LogLevel debug2

Specifies the level of logging for the ErrorLog file. The value "none" stops all logging while "debug2" logs everything. The default is "warn".

LogTimeFormat standard

LogTimeFormat usecs

Specifies the format of the date and time in the log files. The value "standard" is the default and logs whole seconds while "usecs" logs microseconds.

MaxClients number

Specifies the maximum number of simultaneous clients that are allowed by the scheduler. The default is "100".

MaxClientsPerHost number

Specifies the maximum number of simultaneous clients that are allowed from a single address. The default is the MaxClients value.

MaxCopies number

Specifies the maximum number of copies that a user can print of each job. The default is "9999".

MaxHoldTime seconds

Specifies the maximum time a job may remain in the "indefinite" hold state before it is canceled. The default is "0" which disables cancellation of held jobs.

MaxJobs number

Specifies the maximum number of simultaneous jobs that are allowed. Set to "0" to allow an unlimited number of jobs. The default is "500".

MaxJobsPerPrinter number

Specifies the maximum number of simultaneous jobs that are allowed per printer. The default is "0" which allows up to MaxJobs jobs per printer.

MaxJobsPerUser number

Specifies the maximum number of simultaneous jobs that are allowed per user. The default is "0" which allows up to MaxJobs jobs per user.

MaxJobTime seconds

Specifies the maximum time a job may take to print before it is canceled. Set to "0" to disable cancellation of "stuck" jobs. The default is "10800" (3 hours).

MaxLogSize size

Specifies the maximum size of the log files before they are rotated. The value "0" disables log rotation. The default is "1048576" (1MB).

MaxSubscriptions number

Specifies the maximum number of simultaneous event subscriptions that are allowed. Set to "0" to allow an unlimited number of subscriptions. The default is "100".

MaxSubscriptionsPerJob number

Specifies the maximum number of simultaneous event subscriptions that are allowed per job. The default is "0" which allows up to MaxSubscriptions subscriptions per job.

MaxSubscriptionsPerPrinter number

Specifies the maximum number of simultaneous event subscriptions that are allowed per printer. The default is "0" which allows up to MaxSubscriptions subscriptions per printer.

MaxSubscriptionsPerUser number

Specifies the maximum number of simultaneous event subscriptions that are allowed per user. The default is "0" which allows up to MaxSubscriptions subscriptions per user.

MultipleOperationTimeout seconds

Specifies the maximum amount of time to allow between files in a multiple file print job. The default is "900" (15 minutes).

<Policy name> ... </Policy>

Specifies access control for the named policy.

Port number

Listens to the specified port number for connections.

PreserveJobFiles Yes

PreserveJobFiles No

PreserveJobFiles seconds

Specifies whether job files (documents) are preserved after a job is printed. If a numeric value is specified, job files are preserved for the indicated number of seconds after printing. The default is "86400" (preserve 1 day).

PreserveJobHistory Yes

PreserveJobHistory No

PreserveJobHistory seconds

Specifies whether the job history is preserved after a job is printed. If a numeric value is specified, the job history is preserved for the indicated number of seconds after printing. If "Yes", the job history is preserved until the MaxJobs limit is reached. The default is "Yes".

ReadyPaperSizes sizename[,...]

Specifies a list of potential paper sizes that are reported as "ready" (loaded). The actual list will only contain sizes that each printer supports. The default is "Letter,Legal,Tabloid,4x6,Env10" when the default paper size is "Letter" and "A3,A4,A5,A6,EnvDL" otherwise. Note: Paper sizes must use the size names from the PPD file and not PWG self-describing media size names.

ReloadTimeout seconds

Specifies the amount of time to wait for job completion before restarting the scheduler. The default is "30".

ServerAdmin email-address

Specifies the email address of the server administrator. The default value is "root@ServerName".

ServerAlias hostname [ ... hostname ]

ServerAlias *

The ServerAlias directive is used for HTTP Host header validation when clients connect to the scheduler from external interfaces. Using the special name "*" can expose your system to known browser-based DNS rebinding attacks, even when accessing sites through a firewall. If the auto-discovery of alternate names does not work, we recommend listing each alternate name with a ServerAlias directive instead of using "*".

ServerName hostname

Specifies the fully-qualified hostname of the server. The default is the value reported by the hostname(1) command.

ServerTokens None

ServerTokens ProductOnly

ServerTokens Major

ServerTokens Minor

ServerTokens Minimal

ServerTokens OS

ServerTokens Full

Specifies what information is included in the Server header of HTTP responses. "None" disables the Server header. "ProductOnly" reports "CUPS". "Major" reports "CUPS/major IPP/2". "Minor" reports "CUPS/major.minor IPP/2.1". "Minimal" reports "CUPS/major.minor.patch IPP/2.1". "OS" reports "CUPS/major.minor.path (osname osversion) IPP/2.1". "Full" reports "CUPS/major.minor.path (osname osversion; architecture) IPP/2.1". The default is "Minimal".

SSLListen ipv4-address:port

SSLListen [ipv6-address]:port

SSLListen *:port

Listens on the specified address and port for encrypted connections.

SSLOptions [AllowDH] [AllowRC4] [AllowSSL3] [DenyCBC] [DenyTLS1.0] [MaxTLS1.0] [MaxTLS1.1] [MaxTLS1.2] [MaxTLS1.3] [MinTLS1.0] [MinTLS1.1] [MinTLS1.2] [MinTLS1.3] [NoSystem]

SSLOptions None

Sets encryption options (only in /etc/cups/client.conf). By default, CUPS only supports encryption using TLS v1.0 or higher using known secure cipher suites. Security is reduced when Allow options are used. Security is enhanced when Deny options are used. The AllowDH option enables cipher suites using plain Diffie-Hellman key negotiation (not supported on systems using GNU TLS). The AllowRC4 option enables the 128-bit RC4 cipher suites, which are required for some older clients. The AllowSSL3 option enables SSL v3.0, which is required for some older clients that do not support TLS v1.0. The DenyCBC option disables all CBC cipher suites. The DenyTLS1.0 option disables TLS v1.0 support - this sets the minimum protocol version to TLS v1.1. The MinTLS options set the minimum TLS version to support. The MaxTLS options set the maximum TLS version to support. The NoSystem option disables applying system cryptographic policy. Not all operating systems support TLS 1.3 at this time.

SSLPort port

Listens on the specified port for encrypted connections.

StrictConformance Yes

StrictConformance No

Specifies whether the scheduler requires clients to strictly adhere to the IPP specifications. The default is "No".

Timeout seconds

Specifies the HTTP request timeout. The default is "900" (15 minutes).

WebInterface yes

WebInterface no

Specifies whether the web interface is enabled. The default is "No".

### HTTP METHOD NAMES
The following HTTP methods are supported by cupsd(8):

GET

Used by a client to download icons and other printer resources and to access the CUPS web interface.

HEAD

Used by a client to get the type, size, and modification date of resources.

OPTIONS

Used by a client to establish a secure (SSL/TLS) connection.

POST

Used by a client to submit IPP requests and HTML forms from the CUPS web interface.

PUT

Used by a client to upload configuration files.

### IPP OPERATION NAMES
The following IPP operations are supported by cupsd(8):

CUPS-Accept-Jobs

Allows a printer to accept new jobs.

CUPS-Add-Modify-Class

Adds or modifies a printer class.

CUPS-Add-Modify-Printer

Adds or modifies a printer.

CUPS-Authenticate-Job

Releases a job that is held for authentication.

CUPS-Delete-Class

Deletes a printer class.

CUPS-Delete-Printer

Deletes a printer.

CUPS-Get-Classes

Gets a list of printer classes.

CUPS-Get-Default

Gets the server default printer or printer class.

CUPS-Get-Devices

Gets a list of devices that are currently available.

CUPS-Get-Document

Gets a document file for a job.

CUPS-Get-PPD

Gets a PPD file.

CUPS-Get-PPDs

Gets a list of installed PPD files.

CUPS-Get-Printers

Gets a list of printers.

CUPS-Move-Job

Moves a job.

CUPS-Reject-Jobs

Prevents a printer from accepting new jobs.

CUPS-Set-Default

Sets the server default printer or printer class.

Cancel-Job

Cancels a job.

Cancel-Jobs

Cancels one or more jobs.

Cancel-My-Jobs

Cancels one or more jobs creates by a user.

Cancel-Subscription

Cancels a subscription.

Close-Job

Closes a job that is waiting for more documents.

Create-Job

Creates a new job with no documents.

Create-Job-Subscriptions

Creates a subscription for job events.

Create-Printer-Subscriptions

Creates a subscription for printer events.

Get-Job-Attributes

Gets information about a job.

Get-Jobs

Gets a list of jobs.

Get-Notifications

Gets a list of event notifications for a subscription.

Get-Printer-Attributes

Gets information about a printer or printer class.

Get-Subscription-Attributes

Gets information about a subscription.

Get-Subscriptions

Gets a list of subscriptions.

Hold-Job

Holds a job from printing.

Hold-New-Jobs

Holds all new jobs from printing.

Pause-Printer

Stops processing of jobs by a printer or printer class.

Pause-Printer-After-Current-Job

Stops processing of jobs by a printer or printer class after the current job is finished.

Print-Job

Creates a new job with a single document.

Purge-Jobs

Cancels one or more jobs and deletes the job history.

Release-Held-New-Jobs

Allows previously held jobs to print.

Release-Job

Allows a job to print.

Renew-Subscription

Renews a subscription.

Restart-Job

Reprints a job, if possible.

Send-Document

Adds a document to a job.

Set-Job-Attributes

Changes job information.

Set-Printer-Attributes

Changes printer or printer class information.

Validate-Job

Validates options for a new job.

### LOCATION PATHS
The following paths are commonly used when configuring cupsd(8):

/

The path for all get operations (get-printers, get-jobs, etc.)

/admin

The path for all administration operations (add-printer, delete-printer, start-printer, etc.)

/admin/conf

The path for access to the CUPS configuration files (cupsd.conf, client.conf, etc.)

/admin/log

The path for access to the CUPS log files (access_log, error_log, page_log)

/classes

The path for all printer classes

/classes/name

The resource for the named printer class

/jobs

The path for all jobs (hold-job, release-job, etc.)

/jobs/id

The path for the specified job

/printers

The path for all printers

/printers/name

The path for the named printer

/printers/name.png

The icon file path for the named printer

/printers/name.ppd

The PPD file path for the named printer

### DIRECTIVES VALID WITHIN LOCATION AND LIMIT SECTIONS
The following directives may be placed inside Location and Limit sections in the cupsd.conf file:

Allow all

Allow none

Allow host.domain.com

Allow *.domain.com

Allow ipv4-address

Allow ipv4-address/netmask

Allow ipv4-address/mm

Allow [ipv6-address]

Allow [ipv6-address]/mm

Allow @IF(name)

Allow @LOCAL

Allows access from the named hosts, domains, addresses, or interfaces. The @IF(name) form uses the current subnets configured for the named interface. The @LOCAL form uses the current subnets configured for all interfaces that are not point-to-point, for example Ethernet and Wi-Fi interfaces are used but DSL and VPN interfaces are not. The Order directive controls whether Allow lines are evaluated before or after Deny lines.

AuthType None

AuthType Basic

AuthType Default

Specifies the type of authentication required. The value "Default" corresponds to the DefaultAuthType value.

Deny all

Deny none

Deny host.domain.com

Deny *.domain.com

Deny ipv4-address

Deny ipv4-address/netmask

Deny ipv4-address/mm

Deny [ipv6-address]

Deny [ipv6-address]/mm

Deny @IF(name)

Deny @LOCAL

Denies access from the named hosts, domains, addresses, or interfaces. The @IF(name) form uses the current subnets configured for the named interface. The @LOCAL form uses the current subnets configured for all interfaces that are not point-to-point, for example Ethernet and Wi-Fi interfaces are used but DSL and VPN interfaces are not. The Order directive controls whether Deny lines are evaluated before or after Allow lines.

Encryption IfRequested

Encryption Never

Encryption Required

Specifies the level of encryption that is required for a particular location. The default value is "IfRequested".

Order allow,deny

Specifies that access is denied by default. Allow lines are then processed followed by Deny lines to determine whether a client may access a particular resource.

Order deny,allow

Specifies that access is allowed by default. Deny lines are then processed followed by Allow lines to determine whether a client may access a particular resource.

Require group group-name [ group-name ... ]

Specifies that an authenticated user must be a member of one of the named groups.

Require user {user-name|@group-name} ...

Specifies that an authenticated user must match one of the named users or be a member of one of the named groups. The group name "@SYSTEM" corresponds to the list of groups defined by the SystemGroup directive in the cups-files.conf(5) file. The group name "@OWNER" corresponds to the owner of the resource, for example the person that submitted a print job. Note: The 'root' user is not special and must be granted privileges like any other user account.

Require valid-user

Specifies that any authenticated user is acceptable.

Satisfy all

Specifies that all Allow, AuthType, Deny, Order, and Require conditions must be satisfied to allow access.

Satisfy any

Specifies that any a client may access a resource if either the authentication (AuthType/Require) or address (Allow/Deny/Order) conditions are satisfied. For example, this can be used to require authentication only for remote accesses.

### DIRECTIVES VALID WITHIN POLICY SECTIONS
The following directives may be placed inside Policy sections in the cupsd.conf file:

JobPrivateAccess all

JobPrivateAccess default

JobPrivateAccess {user|@group|@ACL|@OWNER|@SYSTEM} ...

Specifies an access list for a job's private values. The "default" access list is "@OWNER @SYSTEM". "@ACL" maps to the printer's requesting-user-name-allowed or requesting-user-name-denied values. "@OWNER" maps to the job's owner. "@SYSTEM" maps to the groups listed for the SystemGroup directive in the cups-files.conf(5) file.

JobPrivateValues all

JobPrivateValues default

JobPrivateValues none

JobPrivateValues attribute-name [ ... attribute-name ]

Specifies the list of job values to make private. The "default" values are "job-name", "job-originating-host-name", "job-originating-user-name", and "phone".

SubscriptionPrivateAccess all

SubscriptionPrivateAccess default

SubscriptionPrivateAccess {user|@group|@ACL|@OWNER|@SYSTEM} ...

Specifies an access list for a subscription's private values. The "default" access list is "@OWNER @SYSTEM". "@ACL" maps to the printer's requesting-user-name-allowed or requesting-user-name-denied values. "@OWNER" maps to the job's owner. "@SYSTEM" maps to the groups listed for the SystemGroup directive in the cups-files.conf(5) file.

SubscriptionPrivateValues all

SubscriptionPrivateValues default

SubscriptionPrivateValues none

SubscriptionPrivateValues attribute-name [ ... attribute-name ]

Specifies the list of subscription values to make private. The "default" values are "notify-events", "notify-pull-method", "notify-recipient-uri", "notify-subscriber-user-name", and "notify-user-data".

### DEPRECATED DIRECTIVES
The following directives are deprecated and will be removed in a future release of CUPS:

AuthType Negotiate

Specifies Kerberos authentication is required.

Classification banner

Specifies the security classification of the server. Any valid banner name can be used, including "classified", "confidential", "secret", "topsecret", and "unclassified", or the banner can be omitted to disable secure printing functions. The default is no classification banner.

ClassifyOverride Yes

ClassifyOverride No

Specifies whether users may override the classification (cover page) of individual print jobs using the "job-sheets" option. The default is "No".

DefaultAuthType Negotiate

Specifies that Kerberos authentication is required by default.

GSSServiceName name

Specifies the service name when using Kerberos authentication. The default service name is "http."

PageLogFormat format-string

Specifies the format of PageLog lines. Sequences beginning with percent (%) characters are replaced with the corresponding information, while all other characters are copied literally. The following percent sequences are recognized:

```
    "%%" inserts a single percent character.

    "%{name}" inserts the value of the specified IPP attribute.

    "%C" inserts the number of copies for the current page.

    "%P" inserts the current page number.

    "%T" inserts the current date and time in common log format.

    "%j" inserts the job ID.

    "%p" inserts the printer name.

    "%u" inserts the username.

```

The default is the empty string, which disables page logging. The string "%p %u %j %T %P %C %{job-billing} %{job-originating-host-name} %{job-name} %{media} %{sides}" creates a page log with the standard items. Use "%{job-impressions-completed}" to insert the number of pages (sides) that were printed, or "%{job-media-sheets-completed}" to insert the number of sheets that were printed.

## NOTES
File, directory, and user configuration directives that used to be allowed in the cupsd.conf file are now stored in the cups-files.conf(5) file instead in order to prevent certain types of privilege escalation attacks.

The scheduler MUST be restarted manually after making changes to the cupsd.conf file. On Linux this is typically done using the systemctl(8) command, while on macOS the launchctl(8) command is used instead.

The @LOCAL macro name can be confusing since the system running cupsd often belongs to a different set of subnets from its clients.

## CONFORMING TO
The cupsd.conf file format is based on the Apache HTTP Server configuration file format.

## EXAMPLES
Log everything with a maximum log file size of 32 megabytes:

```
    AccessLogLevel all

    LogLevel debug2

    MaxLogSize 32m
```

Require authentication for accesses from outside the 10. network:

```
    <Location />

    Order allow,deny

    Allow from 10./8

    AuthType Basic

    Require valid-user

    Satisfy any

    </Location>
```

## SEE ALSO
classes.conf(5), cups-files.conf(5), cupsd(8), mime.convs(5), mime.types(5), printers.conf(5), subscriptions.conf(5), CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2025 by OpenPrinting.


mailto.conf

title: mailto.conf(5)

text:
# mailto.conf(5)

## NAME
mailto.conf - configuration file for cups email notifier

## DESCRIPTION
The mailto.conf file defines the local mail server and email notification preferences for CUPS.

Each line in the file can be a configuration directive, a blank line, or a comment. Configuration directives typically consist of a name and zero or more values separated by whitespace. The configuration directive name and values are case-insensitive. Comment lines start with the # character.

### DIRECTIVES
Cc cc-address@domain.com

Specifies an additional recipient for all email notifications.

From from-address@domain.com

Specifies the sender of email notifications.

Sendmail sendmail command and options

Specifies the sendmail command to use when sending email notifications. Only one Sendmail or SMTPServer line may be present in the mailto.conf file. If multiple lines are present, only the last one is used.

SMTPServer servername

Specifies a SMTP server to send email notifications to. Only one Sendmail or SMTPServer line may be present in the mailto.conf file. If multiple lines are present, only the last one is used.

Subject subject-prefix

Specifies a prefix string for the subject line of an email notification.

## SEE ALSO
cupsd(8), CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2024 by OpenPrinting.


mime.convs

title: mime.convs(5)

text:
# mime.convs(5)

## NAME
mime.convs - mime type conversion file for cups (deprecated)

## DESCRIPTION
The mime.convs file defines the filters that are available for converting files from one format to another. The standard filters support text, PDF, PostScript, and many types of image files.

Additional filters are specified in files with the extension .convs in the CUPS configuration directory.

Each line in the mime.convs file is a comment, blank, or filter line. Comment lines start with the # character. Filter lines specify the source and destination MIME types along with a relative cost associated with the filter and the filter to run:

```
    source/type destination/type cost filter
```

The source/type field specifies the source MIME media type that is consumed by the filter. The destination/type field specifies the destination MIME media type that is produced by the filter.

The cost field specifies the relative cost for running the filter. A value of 100 means that the filter uses a large amount of resources while a value of 0 means that the filter uses very few resources.

The filter field specifies the filter program filename. Filenames are relative to the CUPS filter directory.

## FILES
/etc/cups - Typical CUPS configuration directory.

/usr/lib/cups/filter - Typical CUPS filter directory.

/usr/libexec/cups/filter - CUPS filter directory on macOS.

## EXAMPLES
Define a filter that converts PostScript documents to CUPS Raster format:

```
    application/vnd.cups-postscript application/vnd.cups-raster 50 pstoraster
```

## NOTES
CUPS filters are deprecated and will no longer be supported in a future feature release of CUPS. Printers that do not support IPP can be supported using applications such as ippeveprinter(1).

## SEE ALSO
cups-files.conf(5), cupsd.conf(5), cupsd(8), cupsfilter(8), mime.types(5), CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2024 by OpenPrinting.


mime.types

title: mime.types(5)

summary: mime type description file for cups

text:
# mime.types(5)

## NAME
mime.types - mime type description file for cups

## DESCRIPTION
The mime.types file defines the recognized file types.

Additional file types are specified in files with the extension .types in the CUPS configuration directory.

Each line in the mime.types file is a comment, blank, or rule line. Comment lines start with the # character. Rule lines start with the MIME media type and are optionally followed by a series of file recognition rules:

```
    mime/type [ rule ... rule ]
```

Rules can be extended over multiple lines using the backslash character (\):

```
    mime/type [ really-really-really-long-rule ... \

      rule ]
```

MIME media types specified by the mime/type field are case-insensitive and are sorted in ascending alphanumeric order for the purposes of matching. See the "TYPE MATCHING AND PRIORITY" section for more information. The rules may be grouped using parenthesis, joined using "+" for a logical AND, joined using "," or whitespace for a logical OR, and negated using "!".

### RULES
Rules take two forms - a filename extension by itself and functions with test values inside parenthesis. The following functions are available:

match("pattern")

True if the filename matches the given shell wildcard pattern.

ascii(offset,length)

True if the length bytes starting at offset are valid printable ASCII (CR, NL, TAB, BS, 32-126). length cannot exceed 8192 bytes.

printable(offset,length)

True if the length bytes starting at offset are printable 8-bit chars (CR, NL, TAB, BS, 32-126, 128-254). length cannot exceed 8192 bytes.

priority(number)

Specifies the relative priority of this MIME media type. The default priority is 100. Larger values have higher priority while smaller values have lower priority.

string(offset,"string")

True if the bytes starting at offset are identical to string.

istring(offset,"string")

True if the bytes starting at offset match string without respect to case.

char(offset,value)

True if the byte at offset is identical to value.

short(offset,value)

True if the 16-bit big-endian integer at offset is identical to value.

int(offset,value)

True if the 32-bit big-endian integer at offset is identical to value.

locale("string")

True if current locale matches string.

contains(offset,length,"string")

True if the bytes starting at offset for length bytes contains string. length cannot exceed 8192 bytes.

### STRING CONSTANTS
String constants can be specified inside quotes ("") for strings containing whitespace and angle brackets (<>) for hexadecimal strings.

### TYPE MATCHING AND PRIORITY
When CUPS needs to determine the MIME media type of a given file, it checks every MIME media type defined in the .types files. When two or more types match a given file, the type chosen will depend on the type name and priority, with higher-priority types being used over lower-priority ones. If the types have the same priority, the type names are sorted alphanumerically in ascending order and the first type is chosen.

For example, if two types "text/bar" and "text/foo" are defined as matching the extension "doc", normally the type "text/bar" will be chosen since its name is alphanumerically smaller than "text/foo". However, if "text/foo" also defines a higher priority than "text/bar", "text/foo" will be chosen instead.

## FILES
/etc/cups - Typical CUPS configuration directory.

## EXAMPLES
Define two MIME media types for raster data, with one being a subset with higher priority:

```
    application/vnd.cups-raster  string(0,"RaSt") string(0,"tSaR") \

                                  string(0,"RaS2") string(0,"2SaR") \

                                  string(0,"RaS3") string(0,"3SaR")

    image/pwg-raster              string(0,"RaS2") + \

                                  string(4,PwgRaster<00>) priority(150)
```

## SEE ALSO
cups-files.conf(5), cupsd.conf(5), cupsd(8), cupsfilter(8), mime.convs(5), CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2024 by OpenPrinting.


printers.conf

title: printers.conf(5)

summary: printer configuration file for cups

text:
# printers.conf(5)

## NAME
printers.conf - printer configuration file for cups

## DESCRIPTION
The printers.conf file defines the local printers that are available. It is normally located in the /etc/cups directory and is maintained by the cupsd(8) program. This file is not intended to be edited or managed manually.

## NOTES
The name, location, and format of this file are an implementation detail that will change in future releases of CUPS.

## SEE ALSO
classes.conf(5), cups-files.conf(5), cupsd(8), cupsd.conf(5), mime.convs(5), mime.types(5), subscriptions.conf(5), CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2024 by OpenPrinting.


subscriptions.conf

title: subscriptions.conf(5)

text:
# subscriptions.conf(5)

## NAME
subscriptions.conf - subscription configuration file for cups

## DESCRIPTION
The subscriptions.conf file defines the local event notification subscriptions that are active. It is normally located in the /etc/cups directory and is maintained by the cupsd(8) program. This file is not intended to be edited or managed manually.

## NOTES
The name, location, and format of this file are an implementation detail that will change in future releases of CUPS.

## SEE ALSO
classes.conf(5), cups-files.conf(5), cupsd(8), cupsd.conf(5), mime.convs(5), mime.types(5), printers.conf(5), CUPS Online Help (http://localhost:631/help)

## COPYRIGHT
Copyright © 2020-2024 by OpenPrinting.


cups-browsed.conf

package: cups-filters

title: cups-browsed.conf(5)

text:
# cups-browsed.conf(5)

## NAME
cups-browsed.conf - server configuration file for cups-browsed

## DESCRIPTION
The cups-browsed.conf file configures the cups-browsed daemon. It is normally located in the /etc/cups directory. Each line in the file can be a configuration directive, a blank line, or a comment. Comment lines start with the # character.

## DIRECTIVES
The "CacheDir" directive determines where cups-browsed should save information about the print queues it had generated when shutting down, like whether one of these queues was the default printer, or default option settings of the queues.

```
        CacheDir /var/cache/cups
```

With "LogDir" can be defined where cups-browsed creates its debug log file (if "DebugLogging file" is set).

```
        LogDir /var/log/cups
```

The "DebugLogging" directive determines how should debug logging be done. Into the file /var/log/cups/cups-browsed_log ("file"), to stderr ("stderr"), or not at all ("none"). Note that if cups-browsed is running as a system service (for example via systemd) logging to stderr makes the log output going to the journal or syslog. Only if you run cups-browsed from the command line (for development or debugging) it will actually appear on stderr.

```
        DebugLogging file

        DebugLogging stderr

        DebugLogging file stderr

        DebugLogging none
```

Only browse remote printers (via DNS-SD) from selected servers using the "BrowseAllow", "BrowseDeny", and "BrowseOrder" directives This serves for restricting the choice of printers in print dialogs to trusted servers or to reduce the number of listed printers in the print dialogs to a more user-friendly amount in large networks with very many shared printers.

This only filters the selection of remote printers for which cups-browsed creates local queues. If the print dialog uses other mechanisms to list remote printers as for example direct DNS-SD access, cups-browsed has no influence. cups-browsed also does not prevent the user from manually accessing non-listed printers.

"BrowseAllow": Accept printers from these hosts or networks. If there are only "BrowseAllow" lines and no "BrowseOrder" and/or "BrowseDeny" lines, only servers matching at last one "BrowseAllow" line are accepted.

"BrowseDeny": Deny printers from these hosts or networks. If there are only "BrowseDeny" lines and no "BrowseOrder" and/or "BrowseAllow" lines, all servers NOT matching any of the "BrowseDeny" lines are accepted.

"BrowseOrder": Determine the order in which "BrowseAllow" and "BrowseDeny" lines are applied. With "BrowseOrder Deny,Allow" in the beginning all servers are accepted, then the "BrowseDeny" lines are applied to exclude unwished servers or networks and after that the "BrowseAllow" lines to re-include servers or networks. With "BrowseOrder Allow,Deny" we start with denying all servers, then applying the "BrowseAllow" lines and afterwards the "BrowseDeny" lines.

Default for "BrowseOrder" is "Deny.Allow" if there are both "BrowseAllow" and "BrowseDeny" lines.

If there are no "Browse..." lines at all, all servers are accepted.

```
        BrowseAllow All

        BrowseAllow 192.168.7.20

        BrowseAllow 192.168.7.0/24

        BrowseAllow 192.168.7.0/255.255.255.0

        BrowseDeny All

        BrowseDeny 192.168.1.13

        BrowseDeny 192.168.3.0/24

        BrowseDeny 192.168.3.0/255.255.255.0

        BrowseOrder Deny,Allow

        BrowseOrder Allow,Deny
```

Filtering of remote printers by other properties than IP addresses of their servers Often the desired selection of printers cannot be reached by only taking into account the IP addresses of the servers. For these cases there is the BrowseFilter directive to filter by most of the known properties of the printer.

By default there is no BrowseFilter line meaning that no filtering is applied.

To do filtering one can supply one or more BrowseFilter directives like this:

```
        BrowseFilter [NOT] [EXACT] <FIELD> [<VALUE>]
```

The BrowseFilter directive always starts with the word "BrowseFilter" and it must at least contain the name of the data field (<FIELD>) of the printer's properties to which it should apply. Available field names are:

```
        name:    Name of the local print queue to be created

        host:    Host name of the remote print server

        port:    Port through which the printer is accessed on the server

        service: DNS/SD service name of the remote printer

        domain:  Domain of the remote print server
```

Also all field names in the TXT records of DNS-SD-advertised printers are valid, like "color", "duplex", "pdl", ... If the field name of the filter rule does not exist for the printer, the rule is skipped. The optional <VALUE> field is either the exact value (when the option EXACT is supplied) or a regular expression (Run "man 7 regex" in a terminal window) to be matched with the data field.

If no <VALUE> filed is supplied, rules with field names of the TXT record are considered for boolean matching (true/false) of boolean field (like duplex, which can have the values "T" for true and "F" for false).

If the option NOT is supplied, the filter rule is fulfilled if the regular expression or the exact value DOES NOT match the content of the data field. In a boolean rule (without <VALUE>) the rule matches false.

Regular expressions are always considered case-insensitive and extended POSIX regular expressions. Field names and options (NOT, EXACT) are all evaluated case-insensitive. If there is an error in a regular expression, the BrowseFilter line gets ignored.

Especially to note is that supplying any simple string consisting of only letters, numbers, spaces, and some basic special characters as a regular expression matches if it is contained somewhere in the data field.

If there is more than one BrowseFilter directive, ALL the directives need to be fulfilled for the remote printer to be accepted. If one is not fulfilled, the printer will get ignored.

Examples:

Rules for standard data items which are supplied with any remote printer advertised via DNS-SD:

Print queue name must contain "hum_res_", this matches "hum_res_mono" or "hum_res_color" but also "old_hum_res_mono":

```
        BrowseFilter name hum_res_
```

This matches if the remote host name contains "printserver", like "printserver.local", "printserver2.example.com", "newprintserver":

```
        BrowseFilter host printserver
```

This matches all ports with 631 int its number, for example 631, 8631, 10631,...:

```
        BrowseFilter port 631
```

This rule matches if the DNS-SD service name contains "@ printserver":

```
        Browsefilter service @ printserver
```

Matches all domains with "local" in their names, not only "local" but also things like "printlocally.com":

```
        BrowseFilter domain local
```

Examples for rules applying to items of the TXT record: This rule selects PostScript printers, as the "PDL" field in the TXT record contains "postscript" then. This includes also remote CUPS queues which accept PostScript, independent of whether the physical printer behind the CUPS queue accepts PostScript or not.

```
        BrowseFilter pdl postscript
```

Color printers usually contain a "Color" entry set to "T" (for true) in the TXT record. This rule selects them:

```
        BrowseFilter color
```

This is a similar rule to select only duplex (automatic double-sided printing) printers:

```
        BrowseFilter duplex
```

Rules with the NOT option: This rule EXCLUDES printers from all hosts containing "financial" in their names, nice to get rid of the 100s of printers of the financial department:

```
        BrowseFilter NOT host financial
```

Get only monochrome printers ("Color" set to "F", meaning false, in the TXT record):

```
        BrowseFilter NOT color
```

Rules with more advanced use of regular expressions: Only queue names which BEGIN WITH "hum_res_" are accepted now, so we still get "hum_res_mono" or "hum_res_color" but not "old_hum_res_mono" any more:

```
        BrowseFilter name ^hum_res_
```

Server names is accepted if it contains "print_server" OR "graphics_dep_server":

```
        BrowseFilter host print_server|graphics_dep_server
```

"printserver1", "printserver2", and "printserver3", nothing else:

```
        BrowseFilter host ^printserver[1-3]$
```

Printers understanding at least one of PostScript, PCL, or PDF:

```
        BrowseFilter pdl postscript|pcl|pdf
```

Examples for the EXACT option: Only printers from "printserver.local" are accepted:

```
        BrowseFilter EXACT host printserver.local
```

Printers from all servers except "prinserver2.local" are accepted:

```
        BrowseFilter NOT EXACT host prinserver2.local
```

The BrowsePoll directive polls a server for available printers once every 60 seconds. Multiple BrowsePoll directives can be specified to poll multiple servers. The default port to connect to is 631.

```
        BrowsePoll 192.168.7.20

        BrowsePoll 192.168.7.65:631

        BrowsePoll host.example.com:631
```

The BrowseLocalProtocols directive specifies the protocols to use when advertising local shared printers on the network. The default is "none". Control of advertising of local shared printers using dnssd is done by CUPS and configured in /etc/cups/cupsd.conf.

```
        BrowseLocalProtocols none
```

The BrowseRemoteProtocols directive specifies the protocols to use when finding remote shared printers on the network. Multiple protocols can be specified by separating them with spaces. The default is "dnssd".

```
        BrowseRemoteProtocols none

        BrowseRemoteProtocols dnssd
```

The BrowseProtocols directive specifies the protocols to use when finding remote shared printers on the network and advertising local shared printers. Multiple protocols can be specified by separating them with spaces.

```
        BrowseProtocols none

        BrowseProtocols dnssd
```

The DomainSocket directive specifies the domain socket through which the locally running CUPS daemon is accessed. If not specified the standard domain socket of CUPS is used. Use this if you have specified an alternative domain socket for CUPS via a Listen directive in /etc/cups/cupsd.conf. If cups-browsed is not able to access the local CUPS daemon via a domain socket it accesses it via localhost. "None" or "Off" lets cups-browsed not use CUPS' domain socket.

```
        DomainSocket /var/run/cups/cups.sock

        DomainSocket None

        DomainSocket Off
```

Set HTTP timeout (in seconds) for requests sent to local/remote resources Note that too short timeouts can make services getting missed when they are present and operations be unnecessarily repeated and too long timeouts can make operations take too long when the server does not respond.

```
        HttpLocalTimeout 5

        HttpRemoteTimeout 10
```

Set how many retries (N) should cups-browsed do for creating print queues for remote printers which receive timeouts during print queue creation. The printers which are not successfully set up even after N retries, are skipped until the next restart of the service. Note that too many retries can cause high CPU load.

```
        HttpMaxRetries 5
```

The interval between browsing/broadcasting cycles, local and/or remote, can be adjusted with the BrowseInterval directive.

```
        BrowseInterval 60
```

The BrowseTimeout directive determines the amount of time that browsing-related operations are allowed to take in seconds. Notably, adding or removing one printer queue is considered as one operation. The timeout applies to each one of those operations.

```
        BrowseTimeout 300
```

The AllowResharingRemoteCUPSPrinters directive determines whether a print queue pointing to a remote CUPS queue will be re-shared to the local network or not. Since the queues generated using the BrowsePoll directive are also pointing to remote queues, they are also shared automatically if the following option is set. Default is not to share remote queues.

```
        AllowResharingRemoteCUPSPrinters Yes
```

The NewBrowsePollQueuesShared directive determines whether a print queue for a newly discovered printer (discovered by the BrowsePoll directive) will be shared to the local network or not. This directive will only work if AllowResharingRemoteCUPSPrinters is set to yes. Default is not to share printers discovered using BrowsePoll.

```
        NewBrowsePollQueuesShared Yes
```

Set OnlyUnsupportedByCUPS to "Yes" will make cups-browsed not create local queues for remote printers for which CUPS creates queues by itself. These printers are printers advertised via DNS-SD and doing CUPS-supported (currently PWG Raster and Apple Raster) driverless printing, including remote CUPS queues. Queues for other printers (like for legacy PostScript/PCL printers) are always created (depending on the other configuration settings of cups-browsed). With OnlyUnsupportedByCUPS set to "No", cups-browsed creates queues for all printers which it supports, including printers for which CUPS would create queues by itself. Temporary queues created by CUPS will get overwritten. This way it is assured that any extra functionality of cups-browsed will apply to these queues. As queues created by cups-browsed are permanent CUPS queues this setting is also recommended if applications/print dialogs which do not support temporary CUPS queues are installed. This setting is the default.

```
        OnlyUnsupportedByCUPS Yes
```

With UseCUPSGeneratedPPDs set to "Yes" cups-browsed creates queues for IPP printers with PPDs generated by the PPD generator of CUPS and not with the one of cups-browsed. So any new development in CUPS' PPD generator gets available. As CUPS' PPD generator is not directly accessible, we need to make CUPS generate a temporary print queue with the desired PPD. Therefore we can only use these PPDs when our queue replaces a temporary CUPS queue, meaning that the queue is for a printer on which CUPS supports driverless printing (IPP 2.x, PDLs: PDF, PWG Raster, and/or Apple Raster) and that its name is the same as CUPS uses for the temporary queue ("LocalQueueNamingIPPPrinter DNS-SD" must be set). The directive applies only to IPP printers, not to remote CUPS queues, to not break clustering. Setting this directive to "No" lets cups-browsed generate the PPD file. Default setting is "No".

```
        UseCUPSGeneratedPPDs No
```

With the directives LocalQueueNamingRemoteCUPS and LocalQueueNamingIPPPrinter you can determine how the names for local queues generated by cups-browsed are generated, separately for remote CUPS printers and IPP printers. "DNS-SD" (the default in both cases) bases the naming on the service name of the printer's advertised DNS-SD record. This is exactly the same naming scheme as CUPS uses for its temporary queues, so the local queue from cups-browsed prevents CUPS from listing and creating an additional queue. As DNS-SD service names have to be unique, queue names of printers from different servers will also be unique and so there is no automatic clustering for load-balanced printing.

"MakeModel" bases the queue name on the printer's manufacturer and model names. This scheme cups-browsed used formerly for IPP printers.

"RemoteName" is only available for remote CUPS queues and uses the name of the queue on the remote CUPS server as the local queue's name. This makes printers on different CUPS servers with equal queue names automatically forming a load-balancing cluster as CUPS did formerly (CUPS 1.5.x and older) with CUPS-broadcasted remote printers. This scheme cups-browsed used formerly for remote CUPS printers.

```
        LocalQueueNamingRemoteCUPS DNS-SD

        LocalQueueNamingRemoteCUPS MakeModel

        LocalQueueNamingRemoteCUPS RemoteName

        LocalQueueNamingIPPPrinter DNS-SD

        LocalQueueNamingIPPPrinter MakeModel
```

Set DNSSDBasedDeviceURIs to "Yes" if cups-browsed should use DNS-SD-service-name-based device URIs for its local queues, as CUPS also does. These queues use the DNS-SD service name of the discovered printer. With this the URI is independent of network interfaces and ports, giving reliable connections to always the same physical device. This setting is the default. Set DNSSDBasedDeviceURIs to "No" if cups-browsed should use the conventional host-name/IP-based URIs.

Note that this option has only influence on URIs for printers discovered via DNS-SD, not via BrowsePoll. Those printers get always assigned the conventional URIs.

```
        DNSSDBasedDeviceURIs Yes
```

Set IPBasedDeviceURIs to "Yes" if cups-browsed should create its local queues with device URIs with the IP addresses instead of the host names of the remote servers. This mode is there for any problems with host name resolution in the network, especially also if avahi-daemon is only run for printer discovery and already stopped while still printing. By default this mode is turned off, meaning that we use URIs with host names. Note that the IP addresses depend on the network interface through which the printer is accessed. So do not use IP-based URIs on systems with many network interfaces and where interfaces can appear and disappear frequently.

This mode could also be useful for development and debugging.

If you prefer IPv4 or IPv6 IP addresses in the URIs, you can set IPBasedDeviceURIs to "IPv4" to only get IPv4 IP addresses or IPBasedDeviceURIs to "IPv6" to only get IPv6 IP addresses.

```
        IPBasedDeviceURIs No

        IPBasedDeviceURIs Yes

        IPBasedDeviceURIs IPv4

        IPBasedDeviceURIs IPv6
```

Set CreateRemoteRawPrinterQueues to "Yes" to let cups-browsed also create local queues pointing to remote raw CUPS queues. Normally, only queues pointing to remote queues with PPD/driver are created as we do not use drivers on the client side, but in some cases accessing a remote raw queue can make sense, for example if the queue forwards the jobs by a special backend like Tea4CUPS.

```
        CreateRemoteRawPrinterQueues Yes
```

cups-browsed by default creates local print queues for each shared CUPS print queue which it discovers on remote machines in the local network(s). Set CreateRemoteCUPSPrinterQueues to "No" if you do not want cups-browsed to do this. For example you can set cups-browsed to only create queues for IPP network printers setting CreateIPPPrinterQueues not to "No" and CreateRemoteCUPSPrinterQueues to "No".

```
        CreateRemoteCUPSPrinterQueues No
```

Set CreateIPPPrinterQueues to "All" to let cups-browsed discover IPP network printers (native printers, not CUPS queues) with known page description languages (PWG Raster, PDF, PostScript, PCL XL, PCL 5c/e) in the local network and auto-create print queues for them. Set CreateIPPPrinterQueues to "Everywhere" to let cups-browsed discover IPP Everywhere printers in the local network (native printers, not CUPS queues) and auto-create print queues for them.

Set CreateIPPPrinterQueues to "AppleRaster" to let cups-browsed discover Apple Raster printers in the local network (native printers, not CUPS queues) and auto-create print queues for them.

Set CreateIPPPrinterQueues to "Driverless" to let cups-browsed discover printers designed for driverless use (currently IPP Everywhere and Apple Raster) in the local network (native printers, not CUPS queues) and auto-create print queues for them.

Set CreateIPPPrinterQueues to "LocalOnly" to auto-create print queues only for local printers made available as IPP printers. These are for example IPP-over-USB printers, made available via ippusbxd(8). This is the default.

Set CreateIPPPrinterQueues to "No" to not auto-create print queues for IPP network printers.

If queues with PPD file are created (see IPPPrinterQueueType directive below) the PPDs are auto-generated by cups-browsed based on properties of the printer polled via IPP. In case of missing information, info from the Bonjour record is used asd as last mean default values.

If queues without PPD (see IPPPrinterQueueType directive below) are created clients have to IPP-poll the capabilities of the printer and send option settings as standard IPP attributes. Then we do not poll the capabilities by ourselves to not wake up the printer from power-saving mode when creating the queues. Jobs have to be sent in one of PDF, PWG Raster, or JPEG format. Other formats are not accepted.

This functionality is primarily for mobile devices running CUPS to not need a printer setup tool nor a collection of printer drivers and PPDs.

```
        CreateIPPPrinterQueues No

        CreateIPPPrinterQueues LocalOnly

        CreateIPPPrinterQueues Everywhere

        CreateIPPPrinterQueues AppleRaster

        CreateIPPPrinterQueues Everywhere AppleRaster

        CreateIPPPrinterQueues Driverless

        CreateIPPPrinterQueues All
```

If cups-browsed is automatically creating print queues for native IPP network printers ("CreateIPPPrinterQueues Yes"), the type of queue to be created can be selected by the "IPPPrinterQueueType" directive. The "PPD" (default) setting makes queues with PPD file being created. With "Interface" or "NoPPD" the queue is created with a System V interface script (Not supported with CUPS 2.2.x or later). "Auto" is for backward compatibility and also lets queues with PPD get created.

```
        IPPPrinterQueueType PPD

        IPPPrinterQueueType NoPPD

        IPPPrinterQueueType Interface

        IPPPrinterQueueType Auto
```

The NewIPPPrinterQueuesShared directive determines whether a print queue for a newly discovered IPP network printer (not remote CUPS queue) will be shared to the local network or not. This is only valid for newly discovered printers. For printers discovered in an earlier cups-browsed session, cups-browsed will remember whether the printer was shared, so changes by the user get conserved. Default is not to share newly discovered IPP printers.

```
        NewIPPPrinterQueuesShared Yes
```

How to handle the print queues cups-browsed creates when cups-browsed is shut down: "KeepGeneratedQueuesOnShutdown No" makes the queues being removed. This makes sense as these queues only work while cups-browsed is running. cups-browsed has to determine to which member printer of a cluster to pass on the job.

"KeepGeneratedQueuesOnShutdown Yes" (the default) makes the queues not being removed. This is the recommended setting for a system where cups-browsed is permanently running and only stopped for short times (like log rotation) or on shutdown. This avoids the re-creation of the queues when cups-browsed is restarted, which often causes a clutter of CUPS notifications on the desktop.

```
        KeepGeneratedQueuesOnShutdown No
```

If there is more than one remote CUPS printer whose local queue would get the same name and AutoClustering is set to "Yes" (the default) only one local queue is created which makes up a load-balancing cluster of the remote printers which would get this queue name (implicit class). This means that when several jobs are sent to this queue they get distributed between the printers, using the method chosen by the LoadBalancing directive. Note that the forming of clusters depends on the naming scheme for local queues created by cups-browsed. If you have set LocalQueueNamingRemoteCUPS to "DNSSD" you will not get automatic clustering as the DNS-SD service names are always unique. With LocalQueueNamingRemoteCUPS set to "RemoteName" local queues are named as the CUPS queues on the remote servers are named and so equally named queues on different servers get clustered (this is how CUPS did it in version 1.5.x or older). LocalQueueNamingRemoteCUPS set to "MakeModel" makes remote printers of the same model get clustered. Note that then a cluster can contain more than one queue of the same server.

With AutoClustering set to "No", for each remote CUPS printer an individual local queue is created, and to avoid name clashes when using the LocalQueueNamingRemoteCUPS settings "RemoteName" or "MakeModel" "@<server name>" is added to the local queue name.

Only remote CUPS printers get clustered, not IPP network printers or IPP-over-USB printers.

```
        AutoClustering Yes

        AutoClustering No
```

Load-balancing printer cluster formation can also be manually controlled by defining explicitly which remote CUPS printers should get clustered together. This is done by the "Cluster" directive:

```
        Cluster <QUEUENAME>: <EXPRESSION1> <EXPRESSION2> ...

        Cluster <QUEUENAME>
```

If no expressions are given, <QUEUENAME> is used as the first and only expression for this cluster. Discovered printers are matched against all the expressions of all defined clusters. The first expression which matches the discovered printer determines to which cluster it belongs. Note that this way a printer can only belong to one cluster. Once matched, further cluster definitions will not checked any more.

With the first printer matching a cluster's expression a local queue with the name <QUEUENAME> is created. If more printers are discovered and match this cluster, they join the cluster. Printing to this queue prints to all these printers in a load-balancing manner, according to to the setting of the LoadBalancing directive.

Each expression must be a string of characters without spaces. If spaces are needed, replace them by underscores ('_').

An expression can be matched in three ways:

```
    1. By the name of the CUPS queue on the remote server

    2. By make and model name of the remote printer

    3. By the DNS-SD service name of the remote printer
```

Note that the matching is done case-insensitively and any group of non-alphanumerical characters is replaced by a single underscore. So if an expression is "HP_DeskJet_2540" and the remote server reports "hp Deskjet-2540" the printer gets matched to this cluster.

If "AutoClustering" is not set to "No" both your manual cluster definitions will be followed and automatic clustering of equally-named remote queues will be performed. If a printer matches in both categories the match to the manually defined cluster has priority. Automatic clustering of equally-named remote printers is not performed if there is a manually defined cluster with this name (at least as the printers do not match this cluster).

Examples:

To cluster all remote CUPS queues named "laserprinter" in your local network but not cluster any other equally-named remote CUPS printers use (Local queue will get named "laserprinter"):

```
        AutoClustering No

        Cluster laserprinter
```

To cluster all remote CUPS queues of HP LaserJet 4050 printers in a local queue named "LJ4050":

```
        Cluster LJ4050: HP_LaserJet_4050
```

As DNS-SD service names are unique in a network you can create a cluster from exactly specified printers (spaces replaced by underscores):

```
        Cluster hrdep: oldlaser_@_hr-server1 newlaser_@_hr-server2
```

The LoadBalancing directive switches between two methods of handling load balancing between equally-named remote queues which are represented by one local print queue making up a cluster of them (implicit class). The two methods are:

Queuing of jobs on the client (LoadBalancing QueueOnClient):

Here we queue up the jobs on the client and regularly check the clustered remote print queues. If we find an idle queue, we pass on a job to it.

This is also the method which CUPS uses for classes. Advantage is a more even distribution of the job workload on the servers (especially if the printing speed of the servers is very different), and if a server fails, there are not several jobs stuck or lost. Disadvantage is that if one takes the client (laptop, mobile phone, ...) out of the local network, printing stops with the jobs waiting in the local queue.

Queuing of jobs on the servers (LoadBalancing QueueOnServers):

Here we check the number of jobs on each of the clustered remote printers and send an incoming job immediately to the remote printer with the lowest amount of jobs in its queue. This way no jobs queue up locally, all jobs which are waiting are waiting on one of the remote servers.

Not having jobs waiting locally has the advantage that we can take the local machine from the network and all jobs get printed. Disadvantage is that if a server with a full queue of jobs goes away, the jobs go away, too.

Default is queuing the jobs on the client as this is what CUPS does with classes.

```
        LoadBalancing QueueOnClient

        LoadBalancing QueueOnServers
```

With the DefaultOptions directive one or more option settings can be defined to be applied to every print queue newly created by cups-browsed. Each option is supplied as one supplies options with the "-o" command line argument to the "lpadmin" command (Run "man lpadmin" for more details). More than one option can be supplied separating the options by spaces. By default no option settings are pre-defined. Note that print queues which cups-browsed already created before remember their previous settings and so these settings do not get applied.

```
        DefaultOptions Option1=Value1 Option2=Value2 Option3 noOption4
```

The AutoShutdown directive specifies whether cups-browsed should automatically terminate when it has no local raw queues set up pointing to any discovered remote printers or no jobs on such queues depending on AutoShutdownOn setting (auto shutdown mode). Setting it to "On" activates the auto-shutdown mode, setting it to "Off" deactivates it (the default). The special mode "avahi" turns auto shutdown off while avahi-daemon is running and on when avahi-daemon stops. This allows running cups-browsed on-demand when avahi-daemon is run on-demand.

```
        AutoShutdown Off

        AutoShutdown On

        AutoShutdown avahi
```

The AutoShutdownOn directive determines what event cups-browsed considers as inactivity in auto shutdown mode. "NoQueues" (the default) means that auto shutdown is initiated when there are no queues for discovered remote printers generated by cups-browsed any more. "NoJobs" means that all queues generated by cups-browsed are without jobs.

```
        AutoShutdownOn NoQueues

        AutoShutdownOn NoJobs
```

DebugLogFileSize defines the maximum size possible (in KBytes) of the log files (cups-browsed_log and cups-browsed_previous_logs) that is created using cups-browsed in the debugging mode. Setting its value to 0 would turn off any restriction on the size of the file.

```
        DebugLogFileSize 300
```

The AutoShutdownTimeout directive specifies after how many seconds without local raw queues set up pointing to any discovered remote printers or jobs on these queues cups-browsed should actually shut down in auto shutdown mode. Default is 30 seconds, 0 means immediate shutdown.

```
        AutoShutdownTimeout 20
```

NotifLeaseDuration defines how long the D-BUS subscription created by cups-browsed in cupsd will last before cupsd cancels it. The default value is 1 day in seconds - 86400. The subscription renewal is set to happen after half of NotifLeaseDuration passed. The D-BUS notifications are used for watching over queues and doing specific actions when a D-BUS notification comes.

```
        NotifLeaseDuration 86400
```

## SEE ALSO
cups-browsed(8)

/usr/share/doc/cups-browsed/README.gz

## AUTHOR
The authors of cups-browsed are listed in /usr/share/doc/cups-browsed/AUTHORS.

This manual page was written for the Debian Project, but it may be used by others.