- Description
- Setup
- Usage - A quick start guide
- Bricolage - Hackish ways of resource creation
- Reference - The documentation of all features available
- Limitations
- Contributing - Guidelines for users and developers
This module installs, configures, and manages the Common Unix Printing System (CUPS) service.
It provides Puppet types to install, configure, and manage CUPS printer queues and classes.
Key design goals include locale independence and test driven development.
-
The CUPS packages will be installed.
-
The CUPS service will be enabled and launched.
-
The files in
/etc/cups/
will be modified using CUPS command line utilities. -
The file
/etc/cups/lpoptions
will be deleted. See the section on limitations for details.
This module is written for and tested on systems using
-
Puppet Agent
~> 4.0
-
CUPS
~> 1.5
or 2.x
It might also work with CUPS versions prior to 1.5 after manually installing
the ipptool
command line utility.
First you need to install this module. One way to do this is
puppet module install leoarnold-cups
All resources in this module require the CUPS daemon to be installed and configured in a certain way.
To ensure these preconditions you should include the main cups
class wherever you use this module:
include '::cups'
See the section on the cups
class for details.
Adding printer or class resources is described in the section on usage.
In this section, you will learn the straightforward way to set up CUPS queues from scratch. If the queues are already installed on the node, you can easily obtain a manifest with their current configuration by running
puppet resource cups_queue
and adjust it following the instructions on configuring queues.
There are several ways to set up a printer queue in CUPS. This section provides the minimal manifest for each method.
Note These minimal manifests will not update or change the PPD file on already existing queues, as CUPS does not provide a robust way to determine how the queue was installed. See however the section on changing the driver for a workaround.
If you are unsure which way to choose, we recommend to set up the printer
using the tools provided by your operating system (or the CUPS web interface),
then take the corresponding PPD file from /etc/cups/ppd/
and use the ppd
method.
Minimal printer manifests:
-
Creating a local raw printer:
include '::cups' cups_queue { 'MinimalRaw': ensure => 'printer', uri => 'lpd://192.168.2.105/binary_p1' # Replace with your printer's URI }
To configure this queue see the section on setting the usual options or the type reference.
-
Using a suitable model from the output of the command
lpinfo -m
on the node:include '::cups' cups_queue { 'MinimalModel': ensure => 'printer', model => 'drv:///sample.drv/generic.ppd', uri => 'lpd://192.168.2.105/binary_p1' # Replace with your printer's URI }
To configure this queue see the section on setting the usual options or the type reference.
-
Using a custom PPD file:
include '::cups' cups_queue { 'MinimalPPD': ensure => 'printer', ppd => '/usr/share/cups/model/myprinter.ppd', uri => 'lpd://192.168.2.105/binary_p1' # Replace with your printer's URI }
To configure this queue see the section on setting the usual options or the type reference.
In a master-agent setting, you could transfer the PPD file to the client using a
file
resourcefile { '/usr/share/cups/model/myprinter.ppd': ensure => 'file', source => 'puppet:///modules/myModule/myprinter.ppd' }
which will be autorequired by
Cups_queue['MinimalPrinter']
. -
Using a System V interface script:
include '::cups' cups_queue { 'MinimalInterface': ensure => 'printer', interface => '/usr/share/cups/model/myprinter.sh', uri => 'lpd://192.168.2.105/binary_p1' # Replace with your printer's URI }
To configure this queue see the section on setting the usual options or the type reference.
In a master-agent setting, you could transfer the interface script to the client using a
file
resourcefile { '/usr/share/cups/model/myprinter.sh': ensure => 'file', source => 'puppet:///modules/myModule/myprinter.sh' }
which will be autorequired by
Cups_queue['MinimalPrinter']
.
When a printer queue is already present and managed using a PPD file, it is generally hard to tell which model or PPD file was used to install the queue. Nevertheless it might become necessary to change the model or update the PPD file without changing the queue name, e.g. because the PPD file contains some login credentials.
This module introduces a way to update the driver (i.e. force a reinstall)
through syncing the make_and_model
property, which defaults to
-
the
NickName
(fallbackModelName
) value from the printer's PPD file in/etc/cups/ppd/
if the printer was installed using a PPD file or a model. -
Local System V Printer
if the printer uses a System V interface script. -
Local Raw Printer
for raw print queues.
Example: On the node, running puppet resource cups_queue Office
returns
cups_queue { 'Office':
ensure => 'printer',
make_and_model => 'HP Color LaserJet 4730mfp Postscript (recommended)',
...
}
and you would like to
-
use a different model
$ lpinfo -m | grep 4730mfp ... drv:///hpcups.drv/hp-color_laserjet_4730mfp-pcl3.ppd HP Color LaserJet 4730mfp pcl3, hpcups 3.14.3 postscript-hp:0/ppd/hplip/HP/hp-color_laserjet_4730mfp-ps.ppd HP Color LaserJet 4730mfp Postscript (recommended) ...
then you just need to adapt the manifest from above to
cups_queue { 'Office': ensure => 'printer', model => 'drv:///hpcups.drv/hp-color_laserjet_4730mfp-pcl3.ppd', make_and_model => 'HP Color LaserJet 4730mfp pcl3, hpcups 3.14.3', ... }
-
use a custom PPD file instead which contains the line
*NickName: "HP Color LaserJet 4730mfp Postscript (MyCompany v2)"
then you just need to adapt the manifest from above to
cups_queue { 'Office': ensure => 'printer', ppd => '/usr/share/cups/model/hp4730v2.ppd', make_and_model => 'HP Color LaserJet 4730mfp Postscript (MyCompany v2)', ... }
-
use a System V interface script, then you just need to adapt the manifest from above to
cups_queue { 'Office': ensure => 'printer', interface => '/usr/share/cups/model/myprinter.sh', make_and_model => 'Local System V Printer', ... }
This will, however, not work if the printer was already using a System V interface script (and hence the
make_and_model
would not change). Instead, you can just sync the script right to the place where CUPS expects it:include '::cups' file { '/etc/cups/interfaces/Office': ensure => 'file', owner => 'root', group => 'root', mode => '0755', source => 'puppet:///modules/myModule/myprinter.sh' } cups_queue { 'Office': ensure => 'printer', interface => '/etc/cups/interfaces/Office', ... }
-
make it a raw queue. Then you just need to adapt the manifest from above to
cups_queue { 'Office': ensure => 'printer', make_and_model => 'Local Raw Printer', ... }
When defining a printer class, it is mandatory to also define its member printers in the same catalog:
include '::cups'
cups_queue { 'MinimalClass':
ensure => 'class',
members => ['Office', 'Warehouse']
}
cups_queue { 'Office':
ensure => 'printer',
...
}
cups_queue { 'Warehouse':
ensure => 'printer',
...
}
The Cups_queue['MinimalClass']
resource will autorequire its member resources Cups_queue['Office', 'Warehouse']
.
Once you have your minimal printer or class manifest, you will need to apply some configuration.
Job handling:
In CUPS, newly installed queues are disabled and rejecting by default, which can lead to confusion at times.
The corresponding cups_queue
properties are:
-
accepting
: Should incoming jobs be enqueued or rejected? -
enabled
: Should pending jobs be sent to the device or kept pending?
If you want your print queues to "just work", you should set both to true
.
This module does not set default values by itself, since it might be of disadvantage in a professional copy shop environment.
Option defaults: Sometimes you need to set some default values for CUPS or vendor options of a print queue, e.g. to enable Duplex to save trees or because you use A4 paper instead of US Letter.
To see all vendor options and their possible values for the queue Office
, you can use lpoptions
:
$ lpoptions -p Office -l
PageSize/Media Size: *Letter Legal Executive Tabloid A3 A4 A5 B5 EnvISOB5 Env10 EnvC5 EnvDL EnvMonarch
InputSlot/Media Source: *Default Upper Manual
Duplex/2-Sided Printing: *None DuplexNoTumble DuplexTumble
Option1/Duplexer: *False True
The asterisk (*) indicates the current value. Use this to adapt your manifest
cups_queue { 'Office':
...
options => {
'Duplex' => 'DuplexNoTumble',
'PageSize' => 'A4',
}
}
You only need to provide values for options you actually care about.
Access control: Of course you want your boss Mr. Lumbergh, the secretary Nina and every member of the workers' council to be able to print to the office printer from every node. But all others should be denied to use this printer.
Assuming they respectively have the user accounts lumbergh
, nina
, and the user group council
,
this can be achieved by:
cups_queue { 'Office':
...
access => {
'policy' => 'allow',
'users' => ['lumbergh', 'nina', '@council'],
}
}
Note that group names must be prefixed with an @
sign.
Changing the policy to deny
would deny all users
, but allow everybody else.
Furthermore, you can unset all restrictions by using
cups_queue { 'Office':
...
access => {
'policy' => 'allow',
'users' => ['all'],
}
}
because all
is interpreted by CUPS as a wildcard, not as an account name.
Now that you have created manifest for all your queues, you may want to set the default destination.
class { '::cups'
default_queue => 'Office',
}
This will require the resource Cups_queue['Office']
to be defined in the catalog.
To find out about all options available for Class['::cups']
see the section below.
For your convenience, this module establishes many resource dependencies automatically. For example, on a Debian system the manifest
class { '::cups':
default_queue => 'Warehouse'
}
cups_queue { 'GroundFloor':
ensure => 'class',
members => ['Office', 'Warehouse']
}
cups_queue { 'Office':
ensure => 'printer',
...
}
cups_queue { 'Warehouse':
ensure => 'printer',
...
}
by default generates the dependencies
Package['cups']
|
Service['cups']
|
File['lpoptions']
/ \
Cups_queue['Office'] Cups_queue['Warehouse']
\ / \
Cups_queue['GroundFloor'] Class['cups::default_queue']
The module usage described in this section is considered bad style and we strongly encourage the reader to use the recommended refactor instead.
Nevertheless this module does support these methods to cover some corner cases.
The following usage example is considered bad style. Please consider the recommended refactor.
You can also create cups_queue
resources using an ENC.
Make sure your setup includes the ::cups
class on the relevant nodes and replace a manifest like
class { '::cups':
default_queue => 'GroundFloor',
}
cups_queue { 'Office':
ensure => 'printer',
uri => 'lpd://192.168.2.105/binary_p1',
}
cups_queue { 'GroundFloor':
ensure => 'class',
members => ['Office', 'Warehouse'],
}
with the ENC output
---
cups::default_queue: 'GroundFloor'
cups::resources:
'Office':
ensure: 'printer'
uri: 'lpd://192.168.2.105/binary_p1'
'GroundFloor':
ensure: 'class'
members: ['Office', 'Warehouse']
The following usage example is considered bad style. Please consider the recommended refactor.
You can also create cups_queue
resources using Hiera.
Make sure your setup includes the ::cups
class on the relevant nodes and replace a manifest like
class { '::cups':
default_queue => 'GroundFloor',
}
cups_queue { 'Office':
ensure => 'printer',
uri => 'lpd://192.168.2.105/binary_p1',
}
cups_queue { 'GroundFloor':
ensure => 'class',
members => ['Office', 'Warehouse'],
}
with the Hiera data
---
cups::default_queue: 'GroundFloor'
cups::hiera: priority
cups_queue:
'Office':
ensure: 'printer'
uri: 'lpd://192.168.2.105/binary_p1'
'GroundFloor':
ensure: 'class'
members: ['Office', 'Warehouse']
where the cups::hiera
attribute must be set to priority
or merge
in order to enable Hiera lookups.
If you considered using Hiera or an ENC to directly create cups_queue
resources,
you probably did this in order to have fine-grained control over which CUPS queues
are available on which node.
Instead of creating the resources directly, we strongly encourage you to
encapsulate your cups_queue
resource definitions in subclasses of a custom myprinters
module
and then have the ENC / Hiera decide, which of these subclasses to ensure or remove on the given node.
Suppose you want to refactor the following manifest:
class { '::cups':
default_queue => 'GroundFloor',
}
cups_queue { 'Office':
ensure => 'printer',
uri => 'lpd://192.168.2.105/binary_p1',
}
cups_queue { 'GroundFloor':
ensure => 'class',
members => ['Office', 'Warehouse'],
}
Then your custom myprinters
module could be organized like this:
# MODULEPATH/myprinters/manifests/init.pp
class myprinters {
# Mandatory file - content optional
}
# MODULEPATH/myprinters/manifests/office.pp
class myprinters::office {
include cups
cups_queue { 'Office':
ensure => 'printer',
uri => 'lpd://192.168.2.105/binary_p1',
}
}
# MODULEPATH/myprinters/manifests/groundfloor.pp
class myprinters::groundfloor {
include cups
include myprinters::office
include myprinters::warehouse
cups_queue { 'GroundFloor':
ensure => 'class',
members => ['Office', 'Warehouse'],
}
}
Now you that you have your resource parametes safely wrapped in subclasses, the ENC / Hiera just get to decide which classes get included on the node:
# Example ENC output
classes:
cups:
default_queue: GroundFloor
myprinters::groundfloor:
-
cups_classes
: An array of the names of all installed classes. -
cups_classmembers
: A hash with the names of all classes (as keys) and their members (as array value). -
cups_printers
: An array of the names of all installed print queues (excluding classes). -
cups_queues
: An array of the names of all installed print queues (including classes).
Installs, configures, and manages the CUPS service.
-
default_queue
: The name of the default destination for all print jobs. Requires the catalog to contain acups_queue
resource with the same name. -
hiera
: When set topriority
ormerge
, Puppet will look up the Hiera keycups_queue
to managecups_queue
resources. See also the example above. Disabled by default. -
package_ensure
: Whether CUPS packages should bepresent
orabsent
. Defaults topresent
. -
package_manage
: Whether to manage package installation at all. Defaults totrue
. -
package_names
: An array with the names of all packages needed to install for CUPS andipptool
. Use[]
to disable automatic package management. OS dependent defaults apply. -
papersize
: Sets the system's default/etc/papersize
. Seeman papersize
for supported values. -
purge_unmanaged_queues
: Settingtrue
will remove all queues from the node which do not match acups_queue
resource in the current catalog. Defaults tofalse
. -
resources
: This attribute is intended for use with ENCs only (see example above). -
services
: An array with the names of all CUPS services to be managed. Use[]
to disable automatic service management. OS dependent defaults apply.
Manages the CUPS server configuration files.
-
ensure
: Whether the server should bepresent
orabsent
. Defaults topresent
. -
conf_directory
: The absolute path of the directory (without trailing slash) for the CUPS configuration files. Defaults to/etc/cups
. -
file_device
: Boolean value to allow or denyfile://
URIs other than/dev/null
. -
listen
: An array of network addresses (e.g.'localhost:631'
) and domain sockets (e.g.'/var/run/cups/cups.sock'
) the server should listen to. -
log_level
: Sets the verbosity of theerror_log
. Valid values arenone
,emerg
,alert
,crit
,error
,warn
,notice
,info
,debug
anddebug2
. -
port
: An array of ports (e.g.631
) the server should listen to. -
web_interface
: Boolean value to enable or disable the server's web interface.
Installs and manages CUPS print queues.
-
name
: mandatory - CUPS queue names are case insensitive and may contain any printable character except SPACE, TAB, "/", or "#". -
ensure
: mandatory - Specifies whether this queue should be aclass
, aprinter
orabsent
. -
access
: Manages queue access control. Takes a hash with keyspolicy
andusers
. Theallow
policy restricts access to theusers
provided, while thedeny
policy lets everybody submit jobs except the specifiedusers
. Theusers
are provided as a non-empty array of Unix group names (prefixed with an@
) and Unix user names. -
accepting
: Boolean value specifying whether the queue should accept print jobs or reject them. -
description
: A short informative description of the queue. -
enabled
: Boolean value specifying whether the queue should be running or stopped. -
held
: A held queue will print all jobs in print or pending, but all new jobs will be held. Settingfalse
will release them. -
location
: A short information where to find the hardcopies. -
options
: A hash of options (as keys) and their target value. Uselpoptions -p [queue_name] -l
on the node for a list of all options available for the queue and their supported values. -
shared
: Boolean value specifying whether to share this queue on the network. Default isfalse
.
members
: mandatory - A non-empty array with the names of CUPS queues. The class will be synced to contain only these members in the given order. If the catalog containscups_queue
resources for these queues, they will be required automatically.
-
interface
: The absolute path to a System V interface script on the node. If the catalog contains afile
resource with this path as title, it will automatically be required. -
make_and_model
: This value is used for driver updates and changes. Matches theNickName
(fallbackModelName
) value from the printer's PPD file if the printer was installed using a PPD file or a model, andLocal System V Printer
orLocal Raw Printer
otherwise. -
model
: A supported printer model. Uselpinfo -m
on the node to list all models available. -
ppd
: The absolute path to a PPD file on the node. If the catalog contains afile
resource with this path as title, it will automatically be required. The recommended location for your PPD files is/usr/share/cups/model/
or/usr/local/share/cups/model/
. -
uri
: The device URI of the printer. Uselpinfo -v
on the node to scan for printer URIs.
Setting papersize => 'a4'
only modifies /etc/papersize
,
but Evince uses
the environment variable LC_PAPER
to determine your preferred paper size,
as Patrick Min figured out.
On Debian and Ubuntu, you can set a global default value for LC_PAPER
using the manifest
augeas { 'papersize':
context => '/files/etc/default/locale',
changes => 'set LC_PAPER \'"es_ES.UTF-8"\'' # Change to your locale
}
Sometimes it may be necessary to modify the default values for some queue options to ensure an intuitive user experience, e.g. to enable the use of an optional duplex unit. For historic reasons there are two ways to set default values for all users:
-
Daemon defaults are set using
sudo lpadmin
and will affect all jobs from both local and remote hosts. The CUPS daemon saves them frequently - but not immediately - to/etc/cups/classes.conf
,/etc/cups/printers.conf
, and the PPD files in/etc/cups/ppd/
. -
Local defaults are set using
sudo lpoptions
and will only affect jobs from the local host, overriding the daemon defaults for these jobs. The values are saved to the file/etc/cups/lpoptions
.
Hence there is no robust way to determine the current daemon defaults when used in conjunction with local defaults.
If local defaults aren't used, the command lpoptions -p [queue_name] -l
will return the daemon defaults.
In order to provide a stable and idempotent way for Puppet to set default option values for all jobs sent to a queue,
this module will disable the use of local defaults by deleting the file /etc/cups/lpoptions
.
There are several ways to contribute for both users and developers:
-
This module is striving for the "Puppet approved" badge. If you like this module, please show your appreciation by giving it a positive rating in the Puppet Forge and spreading the news in your favorite way.
-
Want to suggesting a new feature, point out a flaw in the documentation or report a bug? Please open a GitHub issue using the suggested skeleton from the contribution guidelines.
-
Developers might want to submit a GitHub pull request. It is highly recommended to open an issue first and discuss changes with the maintainer. See the contribution guidelines for our quality standards and legal requirements.
Thank you for your interest in the CUPS module.