Only browse remote printers (via DNS-SD or CUPS browsing) from
selected servers using the "BrowseAllow", "BrowseDeny", and
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
"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
"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"
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.
Filtering of remote printers by other properties than IP addresses of
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
To do filtering one can supply one or more BrowseFilter directives
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 printers 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
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
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
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.
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,
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:
This is a similar rule to select only duplex (automatic double-sided
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
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"
BrowseFilter name ^hum_res_
Server names is accepted if it contains "print_server" OR
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
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.
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 CUPS dnssd
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
BrowseProtocols CUPS dnssd
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 servers certificate, or to a certificates store, can be
The optional filter allows the LDAP search to be more specific, and is used
in addition to the hardcoded filter (objectclass=cupsPrinter).
BrowseLDAPFilter (printerLocation=/Office 1/*)
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.
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.
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.
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.
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.
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
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
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 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
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.
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
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