Provided by: cups-browsed_1.8.3-2ubuntu3_amd64 bug

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)