Provided by: cups-browsed_1.8.3-2ubuntu3.5_amd64 
NAME
cups-browsed.conf - server configuration file for cups-browsed
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.
DIRECTIVES
Only browse remote printers (via DNS-SD or CUPS browsing) from selected servers using the
"BrowseAllow", "BrowseDeny", and "BrowseOrder" directives
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.
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.
"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.
"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.
"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.
Default for "BrowseOrder" is "Deny.Allow" if there are both "BrowseAllow" and "BrowseDeny"
lines.
If there are no "Browse..." lines at all, all servers are accepted.
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
Filtering of remote printers by other properties than IP addresses of their servers
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.
By default there is no BrowseFilter line meaning that no filtering is applied.
To do filtering one can supply one or more BrowseFilter directives like this:
BrowseFilter [NOT] [EXACT] <FIELD> [<VALUE>]
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.
Avaialble field names are:
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
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.
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.
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).
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.
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.
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.
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.
Examples:
Rules for standard data items which are supplied with any remote printer advertised via
DNS-SD:
Print queue name must contain "hum_res_", this matches "hum_res_mono" or "hum_res_color"
but also "old_hum_res_mono":
BrowseFilter name hum_res_
This matches if the remote host name contains "printserver", like "printserver.local",
"printserver2.example.com", "newprintserver":
BrowseFilter host printserver
This matches all ports with 631 int its number, for example 631, 8631, 10631,...:
BrowseFilter port 631
This rule matches if the DNS-SD service name contains "@ printserver":
Browsefilter service @ printserver
Matches all domains with "local" in their names, not only "local" but also things like
"printlocally.com":
BrowseFilter domain local
Examples for rules applying to items of the TXT record:
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.
BrowseFilter pdl postscript
Color printers usually contain a "Color" entry set to "T" (for true) in the TXT record.
This rule selects them:
BrowseFilter color
This is a similar rule to select only duplex (automatic double-sided printing) printers:
BrowseFilter duplex
Rules with the NOT option:
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:
BrowseFilter NOT host financial
Get only monochrome printers ("Color" set to "F", meaning false, in the TXT record):
BrowseFilter NOT color
Rules with more advanced use of regular expressions:
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:
BrowseFilter name ^hum_res_
Server names is accepted if it contains "print_server" OR "graphics_dep_server":
BrowseFilter host print_server|graphics_dep_server
"printserver1", "printserver2", and "printserver3", nothing else:
BrowseFilter host ^printserver[1-3]$
Printers understanding at least one of PostScript, PCL, or PDF:
BrowseFilter pdl postscript|pcl|pdf
Examples for the EXACT option:
Only printers from "printserver.local" are accepted:
BrowseFilter EXACT host printserver.local
Printers from all servers except "prinserver2.local" are accepted:
BrowseFilter NOT EXACT host prinserver2.local
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.
BrowsePoll 192.168.7.20
BrowsePoll 192.168.7.65:631
BrowsePoll host.example.com:631
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.
BrowseLocalProtocols none
BrowseLocalProtocols CUPS
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".
BrowseRemoteProtocols none
BrowseRemoteProtocols CUPS dnssd
BrowseRemoteProtocols CUPS
BrowseRemoteProtocols dnssd
BrowseRemoteProtocols ldap
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.
BrowseProtocols none
BrowseProtocols CUPS dnssd
BrowseProtocols CUPS
BrowseProtocols dnssd
BrowseProtocols ldap
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).
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
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.
DomainSocket /var/run/cups/cups.sock
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.
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.
IPBasedDeviceURIs No
IPBasedDeviceURIs Yes
IPBasedDeviceURIs IPv4
IPBasedDeviceURIs IPv6
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.
CreateRemoteRawPrinterQueues Yes
The CreateIPPPrinterQueues directive specifies whether cups-browsed should discover IPP
printers (via Bonjour) and if they understand a known page description language (PWG
Raster, PDF, PostScript, PCL XL, PCL 5c/e) create PPD-less print queues (using a System V
interface script to control the filter chain). Clients have to IPP-poll the capabilities
of the printer and send option settings as standard IPP attributes. 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 PDF 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.
CreateIPPPrinterQueues Yes
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" setting makes always queues with PPD file
being created and no queue if the printer does not supply sufficient information for
creating a PPD. With "NoPPD" the queue is always created with a System V interface script
as filter, also when creatig a PPD would be possible. "Auto" (the default) lets a PPD
being created if the printer supplies sufficient information and a System V interface
script otherwise.
IPPPrinterQueueType Auto
IPPPrinterQueueType PPD
IPPPrinterQueueType NoPPD
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).
The two methods are:
Queuing of jobs on the client (LoadBalancing QueueOnClient):
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.
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.
Queuing of jobs on the servers (LoadBalancing QueueOnServers):
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.
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.
Default is queuing the jobs on the client as this is what CUPS does with classes.
LoadBalancing QueueOnClient
LoadBalancing QueueOnServers
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.
Note that print queues which cups-browsed already created before remember their previous
settings and so these settings do not get applied.
DefaultOptions Option1=Value1 Option2=Value2 Option3 noOption4
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" deactiivates 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.
AutoShutdown Off
AutoShutdown On
AutoShutdown avahi
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.
AutoShutdownOn NoQueues
AutoShutdownOn NoJobs
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.
AutoShutdownTimeout 20
SEE ALSO
cups-browsed(8)
/usr/share/doc/cups-browsed/README.gz
AUTHOR
The authors of cups-browsed are listed in /usr/share/doc/cups-browsed/AUTHORS.
This manual page was written for the Debian Project, but it may be used by others.
29 June 2013 cups-browsed.conf(5)