Printing Services (GNU Guix Reference Manual)

10.8.7 Printing Services

The (gnu services cups) module provides a Guix service definition for the CUPS printing service. To add printer support to a Guix system, add a cups-service to the operating system definition:

Scheme Variable: cups-service-type

The service type for the CUPS print server. Its value should be a valid CUPS configuration (see below). To use the default settings, simply write:

(service cups-service-type)

The CUPS configuration controls the basic things about your CUPS installation: what interfaces it listens on, what to do if a print job fails, how much logging to do, and so on. To actually add a printer, you have to visit the http://localhost:631 URL, or use a tool such as GNOME’s printer configuration services. By default, configuring a CUPS service will generate a self-signed certificate if needed, for secure connections to the print server.

Suppose you want to enable the Web interface of CUPS and also add support for Epson printers via the epson-inkjet-printer-escpr package and for HP printers via the hplip-minimal package. You can do that directly, like this (you need to use the (gnu packages cups) module):

(service cups-service-type
         (cups-configuration
           (web-interface? #t)
           (extensions
             (list cups-filters epson-inkjet-printer-escpr hplip-minimal))))

Note: If you wish to use the Qt5 based GUI which comes with the hplip package then it is suggested that you install the hplip package, either in your OS configuration file or as your user.

The available configuration parameters follow. Each parameter definition is preceded by its type; for example, ‘string-list foo’ indicates that the foo parameter should be specified as a list of strings. There is also a way to specify the configuration as a string, if you have an old cupsd.conf file that you want to port over from some other system; see the end for more details.

Available cups-configuration fields are:

cups-configuration parameter: package cups: The CUPS package.

cups-configuration parameter: package-list extensions (default: (list brlaser cups-filters epson-inkjet-printer-escpr foomatic-filters hplip-minimal splix)): Drivers and other extensions to the CUPS package.

cups-configuration parameter: files-configuration files-configuration

Configuration of where to write logs, what directories to use for print spools, and related privileged configuration parameters.

Available files-configuration fields are:

files-configuration parameter: log-location access-log

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, as in /var/log/cups/%s-access_log.

Defaults to ‘"/var/log/cups/access_log"’.

files-configuration parameter: file-name cache-dir

Where CUPS should cache data.

Defaults to ‘"/var/cache/cups"’.

files-configuration parameter: string config-file-perm

Specifies the permissions for all configuration files that the scheduler writes.

Note that 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.

Defaults to ‘"0640"’.

files-configuration parameter: log-location error-log

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, as in /var/log/cups/%s-error_log.

Defaults to ‘"/var/log/cups/error_log"’.

files-configuration parameter: string fatal-errors

Specifies which errors are fatal, causing the scheduler to exit. 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.

Defaults to ‘"all -browse"’.

files-configuration parameter: boolean file-device?

Specifies whether the file pseudo-device can be used for new printer queues. The URI file:///dev/null is always allowed.

Defaults to ‘#f’.

files-configuration parameter: string group

Specifies the group name or ID that will be used when executing external programs.

Defaults to ‘"lp"’.

files-configuration parameter: string log-file-perm

Specifies the permissions for all log files that the scheduler writes.

Defaults to ‘"0644"’.

files-configuration parameter: log-location page-log

Defines the page log filename. Specifying a blank filename disables page 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, as in /var/log/cups/%s-page_log.

Defaults to ‘"/var/log/cups/page_log"’.

files-configuration parameter: string remote-root

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

Defaults to ‘"remroot"’.

files-configuration parameter: file-name request-root

Specifies the directory that contains print jobs and other HTTP request data.

Defaults to ‘"/var/spool/cups"’.

files-configuration parameter: sandboxing sandboxing

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

Defaults to ‘strict’.

files-configuration parameter: file-name server-keychain

Specifies the location of TLS certificates and private keys. CUPS will look for public and private keys in this directory: .crt files for PEM-encoded certificates and corresponding .key files for PEM-encoded private keys.

Defaults to ‘"/etc/cups/ssl"’.

files-configuration parameter: file-name server-root

Specifies the directory containing the server configuration files.

Defaults to ‘"/etc/cups"’.

files-configuration parameter: boolean sync-on-close?

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

Defaults to ‘#f’.

files-configuration parameter: space-separated-string-list system-group: Specifies the group(s) to use for @SYSTEM group authentication.

files-configuration parameter: file-name temp-dir

Specifies the directory where temporary files are stored.

Defaults to ‘"/var/spool/cups/tmp"’.

files-configuration parameter: string user

Specifies the user name or ID that is used when running external programs.

Defaults to ‘"lp"’.

files-configuration parameter: string set-env

Set the specified environment variable to be passed to child processes.

Defaults to ‘"variable value"’.

cups-configuration parameter: access-log-level access-log-level

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.

Defaults to ‘actions’.

cups-configuration parameter: boolean auto-purge-jobs?

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

Defaults to ‘#f’.

cups-configuration parameter: comma-separated-string-list browse-dns-sd-sub-types

Specifies a list of DNS-SD sub-types to advertise for each shared printer. For example, ‘"_cups" "_print"’ will tell network clients that both CUPS sharing and IPP Everywhere are supported.

Defaults to ‘"_cups"’.

cups-configuration parameter: browse-local-protocols browse-local-protocols

Specifies which protocols to use for local printer sharing.

Defaults to ‘dnssd’.

cups-configuration parameter: boolean browse-web-if?

Specifies whether the CUPS web interface is advertised.

Defaults to ‘#f’.

cups-configuration parameter: boolean browsing?

Specifies whether shared printers are advertised.

Defaults to ‘#f’.

cups-configuration parameter: string classification

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.

Defaults to ‘""’.

cups-configuration parameter: boolean classify-override?

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

Defaults to ‘#f’.

cups-configuration parameter: default-auth-type default-auth-type

Specifies the default type of authentication to use.

Defaults to ‘Basic’.

cups-configuration parameter: default-encryption default-encryption

Specifies whether encryption will be used for authenticated requests.

Defaults to ‘Required’.

cups-configuration parameter: string default-language

Specifies the default language to use for text and web content.

Defaults to ‘"en"’.

cups-configuration parameter: string default-paper-size

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"’.

Defaults to ‘"Auto"’.

cups-configuration parameter: string default-policy

Specifies the default access policy to use.

Defaults to ‘"default"’.

cups-configuration parameter: boolean default-shared?

Specifies whether local printers are shared by default.

Defaults to ‘#t’.

cups-configuration parameter: non-negative-integer dirty-clean-interval

Specifies the delay for updating of configuration and state files, in seconds. A value of 0 causes the update to happen as soon as possible, typically within a few milliseconds.

Defaults to ‘30’.

cups-configuration parameter: error-policy error-policy

Specifies what to do when an error occurs. Possible values are abort-job, which will discard the failed print job; retry-job, which will retry the job at a later time; retry-current-job, which retries the failed job immediately; and stop-printer, which stops the printer.

Defaults to ‘stop-printer’.

cups-configuration parameter: non-negative-integer filter-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.

Defaults to ‘0’.

cups-configuration parameter: non-negative-integer filter-nice

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

Defaults to ‘0’.

cups-configuration parameter: host-name-lookups host-name-lookups

Specifies whether to do reverse lookups on connecting clients. The double setting causes cupsd 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. Only set this option to #t or double if absolutely required.

Defaults to ‘#f’.

cups-configuration parameter: non-negative-integer job-kill-delay

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

Defaults to ‘30’.

cups-configuration parameter: non-negative-integer job-retry-interval

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 or retry-current-job.

Defaults to ‘30’.

cups-configuration parameter: non-negative-integer job-retry-limit

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 or retry-current-job.

Defaults to ‘5’.

cups-configuration parameter: boolean keep-alive?

Specifies whether to support HTTP keep-alive connections.

Defaults to ‘#t’.

cups-configuration parameter: non-negative-integer limit-request-body

Specifies the maximum size of print files, IPP requests, and HTML form data. A limit of 0 disables the limit check.

Defaults to ‘0’.

cups-configuration parameter: multiline-string-list listen: Listens on the specified interfaces for connections. Valid values are of the form address:port, where address is either an IPv6 address enclosed in brackets, an IPv4 address, or * to indicate all addresses. Values can also be file names of local UNIX domain sockets. The Listen directive is similar to the Port directive but allows you to restrict access to specific interfaces or networks.

cups-configuration parameter: non-negative-integer listen-back-log

Specifies the number of pending connections that will be allowed. This normally only affects very busy servers that have reached the MaxClients limit, but can also be triggered by large numbers of simultaneous connections. When the limit is reached, the operating system will refuse additional connections until the scheduler can accept the pending ones.

Defaults to ‘128’.

cups-configuration parameter: location-access-control-list location-access-controls

Specifies a set of additional access controls.

Available location-access-controls fields are:

location-access-controls parameter: file-name path: Specifies the URI path to which the access control applies.

location-access-controls parameter: access-control-list access-controls

Access controls for all access to this path, in the same format as the access-controls of operation-access-control.

Defaults to ‘()’.

location-access-controls parameter: method-access-control-list method-access-controls

Access controls for method-specific access to this path.

Defaults to ‘()’.

Available method-access-controls fields are:

method-access-controls parameter: boolean reverse?

If #t, apply access controls to all methods except the listed methods. Otherwise apply to only the listed methods.

Defaults to ‘#f’.

method-access-controls parameter: method-list methods

Methods to which this access control applies.

Defaults to ‘()’.

method-access-controls parameter: access-control-list access-controls

Access control directives, as a list of strings. Each string should be one directive, such as ‘"Order allow,deny"’.

Defaults to ‘()’.

cups-configuration parameter: non-negative-integer log-debug-history

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.

Defaults to ‘100’.

cups-configuration parameter: log-level log-level

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

Defaults to ‘info’.

cups-configuration parameter: log-time-format log-time-format

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

Defaults to ‘standard’.

cups-configuration parameter: non-negative-integer max-clients

Specifies the maximum number of simultaneous clients that are allowed by the scheduler.

Defaults to ‘100’.

cups-configuration parameter: non-negative-integer max-clients-per-host

Specifies the maximum number of simultaneous clients that are allowed from a single address.

Defaults to ‘100’.

cups-configuration parameter: non-negative-integer max-copies

Specifies the maximum number of copies that a user can print of each job.

Defaults to ‘9999’.

cups-configuration parameter: non-negative-integer max-hold-time

Specifies the maximum time a job may remain in the indefinite hold state before it is canceled. A value of 0 disables cancellation of held jobs.

Defaults to ‘0’.

cups-configuration parameter: non-negative-integer max-jobs

Specifies the maximum number of simultaneous jobs that are allowed. Set to 0 to allow an unlimited number of jobs.

Defaults to ‘500’.

cups-configuration parameter: non-negative-integer max-jobs-per-printer

Specifies the maximum number of simultaneous jobs that are allowed per printer. A value of 0 allows up to MaxJobs jobs per printer.

Defaults to ‘0’.

cups-configuration parameter: non-negative-integer max-jobs-per-user

Specifies the maximum number of simultaneous jobs that are allowed per user. A value of 0 allows up to MaxJobs jobs per user.

Defaults to ‘0’.

cups-configuration parameter: non-negative-integer max-job-time

Specifies the maximum time a job may take to print before it is canceled, in seconds. Set to 0 to disable cancellation of “stuck” jobs.

Defaults to ‘10800’.

cups-configuration parameter: non-negative-integer max-log-size

Specifies the maximum size of the log files before they are rotated, in bytes. The value 0 disables log rotation.

Defaults to ‘1048576’.

cups-configuration parameter: non-negative-integer multiple-operation-timeout

Specifies the maximum amount of time to allow between files in a multiple file print job, in seconds.

Defaults to ‘900’.

cups-configuration parameter: string page-log-format

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:

‘%%’: insert a single percent character
‘%{name}’: insert the value of the specified IPP attribute
‘%C’: insert the number of copies for the current page
‘%P’: insert the current page number
‘%T’: insert the current date and time in common log format
‘%j’: insert the job ID
‘%p’: insert the printer name
‘%u’: insert the username

A value of the empty string 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.

Defaults to ‘""’.

cups-configuration parameter: environment-variables environment-variables

Passes the specified environment variable(s) to child processes; a list of strings.

Defaults to ‘()’.

cups-configuration parameter: policy-configuration-list policies

Specifies named access control policies.

Available policy-configuration fields are:

policy-configuration parameter: string name: Name of the policy.

policy-configuration parameter: string job-private-access

Specifies an access list for a job’s private values. @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 system-group field of the files-configuration, which is reified into the cups-files.conf(5) file. Other possible elements of the access list include specific user names, and @group to indicate members of a specific group. The access list may also be simply all or default.

Defaults to ‘"@OWNER @SYSTEM"’.

policy-configuration parameter: string job-private-values

Specifies the list of job values to make private, or all, default, or none.

Defaults to ‘"job-name job-originating-host-name job-originating-user-name phone"’.

policy-configuration parameter: string subscription-private-access

Specifies an access list for a subscription’s private values. @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 system-group field of the files-configuration, which is reified into the cups-files.conf(5) file. Other possible elements of the access list include specific user names, and @group to indicate members of a specific group. The access list may also be simply all or default.

Defaults to ‘"@OWNER @SYSTEM"’.

policy-configuration parameter: string subscription-private-values

Specifies the list of job values to make private, or all, default, or none.

Defaults to ‘"notify-events notify-pull-method notify-recipient-uri notify-subscriber-user-name notify-user-data"’.

policy-configuration parameter: operation-access-control-list access-controls

Access control by IPP operation.

Defaults to ‘()’.

cups-configuration parameter: boolean-or-non-negative-integer preserve-job-files

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. Otherwise a boolean value applies indefinitely.

Defaults to ‘86400’.

cups-configuration parameter: boolean-or-non-negative-integer preserve-job-history

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 #t, the job history is preserved until the MaxJobs limit is reached.

Defaults to ‘#t’.

cups-configuration parameter: non-negative-integer reload-timeout

Specifies the amount of time to wait for job completion before restarting the scheduler.

Defaults to ‘30’.

cups-configuration parameter: string rip-cache

Specifies the maximum amount of memory to use when converting documents into bitmaps for a printer.

Defaults to ‘"128m"’.

cups-configuration parameter: string server-admin

Specifies the email address of the server administrator.

Defaults to ‘"root@localhost.localdomain"’.

cups-configuration parameter: host-name-list-or-* server-alias

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 *.

Defaults to ‘*’.

cups-configuration parameter: string server-name

Specifies the fully-qualified host name of the server.

Defaults to ‘"localhost"’.

cups-configuration parameter: server-tokens server-tokens

Specifies what information is included in the Server header of HTTP responses. None disables the Server header. ProductOnly reports CUPS. Major reports CUPS 2. Minor reports CUPS 2.0. Minimal reports CUPS 2.0.0. OS reports CUPS 2.0.0 (uname) where uname is the output of the uname command. Full reports CUPS 2.0.0 (uname) IPP/2.0.

Defaults to ‘Minimal’.

cups-configuration parameter: multiline-string-list ssl-listen

Listens on the specified interfaces for encrypted connections. Valid values are of the form address:port, where address is either an IPv6 address enclosed in brackets, an IPv4 address, or * to indicate all addresses.

Defaults to ‘()’.

cups-configuration parameter: ssl-options ssl-options

Sets encryption options. 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, and enhanced when Deny options are used. 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.

Defaults to ‘()’.

cups-configuration parameter: boolean strict-conformance?

Specifies whether the scheduler requires clients to strictly adhere to the IPP specifications.

Defaults to ‘#f’.

cups-configuration parameter: non-negative-integer timeout

Specifies the HTTP request timeout, in seconds.

Defaults to ‘900’.

cups-configuration parameter: boolean web-interface?

Specifies whether the web interface is enabled.

Defaults to ‘#f’.

At this point you’re probably thinking “oh dear, Guix manual, I like you but you can stop already with the configuration options”. Indeed. However, one more point: it could be that you have an existing cupsd.conf that you want to use. In that case, you can pass an opaque-cups-configuration as the configuration of a cups-service-type.

Available opaque-cups-configuration fields are:

opaque-cups-configuration parameter: package cups: The CUPS package.

opaque-cups-configuration parameter: string cupsd.conf: The contents of the cupsd.conf, as a string.

opaque-cups-configuration parameter: string cups-files.conf: The contents of the cups-files.conf file, as a string.

For example, if your cupsd.conf and cups-files.conf are in strings of the same name, you could instantiate a CUPS service like this:

(service cups-service-type
         (opaque-cups-configuration
           (cupsd.conf cupsd.conf)
           (cups-files.conf cups-files.conf)))