The CUPS module

Table of Contents

1. Description
2. Setup
   • What cups affects
   • Setup requirements
   • Beginning with cups
3. Usage - A quick start guide
   • Managing printers
   • Managing classes
   • Configuring queues
   • Configuring CUPS
   • Automatic dependencies
   • Using Hiera
4. Reference - The documentation of all features available
   • Classes
   • Defines
   • Types
   • Facts
5. Limitations
6. Contributing - Guidelines for users and developers

Description

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.

Setup

What cups affects

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

Setup Requirements

This module is written in Ruby 1.9 syntax and tested on systems using

• Ruby 1.9+ or 2.x

• 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. It will however not work with Ruby versions prior to 1.9.

Beginning with CUPS

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.

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.

Managing Printers

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 resource

  file { '/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 resource

  file { '/usr/share/cups/model/myprinter.sh':
    ensure => 'file',
    source => 'puppet:///modules/myModule/myprinter.sh'
  }
  

  which will be autorequired by Cups_queue['MinimalPrinter'].

Changing the driver

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 (fallback ModelName) 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',
    ...
  }
  

Managing Classes

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'].

Configuring queues

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 by default using

# Default values for all 'cups_queue' resources in the current scope:
# Use 'Cups_queue' with upper case first letter and without resource name
Cups_queue {
  accepting => 'true',
  enabled   => '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.

Configuring CUPS

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.

Automatic dependencies

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']

Using Hiera

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']

Reference

Classes

• cups

• cups::default_queue (private)

• cups::params (private)

Defines

• cups::ctl

Types

• cups_queue

Facts

• 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).

Class: cups

Installs, configures, and manages the CUPS service.

Attributes (all optional)

• confdir: The fully qualified directory (without trailing slash) for the CUPS configuration files. Defaults to /etc/cups.

• default_queue: The name of the default destination for all print jobs. Requires the catalog to contain a cups_queue resource with the same name.

• hiera: When set to priority or merge, Puppet will look up the Hiera key cups_queue to manage cups_queue resources. See also the example above. Disabled by default.

• packages: An array with the names of all packages needed to install for CUPS and ipptool. Use [] to disable automatic package management. OS dependent defaults apply.

• purge_unmanaged_queues: Setting true will remove all queues from the node which do not match a cups_queue resource in the current catalog. Defaults to false.

• services: An array with the names of all CUPS services to be managed. Use [] to disable automatic service management. OS dependent defaults apply.

• webinterface: Boolean value to enable or disable the CUPS web interface at http://localhost:631.

Define: cups::ctl

A convenience wrapper for the cupsctl command used to configure the CUPS daemon.

Attributes

• title: mandatory - The name of the parameter to be managed.

• ensure: mandatory - The value to be ensured.

Type: cups_queue

Installs and manages CUPS print queues.

Attributes

• 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 a class, a printer or absent.

• access: Manages queue access control. Takes a hash with keys policy and users. The allow policy restricts access to the users provided, while the deny policy lets everybody submit jobs except the specified users. The users 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. Setting false will release them.

• location: A short information where to find the hardcopies.

• options: A hash of options (as keys) and their target value. Use lpoptions -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 is false.

Class-only attributes

• 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 contains cups_queue resources for these queues, they will be required automatically.

Printers-only attributes

• interface: The absolute path to a System V interface script on the node. If the catalog contains a file resource with this path as title, it will automatically be required.

• make_and_model: This value is used for driver updates and changes. Matches the NickName (fallback ModelName) value from the printer's PPD file if the printer was installed using a PPD file or a model, and Local System V Printer or Local Raw Printer otherwise.

• model: A supported printer model. Use lpinfo -m on the node to list all models available.

• ppd: The absolute path to a PPD file on the node. If the catalog contains a file 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. Use lpinfo -v on the node to scan for printer URIs.

Limitations

Option defaults

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.

Contributing

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.

Changelog

2016-04-10 - Release 1.1.0

Published at Puppet Forge and GitHub.

Summary

This release introduces a new feature and adjusts to Puppet's brand refresh.

Features

• All unmanaged CUPS queues can now be removed automatically

2016-03-19 - Maintenance release 1.0.2

Published at Puppet Forge and GitHub.

Summary

This maintenance release overcomes an unintuitive 3rd-party behavior and improves the internal structure of the module.

Changes in default behavior

• The default value for ensure was removed.

Bugfixes

• A workaround for CUPS issue 4781
• Using puppet resource cups_queue to modify an already installed queue is now possible without specifying ensure
• Automatic resource relations were adjusted to show up correctly in the dependency graph

2016-03-19 - Maintenance release 1.0.1

retracted.

2016-03-07 - Release 1.0.0

Published at Puppet Forge and GitHub.

Summary

Existing CUPS modules in the Puppet Forge lacked some desirable functionality by design. This module was written from scratch, taking divergent architectural decisions and employing test driven development to provide all features required in an office network setting.

Key features

• Locale independence (tested on English and Spanish VMs)
• Support for a wide range of Linux distributions
• Unified support for printer queues and class queues
• Default queue management
• Support for printer driver changes
• Support for queue access control
• Unified support for CUPS options and PPD options