.\"Text automatically generated by txt2man
.TH cups-browsed.conf 5 "29 June 2013" "" ""
.SH NAME
\fBcups-browsed.conf \fP- server configuration file for cups-browsed
\fB
.SH 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.
.SH 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.
.PP
.nf
.fam C
        CacheDir /var/cache/cups

.fam T
.fi
With "LogDir" can be defined where cups-browsed creates its debug log file
(if "DebugLogging file" is set).
.PP
.nf
.fam C
        LogDir /var/log/cups

.fam T
.fi
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").
.PP
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.
.PP
.nf
.fam C
        DebugLogging file
        DebugLogging stderr
        DebugLogging file stderr
        DebugLogging none

.fam T
.fi
Only browse remote printers (via DNS-SD or CUPS browsing) from
selected servers using the "BrowseAllow", "BrowseDeny", and
"BrowseOrder" directives
.PP
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.
.PP
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.
.PP
"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.
.PP
"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.
.PP
"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.
.PP
Default for "BrowseOrder" is "Deny.Allow" if there are both
"BrowseAllow" and "BrowseDeny" lines.
.PP
If there are no "Browse..." lines at all, all servers are accepted.
.PP
.nf
.fam C
        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

.fam T
.fi
Filtering of remote printers by other properties than IP addresses of
their servers
.PP
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.
.PP
By default there is no BrowseFilter line meaning that no filtering is
applied.
.PP
To do filtering one can supply one or more BrowseFilter directives
like this:
.PP
.nf
.fam C
        BrowseFilter [NOT] [EXACT] <FIELD> [<VALUE>]

.fam T
.fi
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.
.PP
Available field names are:
.PP
.nf
.fam C
        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

.fam T
.fi
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.
.PP
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.
.PP
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).
.PP
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.
.PP
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.
.PP
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.
.PP
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.
.PP
Examples:
.PP
Rules for standard data items which are supplied with any remote
printer advertised via DNS-SD:
.PP
Print queue name must contain "hum_res_", this matches "hum_res_mono"
or "hum_res_color" but also "old_hum_res_mono":
.PP
.nf
.fam C
        BrowseFilter name hum_res_

.fam T
.fi
This matches if the remote host name contains "printserver", like
"printserver.local", "printserver2.example.com", "newprintserver":
.PP
.nf
.fam C
        BrowseFilter host printserver

.fam T
.fi
This matches all ports with 631 int its number, for example 631, 8631,
10631,...:
.PP
.nf
.fam C
        BrowseFilter port 631

.fam T
.fi
This rule matches if the DNS-SD service name contains "@ printserver":
.PP
.nf
.fam C
        Browsefilter service @ printserver

.fam T
.fi
Matches all domains with "local" in their names, not only "local" but
also things like "printlocally.com":
.PP
.nf
.fam C
        BrowseFilter domain local

.fam T
.fi
Examples for rules applying to items of the TXT record:
.PP
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.
.PP
.nf
.fam C
        BrowseFilter pdl postscript

.fam T
.fi
Color printers usually contain a "Color" entry set to "T" (for true)
in the TXT record. This rule selects them:
.PP
.nf
.fam C
        BrowseFilter color

.fam T
.fi
This is a similar rule to select only duplex (automatic double-sided
printing) printers:
.PP
.nf
.fam C
        BrowseFilter duplex

.fam T
.fi
Rules with the NOT option:
.PP
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:
.PP
.nf
.fam C
        BrowseFilter NOT host financial

.fam T
.fi
Get only monochrome printers ("Color" set to "F", meaning false, in
the TXT record):
.PP
.nf
.fam C
        BrowseFilter NOT color

.fam T
.fi
Rules with more advanced use of regular expressions:
.PP
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:
.PP
.nf
.fam C
        BrowseFilter name ^hum_res_

.fam T
.fi
Server names is accepted if it contains "print_server" OR
"graphics_dep_server":
.PP
.nf
.fam C
        BrowseFilter host print_server|graphics_dep_server

.fam T
.fi
"printserver1", "printserver2", and "printserver3", nothing else:
.PP
.nf
.fam C
        BrowseFilter host ^printserver[1-3]$

.fam T
.fi
Printers understanding at least one of PostScript, PCL, or PDF:
.PP
.nf
.fam C
        BrowseFilter pdl postscript|pcl|pdf

.fam T
.fi
Examples for the EXACT option:
.PP
Only printers from "printserver.local" are accepted:
.PP
.nf
.fam C
        BrowseFilter EXACT host printserver.local

.fam T
.fi
Printers from all servers except "prinserver2.local" are accepted:
.PP
.nf
.fam C
        BrowseFilter NOT EXACT host prinserver2.local

