1cups-browsed.conf(5) cups-browsed.conf(5)
2
3
4
6 cups-browsed.conf - server configuration file for cups-browsed
7
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
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
765 cups-browsed(8)
766
767 /usr/share/doc/cups-browsed/README.gz
768
770 The authors of cups-browsed are listed in /usr/share/doc/cups-
771 browsed/AUTHORS.
772
773 This manual page was written for the Debian Project, but it may be used
774 by others.
775
776
777
778 29 June 2013 cups-browsed.conf(5)