1cups-browsed.conf(5)                                      cups-browsed.conf(5)
2
3
4

NAME

6       cups-browsed.conf - server configuration file for cups-browsed
7

DESCRIPTION

9       The  cups-browsed.conf  file  configures the cups-browsed daemon. It is
10       normally located in the /etc/cups directory. Each line in the file  can
11       be a configuration directive, a blank line, or a comment. Comment lines
12       start with the # character.
13

DIRECTIVES

15       The "CacheDir" directive determines where cups-browsed should save  in‐
16       formation  about  the print queues it had generated when shutting down,
17       like whether one of these queues was the default  printer,  or  default
18       option settings of the queues.
19
20               CacheDir /var/cache/cups
21
22       With  "LogDir"  can be defined where cups-browsed creates its debug log
23       file (if "DebugLogging file" is set).
24
25               LogDir /var/log/cups
26
27       The "DebugLogging" directive determines how  should  debug  logging  be
28       done.  Into the file /var/log/cups/cups-browsed_log ("file"), to stderr
29       ("stderr"), or not at all ("none").
30
31       Note that if cups-browsed is running as a system service  (for  example
32       via  systemd) logging to stderr makes the log output going to the jour‐
33       nal or syslog. Only if you run cups-browsed from the command line  (for
34       development or debugging) it will actually appear on stderr.
35
36               DebugLogging file
37               DebugLogging stderr
38               DebugLogging file stderr
39               DebugLogging none
40
41       Only browse remote printers (via DNS-SD or CUPS browsing) from selected
42       servers using the "BrowseAllow", "BrowseDeny", and "BrowseOrder" direc‐
43       tives
44
45       This  serves for restricting the choice of printers in print dialogs to
46       trusted servers or to reduce the number of listed printers in the print
47       dialogs to a more user-friendly amount in large networks with very many
48       shared printers.
49
50       This only filters the selection of  remote  printers  for  which  cups-
51       browsed creates local queues. If the print dialog uses other mechanisms
52       to list remote printers as for  example  direct  DNS-SD  access,  cups-
53       browsed  has  no influence. cups-browsed also does not prevent the user
54       from manually accessing non-listed printers.
55
56       "BrowseAllow": Accept printers from these hosts or networks.  If  there
57       are  only  "BrowseAllow" lines and no "BrowseOrder" and/or "BrowseDeny"
58       lines, only servers matching at last one  "BrowseAllow"  line  are  ac‐
59       cepted.
60
61       "BrowseDeny":  Deny printers from these hosts or networks. If there are
62       only "BrowseDeny"  lines  and  no  "BrowseOrder"  and/or  "BrowseAllow"
63       lines,  all  servers NOT matching any of the "BrowseDeny" lines are ac‐
64       cepted.
65
66       "BrowseOrder":  Determine  the  order  in   which   "BrowseAllow"   and
67       "BrowseDeny"  lines  are  applied. With "BrowseOrder Deny,Allow" in the
68       beginning all servers are accepted, then the "BrowseDeny" lines are ap‐
69       plied  to  exclude  unwished  servers  or  networks  and after that the
70       "BrowseAllow" lines to re-include servers or  networks.  With  "Browse‐
71       Order  Allow,Deny" we start with denying all servers, then applying the
72       "BrowseAllow" lines and afterwards the "BrowseDeny" lines.
73
74       Default for "BrowseOrder" is "Deny.Allow" if there are both  "BrowseAl‐
75       low" and "BrowseDeny" lines.
76
77       If there are no "Browse..." lines at all, all servers are accepted.
78
79               BrowseAllow All
80               BrowseAllow 192.168.7.20
81               BrowseAllow 192.168.7.0/24
82               BrowseAllow 192.168.7.0/255.255.255.0
83
84               BrowseDeny All
85               BrowseDeny 192.168.1.13
86               BrowseDeny 192.168.3.0/24
87               BrowseDeny 192.168.3.0/255.255.255.0
88
89               BrowseOrder Deny,Allow
90               BrowseOrder Allow,Deny
91
92       Filtering  of  remote printers by other properties than IP addresses of
93       their servers
94
95       Often the desired selection of printers cannot be reached by only  tak‐
96       ing into account the IP addresses of the servers. For these cases there
97       is the BrowseFilter directive to filter by most of the known properties
98       of the printer.
99
100       By  default  there is no BrowseFilter line meaning that no filtering is
101       applied.
102
103       To do filtering one can supply one or more BrowseFilter directives like
104       this:
105
106               BrowseFilter [NOT] [EXACT] <FIELD> [<VALUE>]
107
108       The  BrowseFilter  directive always starts with the word "BrowseFilter"
109       and it must at least contain the name of the data  field  (<FIELD>)  of
110       the printer's properties to which it should apply.
111
112       Available field names are:
113
114               name:    Name of the local print queue to be created
115               host:    Host name of the remote print server
116               port:    Port through which the printer is accessed on the server
117               service: DNS/SD service name of the remote printer
118               domain:  Domain of the remote print server
119
120       Also  all  field names in the TXT records of DNS-SD-advertised printers
121       are valid, like "color", "duplex", "pdl", ... If the field name of  the
122       filter rule does not exist for the printer, the rule is skipped.
123
124       The  optional  <VALUE> field is either the exact value (when the option
125       EXACT is supplied) or a regular expression (Run "man 7 regex" in a ter‐
126       minal window) to be matched with the data field.
127
128       If  no  <VALUE>  filed  is  supplied, rules with field names of the TXT
129       record are considered for  boolean  matching  (true/false)  of  boolean
130       field  (like duplex, which can have the values "T" for true and "F" for
131       false).
132
133       If the option NOT is supplied, the filter rule is fulfilled if the reg‐
134       ular  expression  or  the exact value DOES NOT match the content of the
135       data field. In a boolean rule (without <VALUE>) the rule matches false.
136
137       Regular expressions are always considered case-insensitive and extended
138       POSIX regular expressions. Field names and options (NOT, EXACT) are all
139       evaluated case-insensitive. If there is an error in a  regular  expres‐
140       sion, the BrowseFilter line gets ignored.
141
142       Especially  to  note  is that supplying any simple string consisting of
143       only letters, numbers, spaces, and some basic special characters  as  a
144       regular  expression  matches  if  it is contained somewhere in the data
145       field.
146
147       If there is more than one BrowseFilter directive,  ALL  the  directives
148       need  to  be fulfilled for the remote printer to be accepted. If one is
149       not fulfilled, the printer will get ignored.
150
151       Examples:
152
153       Rules for standard data  items  which  are  supplied  with  any  remote
154       printer advertised via DNS-SD:
155
156       Print  queue  name must contain "hum_res_", this matches "hum_res_mono"
157       or "hum_res_color" but also "old_hum_res_mono":
158
159               BrowseFilter name hum_res_
160
161       This matches if the  remote  host  name  contains  "printserver",  like
162       "printserver.local", "printserver2.example.com", "newprintserver":
163
164               BrowseFilter host printserver
165
166       This  matches all ports with 631 int its number, for example 631, 8631,
167       10631,...:
168
169               BrowseFilter port 631
170
171       This rule matches if the DNS-SD service name contains "@ printserver":
172
173               Browsefilter service @ printserver
174
175       Matches all domains with "local" in their names, not only  "local"  but
176       also things like "printlocally.com":
177
178               BrowseFilter domain local
179
180       Examples for rules applying to items of the TXT record:
181
182       This  rule  selects  PostScript printers, as the "PDL" field in the TXT
183       record contains "postscript"  then.  This  includes  also  remote  CUPS
184       queues  which  accept  PostScript,  independent of whether the physical
185       printer behind the CUPS queue accepts PostScript or not.
186
187               BrowseFilter pdl postscript
188
189       Color printers usually contain a "Color" entry set to "T" (for true) in
190       the TXT record. This rule selects them:
191
192               BrowseFilter color
193
194       This  is  a  similar rule to select only duplex (automatic double-sided
195       printing) printers:
196
197               BrowseFilter duplex
198
199       Rules with the NOT option:
200
201       This rule EXCLUDES printers from all hosts  containing  "financial"  in
202       their  names,  nice to get rid of the 100s of printers of the financial
203       department:
204
205               BrowseFilter NOT host financial
206
207       Get only monochrome printers ("Color" set to "F", meaning false, in the
208       TXT record):
209
210               BrowseFilter NOT color
211
212       Rules with more advanced use of regular expressions:
213
214       Only  queue  names  which BEGIN WITH "hum_res_" are accepted now, so we
215       still get "hum_res_mono" or "hum_res_color" but not  "old_hum_res_mono"
216       any more:
217
218               BrowseFilter name ^hum_res_
219
220       Server  names  is  accepted  if  it  contains "print_server" OR "graph‐
221       ics_dep_server":
222
223               BrowseFilter host print_server|graphics_dep_server
224
225       "printserver1", "printserver2", and "printserver3", nothing else:
226
227               BrowseFilter host ^printserver[1-3]$
228
229       Printers understanding at least one of PostScript, PCL, or PDF:
230
231               BrowseFilter pdl postscript|pcl|pdf
232
233       Examples for the EXACT option:
234
235       Only printers from "printserver.local" are accepted:
236
237               BrowseFilter EXACT host printserver.local
238
239       Printers from all servers except "prinserver2.local" are accepted:
240
241               BrowseFilter NOT EXACT host prinserver2.local
242
243       The BrowsePoll directive polls a server for available printers once ev‐
244       ery 60 seconds. Multiple BrowsePoll directives can be specified to poll
245       multiple servers. The default port to connect to  is  631.   BrowsePoll
246       works  independently of whether CUPS browsing is activated in BrowseRe‐
247       moteProtocols.
248
249               BrowsePoll 192.168.7.20
250               BrowsePoll 192.168.7.65:631
251               BrowsePoll host.example.com:631
252
253
254       The BrowseLocalProtocols directive specifies the protocols to use  when
255       advertising  local  shared  printers  on  the  network.  The default is
256       "none". Control of advertising of local shared printers using dnssd  is
257       done in /etc/cups/cupsd.conf.
258
259               BrowseLocalProtocols none
260               BrowseLocalProtocols CUPS
261
262
263       The BrowseRemoteProtocols directive specifies the protocols to use when
264       finding remote shared printers on the network. Multiple  protocols  can
265       be  specified  by  separating  them with spaces.  The default is "dnssd
266       cups".
267
268               BrowseRemoteProtocols none
269               BrowseRemoteProtocols CUPS dnssd
270               BrowseRemoteProtocols CUPS
271               BrowseRemoteProtocols dnssd
272               BrowseRemoteProtocols ldap
273
274       The BrowseProtocols directive specifies the protocols to use when find‐
275       ing  remote shared printers on the network and advertising local shared
276       printers. "dnssd" and  "ldap"  are  ignored  for  BrowseLocalProtocols.
277       Multiple protocols can be specified by separating them with spaces. The
278       default  is  "none"  for  BrowseLocalProtocols  and  "dnssd  cups"  for
279       BrowseRemoteProtocols.
280
281               BrowseProtocols none
282               BrowseProtocols CUPS dnssd
283               BrowseProtocols CUPS
284               BrowseProtocols dnssd
285               BrowseProtocols ldap
286
287       The  configuration  for  the  LDAP  browsing mode define where the LDAP
288       search should be performed. If built with an LDAP library that supports
289       TLS,  the path to the server's certificate, or to a certificates store,
290       can be specified.  The optional filter allows the  LDAP  search  to  be
291       more specific, and is used in addition to the hardcoded filter (object‐
292       class=cupsPrinter).
293
294               BrowseLDAPBindDN cn=cups-browsed,dc=domain,dc=tld
295               BrowseLDAPCACertFile /path/to/server/certificate.pem
296               BrowseLDAPDN ou=printers,dc=domain,dc=tld
297               BrowseLDAPFilter (printerLocation=/Office 1/*)
298               BrowseLDAPPassword s3cret
299               BrowseLDAPServer ldaps://ldap.domain.tld
300
301       The DomainSocket directive specifies the domain  socket  through  which
302       the locally running CUPS daemon is accessed. If not specified the stan‐
303       dard domain socket of CUPS is used. Use this if you have  specified  an
304       alternative   domain   socket  for  CUPS  via  a  Listen  directive  in
305       /etc/cups/cupsd.conf. If cups-browsed is not able to access  the  local
306       CUPS daemon via a domain socket it accesses it via localhost. "None" or
307       "Off" lets cups-browsed not use CUPS' domain socket.
308
309               DomainSocket /var/run/cups/cups.sock
310               DomainSocket None
311               DomainSocket Off
312
313       Set HTTP timeout (in seconds) for requests  sent  to  local/remote  re‐
314       sources  Note  that too short timeouts can make services getting missed
315       when they are present and operations be unnecessarily repeated and  too
316       long  timeouts  can  make operations take too long when the server does
317       not respond.
318
319               HttpLocalTimeout 5
320               HttpRemoteTimeout 10
321
322       Set how many retries (N) should  cups-browsed  do  for  creating  print
323       queues  for  remote  printers which receive timeouts during print queue
324       creation.  The printers which are not successfully set up even after  N
325       retries,  are skipped until the next restart of the service.  Note that
326       too many retries can cause high CPU load.
327
328               HttpMaxRetries 5
329
330       The interval between browsing/broadcasting cycles, local and/or remote,
331       can be adjusted with the BrowseInterval directive.
332
333               BrowseInterval 60
334
335       The  BrowseTimeout  directive determines the amount of time that brows‐
336       ing-related operations are allowed to take in seconds.  Notably, adding
337       or removing one printer queue is considered as one operation. The time‐
338       out applies to each one of those operations.  Especially queues discov‐
339       ered  by  CUPS broadcasts will be removed after this timeout if no fur‐
340       ther broadcast from the server happens.
341
342               BrowseTimeout 300
343
344       The AllowResharingRemoteCUPSPrinters  directive  determines  whether  a
345       print  queue  pointing  to a remote CUPS queue will be re-shared to the
346       local network or not. Since the queues generated using  the  BrowsePoll
347       directive  are also pointing to remote queues, they are also shared au‐
348       tomatically if the following option is set. Default is not to share re‐
349       mote queues.
350
351               AllowResharingRemoteCUPSPrinters Yes
352
353       The  NewBrowsePollQueuesShared  directive  determines  whether  a print
354       queue for a newly discovered printer (discovered by the BrowsePoll  di‐
355       rective)  will  be  shared  to the local network or not. This directive
356       will only work if AllowResharingRemoteCUPSPrinters is set to  yes.  De‐
357       fault is not to share printers discovered using BrowsePoll.
358
359               NewBrowsePollQueuesShared Yes
360
361       Set  OnlyUnsupportedByCUPS  to  "Yes" will make cups-browsed not create
362       local queues for remote printers for which CUPS creates queues  by  it‐
363       self.   These  printers  are  printers  advertised via DNS-SD and doing
364       CUPS-supported (currently  PWG  Raster  and  Apple  Raster)  driverless
365       printing, including remote CUPS queues. Queues for other printers (like
366       for legacy PostScript/PCL printers) are always  created  (depending  on
367       the other configuration settings of cups-browsed).
368
369       With OnlyUnsupportedByCUPS set to "No", cups-browsed creates queues for
370       all printers which it supports, including printers for which CUPS would
371       create  queues  by  itself.  Temporary  queues created by CUPS will get
372       overwritten. This way it is assured that  any  extra  functionality  of
373       cups-browsed  will  apply  to  these queues. As queues created by cups-
374       browsed are permanent CUPS queues this setting is also  recommended  if
375       applications/print  dialogs  which do not support temporary CUPS queues
376       are installed. This setting is the default.
377
378               OnlyUnsupportedByCUPS Yes
379
380       With UseCUPSGeneratedPPDs set to "Yes" cups-browsed creates queues  for
381       IPP  printers  with PPDs generated by the PPD generator of CUPS and not
382       with the one of cups-browsed. So any new development in CUPS' PPD  gen‐
383       erator  gets available. As CUPS' PPD generator is not directly accessi‐
384       ble, we need to make CUPS generate a temporary print queue with the de‐
385       sired PPD. Therefore we can only use these PPDs when our queue replaces
386       a temporary CUPS queue, meaning that the queue  is  for  a  printer  on
387       which  CUPS  supports  driverless  printing  (IPP  2.x,  PDLs: PDF, PWG
388       Raster, and/or Apple Raster) and that its name is the same as CUPS uses
389       for  the  temporary  queue ("LocalQueueNamingIPPPrinter DNS-SD" must be
390       set). The directive applies only to IPP printers, not  to  remote  CUPS
391       queues,  to  not  break clustering. Setting this directive to "No" lets
392       cups-browsed generate the PPD file. Default setting is "No".
393
394               UseCUPSGeneratedPPDs No
395
396       With the directives LocalQueueNamingRemoteCUPS and LocalQueueNamingIPP‐
397       Printer  you  can determine how the names for local queues generated by
398       cups-browsed are generated, separately for remote CUPS printers and IPP
399       printers.
400
401       "DNS-SD"  (the  default  in both cases) bases the naming on the service
402       name of the printer's advertised DNS-SD record.  This  is  exactly  the
403       same  naming scheme as CUPS uses for its temporary queues, so the local
404       queue from cups-browsed prevents CUPS from listing and creating an  ad‐
405       ditional  queue. As DNS-SD service names have to be unique, queue names
406       of printers from different servers will also be unique and so there  is
407       no automatic clustering for load-balanced printing.
408
409       "MakeModel"  bases  the  queue  name  on the printer's manufacturer and
410       model names. This scheme cups-browsed used formerly for IPP printers.
411
412       "RemoteName" is only available for remote CUPS queues and uses the name
413       of  the queue on the remote CUPS server as the local queue's name. This
414       makes printers on different CUPS servers with equal queue  names  auto‐
415       matically  forming  a load-balancing cluster as CUPS did formerly (CUPS
416       1.5.x and older) with CUPS-broadcasted  remote  printers.  This  scheme
417       cups-browsed used formerly for remote CUPS printers.
418
419               LocalQueueNamingRemoteCUPS DNS-SD
420               LocalQueueNamingRemoteCUPS MakeModel
421               LocalQueueNamingRemoteCUPS RemoteName
422               LocalQueueNamingIPPPrinter DNS-SD
423               LocalQueueNamingIPPPrinter MakeModel
424
425       Set  DNSSDBasedDeviceURIs  to  "Yes" if cups-browsed should use DNS-SD-
426       service-name-based device URIs for its local queues, as CUPS also does.
427       These  queues  use  the  DNS-SD service name of the discovered printer.
428       With this the URI is independent of network interfaces and ports,  giv‐
429       ing  reliable connections to always the same physical device. This set‐
430       ting is the default.
431
432       Set DNSSDBasedDeviceURIs to "No" if cups-browsed should use the conven‐
433       tional host-name/IP-based URIs.
434
435       Note  that  this option has only influence on URIs for printers discov‐
436       ered via DNS-SD, not via legacy CUPS broewsing or LDAP.  Those printers
437       get always assigned the conventional URIs.
438
439               DNSSDBasedDeviceURIs Yes
440
441       Set  IPBasedDeviceURIs to "Yes" if cups-browsed should create its local
442       queues with device URIs with the IP addresses instead of the host names
443       of  the  remote  servers. This mode is there for any problems with host
444       name resolution in the network, especially also if avahi-daemon is only
445       run  for printer discovery and already stopped while still printing. By
446       default this mode is turned off, meaning that we  use  URIs  with  host
447       names.
448
449       Note  that  the  IP  addresses  depend on the network interface through
450       which the printer is accessed. So do not use IP-based URIs  on  systems
451       with many network interfaces and where interfaces can appear and disap‐
452       pear frequently.
453
454       This mode could also be useful for development and debugging.
455
456       If you prefer IPv4 or IPv6 IP addresses in the URIs, you  can  set  IP‐
457       BasedDeviceURIs  to  "IPv4" to only get IPv4 IP addresses or IPBasedDe‐
458       viceURIs to "IPv6" to only get IPv6 IP addresses.
459
460               IPBasedDeviceURIs No
461               IPBasedDeviceURIs Yes
462               IPBasedDeviceURIs IPv4
463               IPBasedDeviceURIs IPv6
464
465       Set CreateRemoteRawPrinterQueues to "Yes" to let cups-browsed also cre‐
466       ate  local  queues  pointing  to remote raw CUPS queues. Normally, only
467       queues pointing to remote queues with PPD/driver are created as  we  do
468       not  use  drivers on the client side, but in some cases accessing a re‐
469       mote raw queue can make sense, for example if the  queue  forwards  the
470       jobs by a special backend like Tea4CUPS.
471
472               CreateRemoteRawPrinterQueues Yes
473
474       cups-browsed by default creates local print queues for each shared CUPS
475       print queue which it discovers on remote machines  in  the  local  net‐
476       work(s).  Set  CreateRemoteCUPSPrinterQueues to "No" if you do not want
477       cups-browsed to do this. For example you can set cups-browsed  to  only
478       create  queues  for IPP network printers setting CreateIPPPrinterQueues
479       not to "No" and CreateRemoteCUPSPrinterQueues to "No".
480
481               CreateRemoteCUPSPrinterQueues No
482
483       Set CreateIPPPrinterQueues to "All" to let  cups-browsed  discover  IPP
484       network printers (native printers, not CUPS queues) with known page de‐
485       scription languages (PWG Raster, PDF, PostScript, PCL XL, PCL 5c/e)  in
486       the local network and auto-create print queues for them.
487
488       Set CreateIPPPrinterQueues to "Everywhere" to let cups-browsed discover
489       IPP Everywhere printers in the local network (native printers, not CUPS
490       queues) and auto-create print queues for them.
491
492       Set  CreateIPPPrinterQueues  to  "AppleRaster" to let cups-browsed dis‐
493       cover Apple Raster printers in the local network (native printers,  not
494       CUPS queues) and auto-create print queues for them.
495
496       Set CreateIPPPrinterQueues to "Driverless" to let cups-browsed discover
497       printers designed for driverless use (currently IPP Everywhere and  Ap‐
498       ple Raster) in the local network (native printers, not CUPS queues) and
499       auto-create print queues for them.
500
501       Set CreateIPPPrinterQueues to "LocalOnly" to auto-create  print  queues
502       only  for  local printers made available as IPP printers. These are for
503       example IPP-over-USB printers, made available via ippusbxd(8). This  is
504       the default.
505
506       Set  CreateIPPPrinterQueues to "No" to not auto-create print queues for
507       IPP network printers.
508
509       If queues with PPD file are created (see IPPPrinterQueueType  directive
510       below)  the PPDs are auto-generated by cups-browsed based on properties
511       of the printer polled via IPP. In case  of  missing  information,  info
512       from the Bonjour record is used asd as last mean default values.
513
514       If  queues  without  PPD  (see IPPPrinterQueueType directive below) are
515       created clients have to IPP-poll the capabilities of  the  printer  and
516       send  option  settings  as standard IPP attributes. Then we do not poll
517       the capabilities by ourselves to not wake up the  printer  from  power-
518       saving  mode  when  creating the queues. Jobs have to be sent in one of
519       PDF, PWG Raster, or JPEG format. Other formats are not accepted.
520
521       This functionality is primarily for mobile devices running CUPS to  not
522       need a printer setup tool nor a collection of printer drivers and PPDs.
523
524               CreateIPPPrinterQueues No
525               CreateIPPPrinterQueues LocalOnly
526               CreateIPPPrinterQueues Everywhere
527               CreateIPPPrinterQueues AppleRaster
528               CreateIPPPrinterQueues Everywhere AppleRaster
529               CreateIPPPrinterQueues Driverless
530               CreateIPPPrinterQueues All
531
532       If  cups-browsed  is automatically creating print queues for native IPP
533       network printers ("CreateIPPPrinterQueues Yes"), the type of  queue  to
534       be  created can be selected by the "IPPPrinterQueueType" directive. The
535       "PPD" (default) setting makes queues with PPD file being created.  With
536       "Interface"  or  "NoPPD" the queue is created with a System V interface
537       script (Not supported with CUPS 2.2.x or later). "Auto" is for backward
538       compatibility and also lets queues with PPD get created.
539
540               IPPPrinterQueueType PPD
541               IPPPrinterQueueType NoPPD
542               IPPPrinterQueueType Interface
543               IPPPrinterQueueType Auto
544
545       The  NewIPPPrinterQueuesShared  directive  determines  whether  a print
546       queue for a newly discovered  IPP  network  printer  (not  remote  CUPS
547       queue)  will  be shared to the local network or not. This is only valid
548       for newly discovered printers. For printers discovered  in  an  earlier
549       cups-browsed  session,  cups-browsed  will remember whether the printer
550       was shared, so changes by the user get conserved.  Default  is  not  to
551       share newly discovered IPP printers.
552
553               NewIPPPrinterQueuesShared Yes
554
555       How  to  handle the print queues cups-browsed creates when cups-browsed
556       is shut down:
557
558       "KeepGeneratedQueuesOnShutdown No" makes the queues being removed. This
559       makes  sense  as  these queues only work while cups-browsed is running.
560       cups-browsed has to determine to which member printer of a  cluster  to
561       pass on the job.
562
563       "KeepGeneratedQueuesOnShutdown  Yes" (the default) makes the queues not
564       being removed. This is the recommended setting for a system where cups-
565       browsed  is  permanently running and only stopped for short times (like
566       log rotation) or on shutdown. This avoids the re-creation of the queues
567       when  cups-browsed  is  restarted, which often causes a clutter of CUPS
568       notifications on the desktop.
569
570               KeepGeneratedQueuesOnShutdown No
571
572       If there is more than one remote CUPS printer whose local  queue  would
573       get the same name and AutoClustering is set to "Yes" (the default) only
574       one local queue is created which makes up a load-balancing  cluster  of
575       the  remote  printers which would get this queue name (implicit class).
576       This means that when several jobs are sent to this queue they get  dis‐
577       tributed  between the printers, using the method chosen by the LoadBal‐
578       ancing directive.
579
580       Note that the forming of clusters depends on the naming scheme for  lo‐
581       cal queues created by cups-browsed. If you have set LocalQueueNamingRe‐
582       moteCUPS to "DNSSD" you will not get automatic clustering as the DNS-SD
583       service names are always unique. With LocalQueueNamingRemoteCUPS set to
584       "RemoteName" local queues are named as the CUPS queues  on  the  remote
585       servers  are named and so equally named queues on different servers get
586       clustered (this is how CUPS did it in  version  1.5.x  or  older).  Lo‐
587       calQueueNamingRemoteCUPS  set  to  "MakeModel" makes remote printers of
588       the same model get clustered. Note that then a cluster can contain more
589       than one queue of the same server.
590
591       With  AutoClustering set to "No", for each remote CUPS printer an indi‐
592       vidual local queue is created, and to avoid name clashes when using the
593       LocalQueueNamingRemoteCUPS   settings   "RemoteName"   or   "MakeModel"
594       "@<server name>" is added to the local queue name.
595
596       Only remote CUPS printers get clustered, not IPP  network  printers  or
597       IPP-over-USB printers.
598
599               AutoClustering Yes
600               AutoClustering No
601
602       Load-balancing  printer  cluster  formation  can  also be manually con‐
603       trolled by defining explicitly which remote CUPS  printers  should  get
604       clustered together.
605
606       This is done by the "Cluster" directive:
607
608               Cluster <QUEUENAME>: <EXPRESSION1> <EXPRESSION2> ...
609               Cluster <QUEUENAME>
610
611       If  no expressions are given, <QUEUENAME> is used as the first and only
612       expression for this cluster.
613
614       Discovered printers are matched against all the expressions of all  de‐
615       fined  clusters.  The  first  expression  which  matches the discovered
616       printer determines to which cluster it belongs. Note that  this  way  a
617       printer  can  only belong to one cluster. Once matched, further cluster
618       definitions will not checked any more.
619
620       With the first printer matching a cluster's expression  a  local  queue
621       with  the  name <QUEUENAME> is created. If more printers are discovered
622       and match this cluster, they join the cluster. Printing to  this  queue
623       prints  to  all these printers in a load-balancing manner, according to
624       to the setting of the LoadBalancing directive.
625
626       Each expression must be a string of characters without spaces. If  spa‐
627       ces are needed, replace them by underscores ('_').
628
629       An expression can be matched in three ways:
630
631           1. By the name of the CUPS queue on the remote server
632           2. By make and model name of the remote printer
633           3. By the DNS-SD service name of the remote printer
634
635       Note that the matching is done case-insensitively and any group of non-
636       alphanumerical characters is replaced by a single underscore.
637
638       So if an expression is "HP_DeskJet_2540" and the remote server  reports
639       "hp Deskjet-2540" the printer gets matched to this cluster.
640
641       If "AutoClustering" is not set to "No" both your manual cluster defini‐
642       tions will be followed and automatic clustering of equally-named remote
643       queues  will  be performed. If a printer matches in both categories the
644       match to the manually defined cluster has priority. Automatic  cluster‐
645       ing  of  equally-named  remote  printers is not performed if there is a
646       manually defined cluster with this name (at least as  the  printers  do
647       not match this cluster).
648
649       Examples:
650
651       To  cluster  all  remote CUPS queues named "laserprinter" in your local
652       network but not cluster any other equally-named  remote  CUPS  printers
653       use (Local queue will get named "laserprinter"):
654
655               AutoClustering No
656               Cluster laserprinter
657
658       To cluster all remote CUPS queues of HP LaserJet 4050 printers in a lo‐
659       cal queue named "LJ4050":
660
661               Cluster LJ4050: HP_LaserJet_4050
662
663       As DNS-SD service names are unique in a network you can create a  clus‐
664       ter from exactly specified printers (spaces replaced by underscores):
665
666               Cluster hrdep: oldlaser_@_hr-server1 newlaser_@_hr-server2
667
668       The  LoadBalancing  directive  switches between two methods of handling
669       load balancing between equally-named remote  queues  which  are  repre‐
670       sented  by  one local print queue making up a cluster of them (implicit
671       class).
672
673       The two methods are:
674
675       Queuing of jobs on the client (LoadBalancing QueueOnClient):
676
677       Here we queue up the jobs on the client and regularly check  the  clus‐
678       tered  remote  print queues. If we find an idle queue, we pass on a job
679       to it.
680
681       This is also the method which CUPS uses for  classes.  Advantage  is  a
682       more  even  distribution of the job workload on the servers (especially
683       if the printing speed of the servers  is  very  different),  and  if  a
684       server fails, there are not several jobs stuck or lost. Disadvantage is
685       that if one takes the client (laptop, mobile phone, ...) out of the lo‐
686       cal network, printing stops with the jobs waiting in the local queue.
687
688       Queuing of jobs on the servers (LoadBalancing QueueOnServers):
689
690       Here we check the number of jobs on each of the clustered remote print‐
691       ers and send an incoming job immediately to the remote printer with the
692       lowest  amount of jobs in its queue. This way no jobs queue up locally,
693       all jobs which are waiting are waiting on one of the remote servers.
694
695       Not having jobs waiting locally has the advantage that we can take  the
696       local  machine from the network and all jobs get printed.  Disadvantage
697       is that if a server with a full queue of jobs goes away,  the  jobs  go
698       away, too.
699
700       Default  is  queuing  the  jobs on the client as this is what CUPS does
701       with classes.
702
703               LoadBalancing QueueOnClient
704               LoadBalancing QueueOnServers
705
706       With the DefaultOptions directive one or more option  settings  can  be
707       defined  to  be  applied  to  every  print queue newly created by cups-
708       browsed. Each option is supplied as one supplies options with the  "-o"
709       command  line  argument to the "lpadmin" command (Run "man lpadmin" for
710       more details). More than one option can be supplied separating the  op‐
711       tions by spaces. By default no option settings are pre-defined.
712
713       Note that print queues which cups-browsed already created before remem‐
714       ber their previous settings and so these settings do not get applied.
715
716               DefaultOptions Option1=Value1 Option2=Value2 Option3 noOption4
717
718       The AutoShutdown directive specifies whether cups-browsed should  auto‐
719       matically  terminate when it has no local raw queues set up pointing to
720       any discovered remote printers or no jobs on such queues  depending  on
721       AutoShutdownOn  setting  (auto shutdown mode). Setting it to "On" acti‐
722       vates the auto-shutdown mode, setting it to "Off" deactivates  it  (the
723       default). The special mode "avahi" turns auto shutdown off while avahi-
724       daemon is running and on when avahi-daemon stops. This  allows  running
725       cups-browsed on-demand when avahi-daemon is run on-demand.
726
727               AutoShutdown Off
728               AutoShutdown On
729               AutoShutdown avahi
730
731       The AutoShutdownOn directive determines what event cups-browsed consid‐
732       ers as inactivity in auto shutdown mode. "NoQueues" (the default) means
733       that auto shutdown is initiated when there are no queues for discovered
734       remote printers generated by cups-browsed any more. "NoJobs" means that
735       all queues generated by cups-browsed are without jobs.
736
737               AutoShutdownOn NoQueues
738               AutoShutdownOn NoJobs
739
740       DebugLogFileSize  defines  the maximum size possible (in KBytes) of the
741       log files (cups-browsed_log  and  cups-browsed_previous_logs)  that  is
742       created using cups-browsed in the debugging mode.  Setting its value to
743       0 would turn off any restriction on the size of the file.
744
745               DebugLogFileSize 300
746
747       The AutoShutdownTimeout directive  specifies  after  how  many  seconds
748       without  local  raw  queues  set  up  pointing to any discovered remote
749       printers or jobs on these queues cups-browsed should actually shut down
750       in  auto  shutdown mode. Default is 30 seconds, 0 means immediate shut‐
751       down.
752
753               AutoShutdownTimeout 20
754
755       NotifLeaseDuration defines how long the D-BUS subscription  created  by
756       cups-browsed  in  cupsd  will last before cupsd cancels it. The default
757       value is 1 day in seconds - 86400. The subscription renewal is  set  to
758       happen after half of NotifLeaseDuration passed. The D-BUS notifications
759       are used for watching over queues and doing specific actions when a  D-
760       BUS notification comes.
761
762               NotifLeaseDuration 86400
763       FrequentNetifUpdate  turns on/off the network interface update routines
764       which happen for each found entry, which can slow up cups-browsed  sig‐
765       nificantly  if  we  are on a network with many shared printers or if we
766       use BrowsePoll to a server with many queues. Network interface  updates
767       after  receiving D-BUS notification from NetworkManager won't be turned
768       off with the directive. The default value is 'Yes'.
769
770               FrequentNetifUpdate Yes
771

SEE ALSO

773       cups-browsed(8)
774
775       /usr/share/doc/cups-browsed/README.gz
776

AUTHOR

778       The  authors  of  cups-browsed  are  listed   in   /usr/share/doc/cups-
779       browsed/AUTHORS.
780
781       This manual page was written for the Debian Project, but it may be used
782       by others.
783
784
785
786                                 29 June 2013             cups-browsed.conf(5)
Impressum