.fam T
.fi
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 works independently of whether CUPS browsing is activated
in BrowseRemoteProtocols.
.PP
.nf
.fam C
        BrowsePoll 192.168.7.20
        BrowsePoll 192.168.7.65:631
        BrowsePoll host.example.com:631


.fam T
.fi
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 in /etc/cups/cupsd.conf.
.PP
.nf
.fam C
        BrowseLocalProtocols none
        BrowseLocalProtocols CUPS


.fam T
.fi
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 cups".
.PP
.nf
.fam C
        BrowseRemoteProtocols none
        BrowseRemoteProtocols CUPS dnssd
        BrowseRemoteProtocols CUPS
        BrowseRemoteProtocols dnssd
        BrowseRemoteProtocols ldap

.fam T
.fi
The BrowseProtocols directive specifies the protocols to use when
finding remote shared printers on the network and advertising local
shared printers. "dnssd" and "ldap" are ignored for BrowseLocalProtocols.
Multiple protocols can be specified by separating them with spaces. The
default is "none" for BrowseLocalProtocols and "dnssd cups" for
BrowseRemoteProtocols.
.PP
.nf
.fam C
        BrowseProtocols none
        BrowseProtocols CUPS dnssd
        BrowseProtocols CUPS
        BrowseProtocols dnssd
        BrowseProtocols ldap

