NAME

lcfg-cups - Manage CUPS printer queues

DESCRIPTION

Manage CUPS daemon and printer queues.

DAEMON RESOURCES

Virtually all of the directives supported by CUPS are represented by the LCFG resource of the same name. For example, ServerAdmin is stored in the cups.ServerAdmin resource

cups.ServerAdmin       printmaster@foo.org

The Include directive is not supported. Directives marked as deprecated in the CUPS documentation are also not supported (except AuthClass which is used by MacOS X 10.4).

Some directives can appear in the config file multiple times. Set the different values for these as space separated values in its resource. For example, cups.Listen localhost:631 /var/run/cups/cups.sock will result in the following two entries Listen localhost:631 and Listen /var/run/cups/cups.sock. The BrowseAddress, BrowseAllow, BrowseDeny, Listen, PassEnv, Port, SSLListen and SSLPort directives are handled this way.

Some directives which can appear multiple times can have values which include spaces and they cannot be handled in the above manner. BrowseRelay and SetEnv require tagged lists to be created for their multiple values. For example,

cups.BrowseRelays    one two
cups.BrowseRelay_one src1 dst1
cups.BrowseRelay_two src2 dst2

Locations

These are tagged which are listed in the Locations resource. Each location must have a Location_tag resource and optionally Limits_tag, LimitExcepts_tag, Order_tag, Allows_tag, Denies_tag, Encryption_tag, AuthType_tag, Require_tag and Satisfy_tag resources. For example,

cups.Locations         root
cups.Location_root     /

Policies

Policies are tagged and are listed in the Policies resource. Each policy must have its name in its Policy_tag and one or more Limit stanza tags listed in Limits_tag. For example,

cups.Policies          defpol
cups.Policy_defpol     default
cups.Limits_defpol     owner admin cancel all

Limits and LimitExcepts

Limits and LimitExcepts are tagged and are listed in the Limits and LimitsExcepts resources. Because limit stanzas only appear inside locations or policies they are always also associated with their parent's tag. For example, to define a limit for the default policy from above

cups.Limit_defpol_all  All
cups.Order_defpol_all  deny,allow

Allow and Deny

These are tagged resources since each line may contain more than one word (some implementations include from ...). The tags are stored in the Allows and Denies resoures. These directives are always within Location or Limit stanzas so are associated with their parents' tags. Extending the root location above to include access control from localhost, for example

cups.Order_root        allow,deny
cups.Allows_root       lh admin
cups.Allow_root_lh     localhost
cups.Allow_root_admin  myadmin.foo.org

CLIENT RESOURCES

These resources control the contents of /etc/cups/client.conf.

server

Optional IP address or DNS name of the CUPS server which clients on this computer should contact. Can have an optional port number specified after a trailing colon, for example

cups.server printserver.foo.org:631

If you set this to anything other than empty, localhost[:port] or 127.0.0.1[:port] then the component will skip queue management as it does not support configuring remote CUPS servers.

The default is empty, and clients default to using localhost:631.

encryption

Optional resource specifying the encryption level clients should use when communicating with server. The value must be one of empty, IfRequested, Never or Required.

This resource only affects the /etc/cups/client.conf file if the server resource is not empty.

QUEUE RESOURCES

Queues will only be managed if the cups.server resource is empty or set to localhost or 127.0.0.1 with optional port specification.

queues

A list of tags identifying CUPS queues to be created.

queue_tag

The queue name for the queue identified by tag, allowing for characters to be used in queue names which are illegal in LCFG resources, e.g. hyphen. If not set, then the queue defaults to being named tag.

defaultq

The name of the default queue. Remember the queue's name might not be the same as its resources tag if the queue_tag resource is used.

uri_tag

The URI for the queue identified by tag. This is a required resource, as the queue will not be configured if it is empty.

ppd_tag

Full pathname of the Postscript Printer Definition (PPD) file for the queue identified by tag. If the file doesn't exist, the component logs an error and doesn't configure the queue. CUPS copies the PPD file to /etc/cups/ppds/queue.ppd and can gunzip the PPD on the fly so you can set this resource to be a gzipped PPD.

Any spaces should be protected by enclosing the path in double quotes. The quotes must be placed at the beginning and end of the full path, not only surrounding the space(s).

loc_tag

The human readable printer's physical location for the queue identified by tag. The description is free text and shouldn't include double quotes without escaping them, as double quotes are wrapped around the value of this resource in the call to lpadmin. See the TEMPLATE section below for details.

descr_tag

The human readable description for the queue identified by tag. The description is free text and shouldn't include double quotes without escaping them, as double quotes are wrapped around the value of this resource in the call to lpadmin. See the TEMPLATE section below for details.

class_tag

Add printer to the specified class. lpadmin will create the class if it doesn't exist.

perms_tag

Permissions for the queue, as required by the -u option of lpadmin.

qopts_tag

A list of extra option tags for the queue identified by tag. For example

cups.qopts_myprinter           pagesize

qopt_tag1_tag2

The name of the option for the queue identified by tag1 and the option by tag2. For example

cups.qopt_myprinter_pagesize   PageSize

qoptv_tag1_tag2

The value of the option for the queue identified by tag1 and the option by tag2. For example

cups.qoptv_myprinter_pagesize  A4

TEMPLATES

The component uses an LCFG template to build the command line for lpadmin which is used to configure the queues.

The uri, loc, descr, perms are all substituted inside double quotes to protect their values from the shell.

The qopt and qoptv resources are combined in the form qopt=qoptv before being surrounded by double quotes.

The templates for the daemon's (/etc/cups/cupsd.conf) and client's config files (/etc/cups/client.conf) are created by the component's configure method and are not distributed in the package.

FILES

/var/lcfg/conf/cups/cupsd.conf.tmpl: Template for the daemon's config file.
/var/lcfg/conf/cups/client.conf.tmpl: Template for the client's config file.
/usr/lib/lcfg/conf/cups/lpadmin_conf.tmpl: Template for lpadmin command line arguments.
/var/lcfg/conf/cups/queues/tag.q: lpadmin command line arguments for the queue identified by tag, derived from the template and resources.
/var/lcfg/conf/cups/queues/tag.q~: Previous lpadmin command line arguments for the queue identified by tag. This is created by the template processor as a backup file and isn't read by the component.
/var/lcfg/conf/cups/queues/tag.active: A flag for the queue identified by tag, which is used by the component to select which queues should be deleted.
/var/lcfg/conf/cups/queues/tag.name: The real name of the queue identified by tag, which is used in the calls to lpadmin.

BUGS

The component cannot control ordering of the directives in the cupsd.conf file.

There is no validation of any of the resources.

The version of the CUPS daemon is not checked so some resources may or may not have any effect or cause the daemon to fail to start.

The component cannot detect when the server resource is set to a DNS hostname that actually corresponds to the local host.

CUPS may support multiple server addresses in the client configuration file, but this component does not allow you to specify more than one.

PLATFORMS

Scientific5, Darwin

AUTHOR

Kenneth MacDonald <K.MacDonald@ed.ac.uk>