.fam T
.fi
The configuration for the LDAP browsing mode define where the LDAP search
should be performed. If built with an LDAP library that supports TLS, the
path to the server's certificate, or to a certificates store, can be
specified.
The optional filter allows the LDAP search to be more specific, and is used
in addition to the hardcoded filter (objectclass=cupsPrinter).
.PP
.nf
.fam C
        BrowseLDAPBindDN cn=cups-browsed,dc=domain,dc=tld
        BrowseLDAPCACertFile /path/to/server/certificate.pem
        BrowseLDAPDN ou=printers,dc=domain,dc=tld
        BrowseLDAPFilter (printerLocation=/Office 1/*)
        BrowseLDAPPassword s3cret
        BrowseLDAPServer ldaps://ldap.domain.tld

.fam T
.fi
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.
.PP
.nf
.fam C
        DomainSocket /var/run/cups/cups.sock
        DomainSocket None
        DomainSocket Off

.fam T
.fi
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.
.PP
.nf
.fam C
        HttpLocalTimeout 5
        HttpRemoteTimeout 10

.fam T
.fi
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.
.PP
.nf
.fam C
        HttpMaxRetries 5

.fam T
.fi
The interval between browsing/broadcasting cycles, local and/or
remote, can be adjusted with the BrowseInterval directive.
.PP
.nf
.fam C
        BrowseInterval 60

.fam T
.fi
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.
Especially queues discovered by CUPS broadcasts will be removed after
this timeout if no further broadcast from the server happens.
.PP
.nf
.fam C
        BrowseTimeout 300

.fam T
.fi
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.
.PP
.nf
.fam C
        AllowResharingRemoteCUPSPrinters Yes

.fam T
.fi
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.
.PP
.nf
.fam C
        NewBrowsePollQueuesShared Yes

.fam T
.fi
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.
.PP
.nf
.fam C
        OnlyUnsupportedByCUPS Yes

.fam T
.fi
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".
.PP
.nf
.fam C
        UseCUPSGeneratedPPDs No

.fam T
.fi
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.
.PP
.nf
.fam C
        LocalQueueNamingRemoteCUPS DNS-SD
        LocalQueueNamingRemoteCUPS MakeModel
        LocalQueueNamingRemoteCUPS RemoteName
        LocalQueueNamingIPPPrinter DNS-SD
        LocalQueueNamingIPPPrinter MakeModel

.fam T
.fi
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.
.PP
Set DNSSDBasedDeviceURIs to "No" if cups-browsed should use the
conventional host-name/IP-based URIs.
.PP
Note that this option has only influence on URIs for printers
discovered via DNS-SD, not via legacy CUPS broewsing or LDAP.
Those printers get always assigned the conventional URIs.
.PP
.nf
.fam C
        DNSSDBasedDeviceURIs Yes

.fam T
.fi
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.
.PP
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.
.PP
This mode could also be useful for development and debugging.
.PP
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.
.PP
.nf
.fam C
        IPBasedDeviceURIs No
        IPBasedDeviceURIs Yes
        IPBasedDeviceURIs IPv4
        IPBasedDeviceURIs IPv6

.fam T
.fi
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.
.PP
.nf
.fam C
        CreateRemoteRawPrinterQueues Yes

.fam T
.fi
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".
.PP
.nf
.fam C
        CreateRemoteCUPSPrinterQueues No

.fam T
.fi
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.
.PP
.nf
.fam C
        CreateIPPPrinterQueues No
        CreateIPPPrinterQueues LocalOnly
        CreateIPPPrinterQueues Everywhere
        CreateIPPPrinterQueues AppleRaster
        CreateIPPPrinterQueues Everywhere AppleRaster
        CreateIPPPrinterQueues Driverless
        CreateIPPPrinterQueues All

.fam T
.fi
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.
.PP
.nf
.fam C
        IPPPrinterQueueType PPD
        IPPPrinterQueueType NoPPD
        IPPPrinterQueueType Interface
        IPPPrinterQueueType Auto

.fam T
.fi
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.
.PP
.nf
.fam C
        NewIPPPrinterQueuesShared Yes

.fam T
.fi
How to handle the print queues cups-browsed creates when cups-browsed
is shut down:
.PP
"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.
.PP
"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.
.PP
.nf
.fam C
        KeepGeneratedQueuesOnShutdown No

.fam T
.fi
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.
.PP
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.
.PP
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.
.PP
Only remote CUPS printers get clustered, not IPP network printers or
IPP-over-USB printers.
.PP
.nf
.fam C
        AutoClustering Yes
        AutoClustering No

.fam T
.fi
Load-balancing printer cluster formation can also be manually
controlled by defining explicitly which remote CUPS printers should
get clustered together.
.PP
This is done by the "Cluster" directive:
.PP
.nf
.fam C
        Cluster <QUEUENAME>: <EXPRESSION1> <EXPRESSION2> ...
        Cluster <QUEUENAME>

.fam T
.fi
If no expressions are given, <QUEUENAME> is used as the first and
only expression for this cluster.
.PP
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.
.PP
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.
.PP
Each expression must be a string of characters without spaces. If
spaces are needed, replace them by underscores ('_').
.PP
An expression can be matched in three ways:
.PP
.nf
.fam C
    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

.fam T
.fi
Note that the matching is done case-insensitively and any group of
non-alphanumerical characters is replaced by a single underscore.
.PP
So if an expression is "HP_DeskJet_2540" and the remote server
reports "hp Deskjet-2540" the printer gets matched to this cluster.
.PP
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).
.PP
Examples:
.PP
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"):
.PP
.nf
.fam C
        AutoClustering No
        Cluster laserprinter

.fam T
.fi
To cluster all remote CUPS queues of HP LaserJet 4050 printers in a
local queue named "LJ4050":
.PP
.nf
.fam C
        Cluster LJ4050: HP_LaserJet_4050

.fam T
.fi
As DNS-SD service names are unique in a network you can create a
cluster from exactly specified printers (spaces replaced by
underscores):
.PP
.nf
.fam C
        Cluster hrdep: oldlaser_@_hr-server1 newlaser_@_hr-server2

.fam T
.fi
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).
.PP
The two methods are:
.PP
Queuing of jobs on the client (LoadBalancing QueueOnClient):
.PP
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.
.PP
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.
.PP
Queuing of jobs on the servers (LoadBalancing QueueOnServers):
.PP
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.
.PP
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.
.PP
Default is queuing the jobs on the client as this is what CUPS does
with classes.
.PP
.nf
.fam C
        LoadBalancing QueueOnClient
        LoadBalancing QueueOnServers

.fam T
.fi
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.
.PP
Note that print queues which cups-browsed already created before
remember their previous settings and so these settings do not get
applied.
.PP
.nf
.fam C
        DefaultOptions Option1=Value1 Option2=Value2 Option3 noOption4

.fam T
.fi
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.
.PP
.nf
.fam C
        AutoShutdown Off
        AutoShutdown On
        AutoShutdown avahi

.fam T
.fi
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.
.PP
.nf
.fam C
        AutoShutdownOn NoQueues
        AutoShutdownOn NoJobs

.fam T
.fi
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.
.PP
.nf
.fam C
        DebugLogFileSize 300

.fam T
.fi
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.
.PP
.nf
.fam C
        AutoShutdownTimeout 20

.fam T
.fi
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.
.PP
.nf
.fam C
        NotifLeaseDuration 86400
.fam T
.fi
.SH SEE ALSO

\fBcups-browsed\fP(8)
.PP
/usr/share/doc/cups-browsed/README.gz
.SH AUTHOR
The authors of cups-browsed are listed in /usr/share/doc/cups-browsed/AUTHORS.
.PP
This manual page was written for the Debian Project, but it may be used by others.