1MOSQUITTO.CONF(5) File formats and conventions MOSQUITTO.CONF(5)
2
3
4
6 mosquitto.conf - the configuration file for mosquitto
7
9 mosquitto.conf
10
12 mosquitto.conf is the configuration file for mosquitto. This file can
13 reside anywhere as long as mosquitto can read it. By default, mosquitto
14 does not need a configuration file and will use the default values
15 listed below. See mosquitto(8) for information on how to load a
16 configuration file.
17
18 Mosquitto can be instructed to reload the configuration file by sending
19 a SIGHUP signal as described in the Signals section of mosquitto(8).
20 Not all configuration options can be reloaded, as detailed in the
21 options below.
22
24 All lines with a # as the very first character are treated as a
25 comment.
26
27 Configuration lines start with a variable name. The variable value is
28 separated from the name by a single space.
29
31 The authentication options described below allow a wide range of
32 possibilities in conjunction with the listener options. This section
33 aims to clarify the possibilities. An overview is also available at
34 https://mosquitto.org/documentation/authentication-methods/
35
36 The simplest option is to have no authentication at all. This is the
37 default if no other options are given. Unauthenticated encrypted
38 support is provided by using the certificate based SSL/TLS based
39 options certfile and keyfile.
40
41 MQTT provides username/password authentication as part of the protocol.
42 Use the password_file option to define the valid usernames and
43 passwords. Be sure to use network encryption if you are using this
44 option otherwise the username and password will be vulnerable to
45 interception. Use the per_listener_settings to control whether
46 passwords are required globally or on a per-listener basis.
47
48 Mosquitto provides the Dynamic Security plugin which handles
49 username/password authentication and access control in a much more
50 flexible way than a password file. See
51 https://mosquitto.org/documentation/dynamic-security/
52
53 When using certificate based encryption there are three options that
54 affect authentication. The first is require_certificate, which may be
55 set to true or false. If false, the SSL/TLS component of the client
56 will verify the server but there is no requirement for the client to
57 provide anything for the server: authentication is limited to the MQTT
58 built in username/password. If require_certificate is true, the client
59 must provide a valid certificate in order to connect successfully. In
60 this case, the second and third options, use_identity_as_username and
61 use_subject_as_username, become relevant. If set to true,
62 use_identity_as_username causes the Common Name (CN) from the client
63 certificate to be used instead of the MQTT username for access control
64 purposes. The password is not used because it is assumed that only
65 authenticated clients have valid certificates. This means that any CA
66 certificates you include in cafile or capath will be able to issue
67 client certificates that are valid for connecting to your broker. If
68 use_identity_as_username is false, the client must authenticate as
69 normal (if required by password_file) through the MQTT options. The
70 same principle applies for the use_subject_as_username option, but the
71 entire certificate subject is used as the username instead of just the
72 CN.
73
74 When using pre-shared-key based encryption through the psk_hint and
75 psk_file options, the client must provide a valid identity and key in
76 order to connect to the broker before any MQTT communication takes
77 place. If use_identity_as_username is true, the PSK identity is used
78 instead of the MQTT username for access control purposes. If
79 use_identity_as_username is false, the client may still authenticate
80 using the MQTT username/password if using the password_file option.
81
82 Both certificate and PSK based encryption are configured on a
83 per-listener basis.
84
85 Authentication plugins can be created to augment the password_file,
86 acl_file and psk_file options with e.g. SQL based lookups.
87
88 It is possible to support multiple authentication schemes at once. A
89 config could be created that had a listener for all of the different
90 encryption options described above and hence a large number of ways of
91 authenticating.
92
94 acl_file file path
95 Set the path to an access control list file. If defined, the
96 contents of the file are used to control client access to topics on
97 the broker.
98
99 If this parameter is defined then only the topics listed will have
100 access. Topic access is added with lines of the format:
101
102 topic [read|write|readwrite|deny] <topic>
103
104 The access type is controlled using "read", "write", "readwrite" or
105 "deny". This parameter is optional (unless <topic> includes a space
106 character) - if not given then the access is read/write. <topic>
107 can contain the + or # wildcards as in subscriptions. The "deny"
108 option can used to explicitly deny access to a topic that would
109 otherwise be granted by a broader read/write/readwrite statement.
110 Any "deny" topics are handled before topics that grant read/write
111 access.
112
113 The first set of topics are applied to anonymous clients, assuming
114 allow_anonymous is true. User specific topic ACLs are added after a
115 user line as follows:
116
117 user <username>
118
119 The username referred to here is the same as in password_file. It
120 is not the clientid.
121
122 It is also possible to define ACLs based on pattern substitution
123 within the topic. The form is the same as for the topic keyword,
124 but using pattern as the keyword.
125
126 pattern [read|write|readwrite|deny] <topic>
127
128 The patterns available for substition are:
129
130 • %c to match the client id of the client
131
132 • %u to match the username of the client
133
134 The substitution pattern must be the only text for that level of
135 hierarchy. Pattern ACLs apply to all users even if the "user"
136 keyword has previously been given.
137
138 Example:
139
140 pattern write sensor/%u/data
141
142 Allow access for bridge connection messages:
143
144 pattern write $SYS/broker/connection/%c/state
145
146 If the first character of a line of the ACL file is a # it is
147 treated as a comment.
148
149 If per_listener_settings is true, this option applies to the
150 current listener being configured only. If per_listener_settings is
151 false, this option applies to all listeners.
152
153 Reloaded on reload signal. The currently loaded ACLs will be freed
154 and reloaded. Existing subscriptions will be affected after the
155 reload.
156
157 See also https://mosquitto.org/documentation/dynamic-security/
158
159 allow_anonymous [ true | false ]
160 Boolean value that determines whether clients that connect without
161 providing a username are allowed to connect. If set to false then
162 another means of connection should be created to control
163 authenticated client access.
164
165 Defaults to false, unless no listeners are defined in the
166 configuration file, in which case it set to true, but connections
167 are only allowed from the local machine.
168
169 If per_listener_settings is true, this option applies to the
170 current listener being configured only. If per_listener_settings is
171 false, this option applies to all listeners.
172
173 Important
174 In version 1.6.x and earlier, this option defaulted to true
175 unless there was another security option set.
176 Reloaded on reload signal.
177
178 allow_duplicate_messages [ true | false ]
179 This option is deprecated and will be removed in a future version.
180 The behaviour will default to true.
181
182 If a client is subscribed to multiple subscriptions that overlap,
183 e.g. foo/# and foo/+/baz , then MQTT expects that when the broker
184 receives a message on a topic that matches both subscriptions, such
185 as foo/bar/baz, then the client should only receive the message
186 once.
187
188 Mosquitto keeps track of which clients a message has been sent to
189 in order to meet this requirement. This option allows this
190 behaviour to be disabled, which may be useful if you have a large
191 number of clients subscribed to the same set of topics and want to
192 minimise memory usage.
193
194 It can be safely set to true if you know in advance that your
195 clients will never have overlapping subscriptions, otherwise your
196 clients must be able to correctly deal with duplicate messages even
197 when then have QoS=2.
198
199 Defaults to true.
200
201 This option applies globally.
202
203 Reloaded on reload signal.
204
205 allow_zero_length_clientid [ true | false ]
206 MQTT 3.1.1 and MQTT 5 allow clients to connect with a zero length
207 client id and have the broker generate a client id for them. Use
208 this option to allow/disallow this behaviour. Defaults to true.
209
210 See also the auto_id_prefix option.
211
212 If per_listener_settings is true, this option applies to the
213 current listener being configured only. If per_listener_settings is
214 false, this option applies to all listeners.
215
216 Reloaded on reload signal.
217
218 auth_plugin_deny_special_chars [ true | false ]
219 If true then before an ACL check is made, the username/client id of
220 the client needing the check is searched for the presence of either
221 a '+' or '#' character. If either of these characters is found in
222 either the username or client id, then the ACL check is denied
223 before it is sent to the plugin.
224
225 This check prevents the case where a malicious user could
226 circumvent an ACL check by using one of these characters as their
227 username or client id. This is the same issue as was reported with
228 mosquitto itself as CVE-2017-7650.
229
230 If you are entirely sure that the plugin you are using is not
231 vulnerable to this attack (i.e. if you never use usernames or
232 client ids in topics) then you can disable this extra check and
233 hence have all ACL checks delivered to your plugin by setting this
234 option to false.
235
236 Defaults to true.
237
238 Applies to the current authentication plugin being configured.
239
240 Not currently reloaded on reload signal.
241
242 auto_id_prefix prefix
243 If allow_zero_length_clientid is true, this option allows you to
244 set a string that will be prefixed to the automatically generated
245 client ids to aid visibility in logs. Defaults to auto-.
246
247 If per_listener_settings is true, this option applies to the
248 current listener being configured only. If per_listener_settings is
249 false, this option applies to all listeners.
250
251 Reloaded on reload signal.
252
253 autosave_interval seconds
254 The number of seconds that mosquitto will wait between each time it
255 saves the in-memory database to disk. If set to 0, the in-memory
256 database will only be saved when mosquitto exits or when receiving
257 the SIGUSR1 signal. Note that this setting only has an effect if
258 persistence is enabled. Defaults to 1800 seconds (30 minutes).
259
260 This option applies globally.
261
262 Reloaded on reload signal.
263
264 autosave_on_changes [ true | false ]
265 If true, mosquitto will count the number of subscription changes,
266 retained messages received and queued messages and if the total
267 exceeds autosave_interval then the in-memory database will be saved
268 to disk. If false, mosquitto will save the in-memory database to
269 disk by treating autosave_interval as a time in seconds.
270
271 This option applies globally.
272
273 Reloaded on reload signal.
274
275 check_retain_source [ true | false ]
276 This option affects the scenario when a client subscribes to a
277 topic that has retained messages. It is possible that the client
278 that published the retained message to the topic had access at the
279 time they published, but that access has been subsequently removed.
280 If check_retain_source is set to true, the default, the source of a
281 retained message will be checked for access rights before it is
282 republished. When set to false, no check will be made and the
283 retained message will always be published.
284
285 This option applies globally, regardless of the
286 per_listener_settings option.
287
288 clientid_prefixes prefix
289 This option is deprecated and will be removed in a future version.
290
291 If defined, only clients that have a clientid with a prefix that
292 matches clientid_prefixes will be allowed to connect to the broker.
293 For example, setting "secure-" here would mean a client
294 "secure-client" could connect but another with clientid "mqtt"
295 couldn't. By default, all client ids are valid.
296
297 This option applies globally.
298
299 Reloaded on reload signal. Note that currently connected clients
300 will be unaffected by any changes.
301
302 connection_messages [ true | false ]
303 If set to true, the log will include entries when clients connect
304 and disconnect. If set to false, these entries will not appear.
305
306 This option applies globally.
307
308 Reloaded on reload signal.
309
310 include_dir dir
311 External configuration files may be included by using the
312 include_dir option. This defines a directory that will be searched
313 for config files. All files that end in '.conf' will be loaded as a
314 configuration file. It is best to have this as the last option in
315 the main file. This option will only be processed from the main
316 configuration file. The directory specified must not contain the
317 main configuration file.
318
319 The configuration files in include_dir are loaded in case sensitive
320 alphabetical order, with the upper case of each letter ordered
321 before the lower case of the same letter.
322
323 Example Load Order for include_dir. Given the files b.conf,
324 A.conf, 01.conf, a.conf, B.conf, and 00.conf inside include_dir,
325 the config files would be loaded in this order:
326
327 00.conf
328 01.conf
329 A.conf
330 a.conf
331 B.conf
332 b.conf
333
334 If this option is used multiple times, then each include_dir option
335 is processed completely in the order that they are written in the
336 main configuration file.
337
338 Example Load Order for Multiple include_dir. Assuming a directory
339 one.d containing files B.conf and C.conf, and a second directory
340 two.d containing files A.conf and D.conf, and a config:
341
342 include_dir one.d
343 include_dir two.d
344
345 Then the config files would be loaded in this order:
346
347 # files from one.d
348 B.conf
349 C.conf
350 # files from two.d
351 A.conf
352 D.conf
353
354 log_dest destinations
355 Send log messages to a particular destination. Possible
356 destinations are: stdout stderr syslog topic file dlt.
357
358 stdout and stderr log to the console on the named output.
359
360 syslog uses the userspace syslog facility which usually ends up in
361 /var/log/messages or similar.
362
363 topic logs to the broker topic '$SYS/broker/log/<severity>', where
364 severity is one of E, W, N, I, M which are error, warning, notice,
365 information and message. Message type severity is used by the
366 subscribe and unsubscribe log_type options and publishes log
367 messages at $SYS/broker/log/M/subscribe and
368 $SYS/broker/log/M/unsubscribe. Debug messages are never logged on
369 topics.
370
371 The file destination requires an additional parameter which is the
372 file to be logged to, e.g. "log_dest file /var/log/mosquitto.log".
373 The file will be closed and reopened when the broker receives a HUP
374 signal. Only a single file destination may be configured.
375
376 The dlt destination is for the automotive `Diagnostic Log and
377 Trace` tool. This requires that Mosquitto has been compiled with
378 DLT support.
379
380 Use "log_dest none" if you wish to disable logging. Defaults to
381 stderr. This option may be specified multiple times.
382
383 Note that if the broker is running as a Windows service it will
384 default to "log_dest none" and neither stdout nor stderr logging is
385 available.
386
387 Reloaded on reload signal.
388
389 log_facility local facility
390 If using syslog logging (not on Windows), messages will be logged
391 to the "daemon" facility by default. Use the log_facility option to
392 choose which of local0 to local7 to log to instead. The option
393 value should be an integer value, e.g. "log_facility 5" to use
394 local5.
395
396 log_timestamp [ true | false ]
397 Boolean value, if set to true a timestamp value will be added to
398 each log entry. The default is true.
399
400 Reloaded on reload signal.
401
402 log_timestamp_format format
403 Set the format of the log timestamp. If left unset, this is the
404 number of seconds since the Unix epoch. This option is a free text
405 string which will be passed to the strftime function as the format
406 specifier. To get an ISO 8601 datetime, for example:
407
408 log_timestamp_format %Y-%m-%dT%H:%M:%S
409
410
411 Reloaded on reload signal.
412
413 log_type types
414 Choose types of messages to log. Possible types are: debug, error,
415 warning, notice, information, subscribe, unsubscribe, websockets,
416 none, all.
417
418 Defaults to error, warning, notice and information. This option may
419 be specified multiple times. Note that the debug type (used for
420 decoding incoming/outgoing network packets) is never logged in
421 topics.
422
423 Reloaded on reload signal.
424
425 max_inflight_bytes count
426 Outgoing QoS 1 and 2 messages will be allowed in flight until this
427 byte limit is reached. This allows control of outgoing message rate
428 based on message size rather than message count. If the limit is
429 set to 100, messages of over 100 bytes are still allowed, but only
430 a single message can be in flight at once. Defaults to 0. (No
431 limit).
432
433 See also the max_inflight_messages option.
434
435 This option applies globally.
436
437 Reloaded on reload signal.
438
439 max_inflight_messages count
440 The maximum number of outgoing QoS 1 or 2 messages that can be in
441 the process of being transmitted simultaneously. This includes
442 messages currently going through handshakes and messages that are
443 being retried. Defaults to 20. Set to 0 for no maximum. If set to
444 1, this will guarantee in-order delivery of messages.
445
446 This option applies globally.
447
448 Reloaded on reload signal.
449
450 max_keepalive value
451 For MQTT v5 clients, it is possible to have the server send a
452 "server keepalive" value that will override the keepalive value set
453 by the client. This is intended to be used as a mechanism to say
454 that the server will disconnect the client earlier than it
455 anticipated, and that the client should use the new keepalive
456 value. The max_keepalive option allows you to specify that clients
457 may only connect with keepalive less than or equal to this value,
458 otherwise they will be sent a server keepalive telling them to use
459 max_keepalive. This only applies to MQTT v5 clients. The maximum
460 value allowable, and default value, is 65535.
461
462 Set to 0 to allow clients to set keepalive = 0, which means no
463 keepalive checks are made and the client will never be disconnected
464 by the broker if no messages are received. You should be very sure
465 this is the behaviour that you want.
466
467 For MQTT v3.1.1 and v3.1 clients, there is no mechanism to tell the
468 client what keepalive value they should use. If an MQTT v3.1.1 or
469 v3.1 client specifies a keepalive time greater than max_keepalive
470 they will be sent a CONNACK message with the "identifier rejected"
471 reason code, and disconnected.
472
473 This option applies globally.
474
475 Reloaded on reload signal.
476
477 max_packet_size value
478 For MQTT v5 clients, it is possible to have the server send a
479 "maximum packet size" value that will instruct the client it will
480 not accept MQTT packets with size greater than value bytes. This
481 applies to the full MQTT packet, not just the payload. Setting this
482 option to a positive value will set the maximum packet size to that
483 number of bytes. If a client sends a packet which is larger than
484 this value, it will be disconnected. This applies to all clients
485 regardless of the protocol version they are using, but v3.1.1 and
486 earlier clients will of course not have received the maximum packet
487 size information. Defaults to no limit.
488
489 This option applies to all clients, not just those using MQTT v5,
490 but it is not possible to notify clients using MQTT v3.1.1 or MQTT
491 v3.1 of the limit.
492
493 Setting below 20 bytes is forbidden because it is likely to
494 interfere with normal client operation even with small payloads.
495
496 This option applies globally.
497
498 Reloaded on reload signal.
499
500 max_queued_bytes count
501 The number of outgoing QoS 1 and 2 messages above those currently
502 in-flight will be queued (per client) by the broker. Once this
503 limit has been reached, subsequent messages will be silently
504 dropped. This is an important option if you are sending messages at
505 a high rate and/or have clients who are slow to respond or may be
506 offline for extended periods of time. Defaults to 0. (No maximum).
507
508 See also the max_queued_messages option. If both
509 max_queued_messages and max_queued_bytes are specified, packets
510 will be queued until the first limit is reached.
511
512 This option applies globally.
513
514 Reloaded on reload signal.
515
516 max_queued_messages count
517 The maximum number of QoS 1 or 2 messages to hold in the queue (per
518 client) above those messages that are currently in flight. Defaults
519 to 1000. Set to 0 for no maximum (not recommended). See also the
520 queue_qos0_messages and max_queued_bytes options.
521
522 This option applies globally.
523
524 Reloaded on reload signal.
525
526 memory_limit limit
527 This option sets the maximum number of heap memory bytes that the
528 broker will allocate, and hence sets a hard limit on memory use by
529 the broker. Memory requests that exceed this value will be denied.
530 The effect will vary depending on what has been denied. If an
531 incoming message is being processed, then the message will be
532 dropped and the publishing client will be disconnected. If an
533 outgoing message is being sent, then the individual message will be
534 dropped and the receiving client will be disconnected. Defaults to
535 no limit.
536
537 This option is only available if memory tracking support is
538 compiled in.
539
540 Reloaded on reload signal. Setting to a lower value and reloading
541 will not result in memory being freed.
542
543 message_size_limit limit
544 This option sets the maximum publish payload size that the broker
545 will allow. Received messages that exceed this size will not be
546 accepted by the broker. This means that the message will not be
547 forwarded on to subscribing clients, but the QoS flow will be
548 completed for QoS 1 or QoS 2 messages. MQTT v5 clients using QoS 1
549 or QoS 2 will receive a PUBACK or PUBREC with the "implementation
550 specific error" reason code.
551
552 The default value is 0, which means that all valid MQTT messages
553 are accepted. MQTT imposes a maximum payload size of 268435455
554 bytes.
555
556 This option applies globally.
557
558 Reloaded on reload signal.
559
560 password_file file path
561 Set the path to a password file. If defined, the contents of the
562 file are used to control client access to the broker. The file can
563 be created using the mosquitto_passwd(1) utility. If mosquitto is
564 compiled without TLS support (it is recommended that TLS support is
565 included), then the password file should be a text file with each
566 line in the format "username:password", where the colon and
567 password are optional but recommended. If allow_anonymous is set to
568 false, only users defined in this file will be able to connect.
569 Setting allow_anonymous to true when password_fileis defined is
570 valid and could be used with acl_file to have e.g. read only
571 guest/anonymous accounts and defined users that can publish.
572
573 If per_listener_settings is true, this option applies to the
574 current listener being configured only. If per_listener_settings is
575 false, this option applies to all listeners.
576
577 Reloaded on reload signal. The currently loaded username and
578 password data will be freed and reloaded. Clients that are already
579 connected will not be affected.
580
581 See also mosquitto_passwd(1) and
582 https://mosquitto.org/documentation/dynamic-security/
583
584 per_listener_settings [ true | false ]
585 If true, then authentication and access control settings will be
586 controlled on a per-listener basis. The following options are
587 affected:
588
589 password_file, acl_file, psk_file, allow_anonymous,
590 allow_zero_length_clientid, auto_id_prefix. plugin,
591 plugin_opt_*,
592 Note that if set to true, then a durable
593 client (i.e. with clean session set to false) that has disconnected
594 will use the ACL settings defined for the listener that it was most
595 recently connected to.
596
597 The default behaviour is for this to be set to false, which
598 maintains the settings behaviour from previous versions of
599 mosquitto.
600
601 Reloaded on reload signal.
602
603 persistence [ true | false ]
604 If true, connection, subscription and message data will be written
605 to the disk in mosquitto.db at the location dictated by
606 persistence_location. When mosquitto is restarted, it will reload
607 the information stored in mosquitto.db. The data will be written to
608 disk when mosquitto closes and also at periodic intervals as
609 defined by autosave_interval. Writing of the persistence database
610 may also be forced by sending mosquitto the SIGUSR1 signal. If
611 false, the data will be stored in memory only. Defaults to false.
612
613 The persistence file may change its format in a new version. The
614 broker can currently read all old formats, but will only save in
615 the latest format. It should always be safe to upgrade, but
616 cautious users may wish to take a copy of the persistence file
617 before installing a new version so that they can roll back to an
618 earlier version if necessary.
619
620 This option applies globally.
621
622 Reloaded on reload signal.
623
624 persistence_file file name
625 The filename to use for the persistent database. Defaults to
626 mosquitto.db.
627
628 This option applies globally.
629
630 Reloaded on reload signal.
631
632 persistence_location path
633 The path where the persistence database should be stored. If not
634 given, then the current directory is used.
635
636 This option applies globally.
637
638 Reloaded on reload signal.
639
640 persistent_client_expiration duration
641 This option allows the session of persistent clients (those with
642 clean session set to false) that are not currently connected to be
643 removed if they do not reconnect within a certain time frame. This
644 is a non-standard option in MQTT v3.1. MQTT v3.1.1 and v5.0 allow
645 brokers to remove client sessions.
646
647 Badly designed clients may set clean session to false whilst using
648 a randomly generated client id. This leads to persistent clients
649 that connect once and never reconnect. This option allows these
650 clients to be removed. This option allows persistent clients (those
651 with clean session set to false) to be removed if they do not
652 reconnect within a certain time frame.
653
654 The expiration period should be an integer followed by one of h d w
655 m y for hour, day, week, month and year respectively. For example:
656
657 • persistent_client_expiration 2m
658
659 • persistent_client_expiration 14d
660
661 • persistent_client_expiration 1y
662
663 As this is a non-standard option, the default if not set is to
664 never expire persistent clients.
665
666 This option applies globally.
667
668 Reloaded on reload signal.
669
670 pid_file file path
671 Write a pid file to the file specified. If not given (the default),
672 no pid file will be written. If the pid file cannot be written,
673 mosquitto will exit.
674
675 If mosquitto is being automatically started by an init script it
676 will usually be required to write a pid file. This should then be
677 configured as e.g. /var/run/mosquitto/mosquitto.pid
678
679 Not reloaded on reload signal.
680
681 plugin_opt_* value
682 Options to be passed to the most recent plugin defined in the
683 configuration file. See the specific plugin instructions for
684 details of what options are available.
685
686 Applies to the current plugin being configured.
687
688 This is also available as the auth_opt_* option, but this use is
689 deprecated and will be removed in a future version.
690
691 plugin file path
692 Specify an external module to use for authentication and access
693 control. This allows custom username/password and access control
694 functions to be created.
695
696 Can be specified multiple times to load multiple plugins. The
697 plugins will be processed in the order that they are specified.
698
699 If password_file, or acl_file are used in the config file alongsize
700 plugin, the plugin checks will run after the built in checks.
701
702 Not currently reloaded on reload signal.
703
704 See also https://mosquitto.org/documentation/dynamic-security/
705
706 This is also available as the auth_plugin option, but this use is
707 deprecated and will be removed in a future version.
708
709 psk_file file path
710 Set the path to a pre-shared-key file. This option requires a
711 listener to be have PSK support enabled. If defined, the contents
712 of the file are used to control client access to the broker. Each
713 line should be in the format "identity:key", where the key is a
714 hexadecimal string with no leading "0x". A client connecting to a
715 listener that has PSK support enabled must provide a matching
716 identity and PSK to allow the encrypted connection to proceed.
717
718 If per_listener_settings is true, this option applies to the
719 current listener being configured only. If per_listener_settings is
720 false, this option applies to all listeners.
721
722 Reloaded on reload signal. The currently loaded identity and key
723 data will be freed and reloaded. Clients that are already connected
724 will not be affected.
725
726 queue_qos0_messages [ true | false ]
727 Set to true to queue messages with QoS 0 when a persistent client
728 is disconnected. When bridges topics are configured with QoS level
729 1 or 2 incoming QoS 0 messages for these topics are also queued.
730 These messages are included in the limit imposed by
731 max_queued_messages. Defaults to false.
732
733 Note that the MQTT v3.1.1 spec states that only QoS 1 and 2
734 messages should be saved in this situation so this is a
735 non-standard option.
736
737 This option applies globally.
738
739 Reloaded on reload signal.
740
741 retain_available [ true | false ]
742 If set to false, then retained messages are not supported. Clients
743 that send a message with the retain bit will be disconnected if
744 this option is set to false. Defaults to true.
745
746 This option applies globally.
747
748 Reloaded on reload signal.
749
750 set_tcp_nodelay [ true | false ]
751 If set to true, the TCP_NODELAY option will be set on client
752 sockets to disable Nagle's algorithm. This has the effect of
753 reducing latency of some messages at potentially increasing the
754 number of TCP packets being sent. Defaults to false.
755
756 This option applies globally.
757
758 Reloaded on reload signal.
759
760 sys_interval seconds
761 The integer number of seconds between updates of the $SYS
762 subscription hierarchy, which provides status information about the
763 broker. If unset, defaults to 10 seconds.
764
765 Set to 0 to disable publishing the $SYS hierarchy completely.
766
767 This option applies globally.
768
769 Reloaded on reload signal.
770
771 upgrade_outgoing_qos [ true | false ]
772 The MQTT specification requires that the QoS of a message delivered
773 to a subscriber is never upgraded to match the QoS of the
774 subscription. Enabling this option changes this behaviour. If
775 upgrade_outgoing_qos is set true, messages sent to a subscriber
776 will always match the QoS of its subscription. This is a
777 non-standard option not provided for by the spec. Defaults to
778 false.
779
780 This option applies globally.
781
782 Reloaded on reload signal.
783
784 user username
785 When run as root, change to this user and its primary group on
786 startup. If set to "mosquitto" or left unset, and if the
787 "mosquitto" user does not exist, then mosquitto will change to the
788 "nobody" user instead. If this is set to another value and
789 mosquitto is unable to change to this user and group, it will exit
790 with an error. The user specified must have read/write access to
791 the persistence database if it is to be written. If run as a
792 non-root user, this setting has no effect. Defaults to mosquitto.
793
794 This setting has no effect on Windows and so you should run
795 mosquitto as the user you wish it to run as.
796
797 Not reloaded on reload signal.
798
800 The network ports that mosquitto listens on can be controlled using
801 listeners. The default listener options can be overridden and further
802 listeners can be created.
803
804 General Options
805 bind_address address
806 This option is deprecated and will be removed in a future version.
807 Use the listener instead.
808
809 Listen for incoming network connections on the specified IP
810 address/hostname only. This is useful to restrict access to certain
811 network interfaces. To restrict access to mosquitto to the local
812 host only, use "bind_address localhost". This only applies to the
813 default listener. Use the listener option to control other
814 listeners.
815
816 It is recommended to use an explicit listener rather than rely on
817 the implicit default listener options like this.
818
819 Not reloaded on reload signal.
820
821 bind_interface device
822 Listen for incoming network connections only on the specified
823 interface. This is similar to the bind_address option but is useful
824 when an interface has multiple addresses or the address may change.
825
826 If used at the same time as the bind_address for the default
827 listener, or the bind address/host part of the listener, then
828 bind_interface will take priority.
829
830 This option is not available on Windows.
831
832 Not reloaded on reload signal.
833
834 http_dir directory
835 When a listener is using the websockets protocol, it is possible to
836 serve http data as well. Set http_dir to a directory which contains
837 the files you wish to serve. If this option is not specified, then
838 no normal http connections will be possible.
839
840 Not reloaded on reload signal.
841
842 listener port [bind address/host/unix socket path]
843 Listen for incoming network connection on the specified port. A
844 second optional argument allows the listener to be bound to a
845 specific ip address/hostname. If this variable is used and neither
846 the global bind_address nor port options are used then the default
847 listener will not be started.
848
849 The bind address/host option allows this listener to be bound to a
850 specific IP address by passing an IP address or hostname. For
851 websockets listeners, it is only possible to pass an IP address
852 here.
853
854 On systems that support Unix Domain Sockets, this option can also
855 be used to create a Unix socket rather than opening a TCP socket.
856 In this case, the port must be set to 0, and the unix socket path
857 must be given.
858
859 This option may be specified multiple times. See also the
860 mount_point option.
861
862 Not reloaded on reload signal.
863
864 max_connections count
865 Limit the total number of clients connected for the current
866 listener. Set to -1 to have "unlimited" connections. Note that
867 other limits may be imposed that are outside the control of
868 mosquitto. See e.g. limits.conf().
869
870 Not reloaded on reload signal.
871
872 max_qos value
873 Limit the QoS value allowed for clients connecting to this
874 listener. Defaults to 2, which means any QoS can be used. Set to 0
875 or 1 to limit to those QoS values. This makes use of an MQTT v5
876 feature to notify clients of the limitation. MQTT v3.1.1 clients
877 will not be aware of the limitation. Clients publishing to this
878 listener with a too-high QoS will be disconnected.
879
880 Not reloaded on reload signal.
881
882 max_topic_alias number
883 This option sets the maximum number topic aliases that an MQTT v5
884 client is allowed to create. This option applies per listener.
885 Defaults to 10. Set to 0 to disallow topic aliases. The maximum
886 value possible is 65535.
887
888 Not reloaded on reload signal.
889
890 mount_point topic prefix
891 This option is used with the listener option to isolate groups of
892 clients. When a client connects to a listener which uses this
893 option, the string argument is attached to the start of all topics
894 for this client. This prefix is removed when any messages are sent
895 to the client. This means a client connected to a listener with
896 mount point example can only see messages that are published in the
897 topic hierarchy example and below.
898
899 Not reloaded on reload signal.
900
901 port port number
902 This option is deprecated and will be removed in a future version.
903 Use the listener instead.
904
905 Set the network port for the default listener to listen on.
906 Defaults to 1883.
907
908 Not reloaded on reload signal.
909
910 It is recommended to use an explicit listener rather than rely on
911 the implicit default listener options like this.
912
913 protocol value
914 Set the protocol to accept for the current listener. Can be mqtt,
915 the default, or websockets if available.
916
917 Websockets support is currently disabled by default at compile
918 time. Certificate based TLS may be used with websockets, except
919 that only the cafile, certfile, keyfile, ciphers, and
920 ciphers_tls1.3 options are supported.
921
922 Not reloaded on reload signal.
923
924 socket_domain [ ipv4 | ipv6 ]
925 By default, a listener will attempt to listen on all supported IP
926 protocol versions. If you do not have an IPv4 or IPv6 interface you
927 may wish to disable support for either of those protocol versions.
928 In particular, note that due to the limitations of the websockets
929 library, it will only ever attempt to open IPv6 sockets if IPv6
930 support is compiled in, and so will fail if IPv6 is not available.
931
932 Set to ipv4 to force the listener to only use IPv4, or set to ipv6
933 to force the listener to only use IPv6. If you want support for
934 both IPv4 and IPv6, then do not use the socket_domain option.
935
936 Not reloaded on reload signal.
937
938 use_username_as_clientid [ true | false ]
939 Set use_username_as_clientid to true to replace the clientid that a
940 client connected with its username. This allows authentication to
941 be tied to the clientid, which means that it is possible to prevent
942 one client disconnecting another by using the same clientid.
943 Defaults to false.
944
945 If a client connects with no username it will be disconnected as
946 not authorised when this option is set to true. Do not use in
947 conjunction with clientid_prefixes.
948
949 This does not apply globally, but on a per-listener basis.
950
951 See also use_identity_as_username.
952
953 Not reloaded on reload signal.
954
955 websockets_log_level level
956 Change the websockets logging level. This is a global option, it is
957 not possible to set per listener. This is an integer that is
958 interpreted by libwebsockets as a bit mask for its lws_log_levels
959 enum. See the libwebsockets documentation for more details.
960
961 To use this option, log_type websockets must also be enabled.
962 Defaults to 0.
963
964 websockets_headers_size size
965 Change the websockets headers size. This is a global option, it is
966 not possible to set per listener. This option sets the size of the
967 buffer used in the libwebsockets library when reading HTTP headers.
968 If you are passing large header data such as cookies then you may
969 need to increase this value. If left unset, or set to 0, then the
970 default of 1024 bytes will be used.
971
972 Certificate based SSL/TLS Support
973 The following options are available for all listeners to configure
974 certificate based SSL support. See also "Pre-shared-key based SSL/TLS
975 support".
976
977 cafile file path
978 cafile is used to define the path to a file containing the PEM
979 encoded CA certificates that are trusted when checking incoming
980 client certificates.
981
982 capath directory path
983 capath is used to define a directory that contains PEM encoded CA
984 certificates that are trusted when checking incoming client
985 certificates. For capath to work correctly, the certificates files
986 must have ".pem" as the file ending and you must run "openssl
987 rehash <path to capath>" each time you add/remove a certificate.
988
989 certfile file path
990 Path to the PEM encoded server certificate. This option and keyfile
991 must be present to enable certificate based TLS encryption.
992
993 The certificate pointed to by this option will be reloaded when
994 Mosquitto receives a SIGHUP signal. This can be used to load new
995 certificates prior to the existing ones expiring.
996
997 ciphers cipher:list
998 The list of allowed ciphers for this listener, for TLS v1.2 and
999 earlier only, each separated with a colon. Available ciphers can be
1000 obtained using the "openssl ciphers" command.
1001
1002 ciphers_tls1.3 cipher:list
1003 The list of allowed ciphersuites for this listener, for TLS v1.3,
1004 each separated with a colon.
1005
1006 crlfile file path
1007 If you have require_certificate set to true, you can create a
1008 certificate revocation list file to revoke access to particular
1009 client certificates. If you have done this, use crlfile to point to
1010 the PEM encoded revocation file.
1011
1012 dhparamfile file path
1013 To allow the use of ephemeral DH key exchange, which provides
1014 forward security, the listener must load DH parameters. This can be
1015 specified with the dhparamfile option. The dhparamfile can be
1016 generated with the command e.g.
1017
1018 openssl dhparam -out dhparam.pem 2048
1019
1020 keyfile file path
1021 If tls_keyform equals "pem" this is the path to the PEM encoded
1022 server key. This option and certfile must be present to enable
1023 certificate based TLS encryption. If tls_keyform is "engine" this
1024 represents the engine handle of the private key.
1025
1026 The private key pointed to by this option will be reloaded when
1027 Mosquitto receives a SIGHUP signal. This can be used to load new
1028 keys prior to the existing ones expiring.
1029
1030 require_certificate [ true | false ]
1031 By default an SSL/TLS enabled listener will operate in a similar
1032 fashion to a https enabled web server, in that the server has a
1033 certificate signed by a CA and the client will verify that it is a
1034 trusted certificate. The overall aim is encryption of the network
1035 traffic. By setting require_certificate to true, a client
1036 connecting to this listener must provide a valid certificate in
1037 order for the network connection to proceed. This allows access to
1038 the broker to be controlled outside of the mechanisms provided by
1039 MQTT.
1040
1041 tls_engine engine
1042 A valid openssl engine id. These can be listed with openssl engine
1043 command.
1044
1045 tls_engine_kpass_sha1 engine_kpass_sha1
1046 SHA1 of the private key password when using an TLS engine. Some TLS
1047 engines such as the TPM engine may require the use of a password in
1048 order to be accessed. This option allows a hex encoded SHA1 hash of
1049 the password to the engine directly, instead of the user being
1050 prompted for the password.
1051
1052 tls_keyform [ pem | engine ]
1053 Specifies the type of private key in use when making TLS
1054 connections.. This can be "pem" or "engine". This parameter is
1055 useful when a TPM module is being used and the private key has been
1056 created with it. Defaults to "pem", which means normal private key
1057 files are used.
1058
1059 tls_version version
1060 Configure the minimum version of the TLS protocol to be used for
1061 this listener. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. If
1062 left unset, the default allows TLS v1.3 and v1.2.
1063
1064 In Mosquitto version 1.6.x and earlier, this option set the only
1065 TLS protocol version that was allowed, rather than the minimum.
1066
1067 use_identity_as_username [ true | false ]
1068 If require_certificate is true, you may set
1069 use_identity_as_username to true to use the CN value from the
1070 client certificate as a username. If this is true, the
1071 password_file option will not be used for this listener.
1072
1073 This takes priority over use_subject_as_username if both are set to
1074 true.
1075
1076 See also use_subject_as_username
1077
1078 use_subject_as_username [ true | false ]
1079 If require_certificate is true, you may set use_subject_as_username
1080 to true to use the complete subject value from the client
1081 certificate as a username. If this is true, the password_file
1082 option will not be used for this listener.
1083
1084 The subject will be generated in a form similar to CN=test
1085 client,OU=Production,O=Server,L=Nottingham,ST=Nottinghamshire,C=GB.
1086
1087 See also use_identity_as_username
1088
1089 Pre-shared-key based SSL/TLS Support
1090 The following options are available for all listeners to configure
1091 pre-shared-key based SSL support. See also "Certificate based SSL/TLS
1092 support".
1093
1094 ciphers cipher:list
1095 When using PSK, the encryption ciphers used will be chosen from the
1096 list of available PSK ciphers. If you want to control which ciphers
1097 are available, use this option. The list of available ciphers can
1098 be optained using the "openssl ciphers" command and should be
1099 provided in the same format as the output of that command.
1100
1101 psk_hint hint
1102 The psk_hint option enables pre-shared-key support for this
1103 listener and also acts as an identifier for this listener. The hint
1104 is sent to clients and may be used locally to aid authentication.
1105 The hint is a free form string that doesn't have much meaning in
1106 itself, so feel free to be creative.
1107
1108 If this option is provided, see psk_file to define the pre-shared
1109 keys to be used or create a security plugin to handle them.
1110
1111 tls_version version
1112 Configure the minimum version of the TLS protocol to be used for
1113 this listener. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. If
1114 left unset, the default of allowing TLS v1.3 and v1.2.
1115
1116 In Mosquitto version 1.6.x and earlier, this option set the only
1117 TLS protocol version that was allowed, rather than the minimum.
1118
1119 use_identity_as_username [ true | false ]
1120 Set use_identity_as_username to have the psk identity sent by the
1121 client used as its username. The username will be checked as
1122 normal, so password_file or another means of authentication
1123 checking must be used. No password will be used.
1124
1126 Multiple bridges (connections to other brokers) can be configured using
1127 the following variables.
1128
1129 Bridges cannot currently be reloaded on reload signal.
1130
1131 address address[:port] [address[:port]], addresses address[:port]
1132 [address[:port]]
1133 Specify the address and optionally the port of the bridge to
1134 connect to. This must be given for each bridge connection. If the
1135 port is not specified, the default of 1883 is used.
1136
1137 If you use an IPv6 address, then the port is not optional.
1138
1139 Multiple host addresses can be specified on the address config. See
1140 the round_robin option for more details on the behaviour of bridges
1141 with multiple addresses.
1142
1143 bridge_attempt_unsubscribe [ true | false ]
1144 If a bridge has topics that have "out" direction, the default
1145 behaviour is to send an unsubscribe request to the remote broker on
1146 that topic. This means that changing a topic direction from "in" to
1147 "out" will not keep receiving incoming messages. Sending these
1148 unsubscribe requests is not always desirable, setting
1149 bridge_attempt_unsubscribe to false will disable sending the
1150 unsubscribe request. Defaults to true.
1151
1152 bridge_bind_address ip address
1153 If you need to have the bridge connect over a particular network
1154 interface, use bridge_bind_address to tell the bridge which local
1155 IP address the socket should bind to, e.g. bridge_bind_address
1156 192.168.1.10.
1157
1158 bridge_max_packet_size value
1159 If you wish to restrict the size of messages sent to a remote
1160 bridge, use this option. This sets the maximum number of bytes for
1161 the total message, including headers and payload. Note that MQTT v5
1162 brokers may provide their own maximum-packet-size property. In this
1163 case, the smaller of the two limits will be used. Set to 0 for
1164 "unlimited".
1165
1166 bridge_outgoing_retain [ true | false ]
1167 Some MQTT brokers do not allow retained messages. MQTT v5 gives a
1168 mechanism for brokers to tell clients that they do not support
1169 retained messages, but this is not possible for MQTT v3.1.1 or
1170 v3.1. If you need to bridge to a v3.1.1 or v3.1 broker that does
1171 not support retained messages, set the bridge_outgoing_retain
1172 option to false. This will remove the retain bit on all outgoing
1173 messages to that bridge, regardless of any other setting. Defaults
1174 to true.
1175
1176 bridge_protocol_version version
1177 Set the version of the MQTT protocol to use with for this bridge.
1178 Can be one of mqttv50, mqttv311 or mqttv31. Defaults to mqttv311.
1179
1180 cleansession [ true | false ]
1181 Set the clean session option for this bridge. Setting to false (the
1182 default), means that all subscriptions on the remote broker are
1183 kept in case of the network connection dropping. If set to true,
1184 all subscriptions and messages on the remote broker will be cleaned
1185 up if the connection drops. Note that setting to true may cause a
1186 large amount of retained messages to be sent each time the bridge
1187 reconnects.
1188
1189 If you are using bridges with cleansession set to false (the
1190 default), then you may get unexpected behaviour from incoming
1191 topics if you change what topics you are subscribing to. This is
1192 because the remote broker keeps the subscription for the old topic.
1193 If you have this problem, connect your bridge with cleansession set
1194 to true, then reconnect with cleansession set to false as normal.
1195
1196 local_cleansession [ true | false]
1197 The regular cleansession covers both the local subscriptions and
1198 the remote subscriptions. local_cleansession allows splitting this.
1199 Setting false will mean that the local connection will preserve
1200 subscription, independent of the remote connection.
1201
1202 Defaults to the value of bridge.cleansession unless explicitly
1203 specified.
1204
1205 connection name
1206 This variable marks the start of a new bridge connection. It is
1207 also used to give the bridge a name which is used as the client id
1208 on the remote broker.
1209
1210 keepalive_interval seconds
1211 Set the number of seconds after which the bridge should send a ping
1212 if no other traffic has occurred. Defaults to 60. A minimum value
1213 of 5 seconds is allowed.
1214
1215 idle_timeout seconds
1216 Set the amount of time a bridge using the lazy start type must be
1217 idle before it will be stopped. Defaults to 60 seconds.
1218
1219 local_clientid id
1220 Set the clientid to use on the local broker. If not defined, this
1221 defaults to local.<remote_clientid>. If you are bridging a broker
1222 to itself, it is important that local_clientid and remote_clientid
1223 do not match.
1224
1225 local_password password
1226 Configure the password to be used when connecting this bridge to
1227 the local broker. This may be important when authentication and
1228 ACLs are being used.
1229
1230 local_username username
1231 Configure the username to be used when connecting this bridge to
1232 the local broker. This may be important when authentication and
1233 ACLs are being used.
1234
1235 notifications [ true | false ]
1236 If set to true, publish notification messages to the local and
1237 remote brokers giving information about the state of the bridge
1238 connection. Retained messages are published to the topic
1239 $SYS/broker/connection/<remote_clientid>/state unless otherwise set
1240 with notification_topics. If the message is 1 then the connection
1241 is active, or 0 if the connection has failed. Defaults to true.
1242
1243 This uses the Last Will and Testament (LWT) feature.
1244
1245 notifications_local_only [ true | false ]
1246 If set to true, only publish notification messages to the local
1247 broker giving information about the state of the bridge connection.
1248 Defaults to false.
1249
1250 notification_topic topic
1251 Choose the topic on which notifications will be published for this
1252 bridge. If not set the messages will be sent on the topic
1253 $SYS/broker/connection/<remote_clientid>/state.
1254
1255 remote_clientid id
1256 Set the client id for this bridge connection. If not defined, this
1257 defaults to 'name.hostname', where name is the connection name and
1258 hostname is the hostname of this computer.
1259
1260 This replaces the old "clientid" option to avoid confusion with
1261 local/remote sides of the bridge. "clientid" remains valid for the
1262 time being.
1263
1264 remote_password value
1265 Configure a password for the bridge. This is used for
1266 authentication purposes when connecting to a broker that supports
1267 MQTT v3.1 and up and requires a username and/or password to
1268 connect. This option is only valid if a remote_username is also
1269 supplied.
1270
1271 This replaces the old "password" option to avoid confusion with
1272 local/remote sides of the bridge. "password" remains valid for the
1273 time being.
1274
1275 remote_username name
1276 Configure a username for the bridge. This is used for
1277 authentication purposes when connecting to a broker that supports
1278 MQTT v3.1 and up and requires a username and/or password to
1279 connect. See also the remote_password option.
1280
1281 This replaces the old "username" option to avoid confusion with
1282 local/remote sides of the bridge. "username" remains valid for the
1283 time being.
1284
1285 restart_timeout base cap, restart_timeout constant
1286 Set the amount of time a bridge using the automatic start type will
1287 wait until attempting to reconnect.
1288
1289 This option can be configured to use a constant delay time in
1290 seconds, or to use a backoff mechanism based on "Decorrelated
1291 Jitter", which adds a degree of randomness to when the restart
1292 occurs, starting at the base and increasing up to the cap. Set a
1293 constant timeout of 20 seconds:
1294
1295 restart_timeout 20
1296
1297 Set backoff with a base (start value) of 10 seconds and a cap
1298 (upper limit) of 60 seconds:
1299
1300 restart_timeout 10 30
1301
1302 Defaults to jitter with a base of 5 seconds and cap of 30 seconds.
1303
1304 round_robin [ true | false ]
1305 If the bridge has more than one address given in the
1306 address/addresses configuration, the round_robin option defines the
1307 behaviour of the bridge on a failure of the bridge connection. If
1308 round_robin is false, the default value, then the first address is
1309 treated as the main bridge connection. If the connection fails, the
1310 other secondary addresses will be attempted in turn. Whilst
1311 connected to a secondary bridge, the bridge will periodically
1312 attempt to reconnect to the main bridge until successful.
1313
1314 If round_robin is true, then all addresses are treated as equals.
1315 If a connection fails, the next address will be tried and if
1316 successful will remain connected until it fails.
1317
1318 start_type [ automatic | lazy | once ]
1319 Set the start type of the bridge. This controls how the bridge
1320 starts and can be one of three types: automatic, lazy and once.
1321 Note that RSMB provides a fourth start type "manual" which isn't
1322 currently supported by mosquitto.
1323
1324 automatic is the default start type and means that the bridge
1325 connection will be started automatically when the broker starts and
1326 also restarted after a short delay (30 seconds) if the connection
1327 fails.
1328
1329 Bridges using the lazy start type will be started automatically
1330 when the number of queued messages exceeds the number set with the
1331 threshold option. It will be stopped automatically after the time
1332 set by the idle_timeout parameter. Use this start type if you wish
1333 the connection to only be active when it is needed.
1334
1335 A bridge using the once start type will be started automatically
1336 when the broker starts but will not be restarted if the connection
1337 fails.
1338
1339 threshold count
1340 Set the number of messages that need to be queued for a bridge with
1341 lazy start type to be restarted. Defaults to 10 messages.
1342
1343 topic pattern [[[ out | in | both ] qos-level] local-prefix
1344 remote-prefix]
1345 Define a topic pattern to be shared between the two brokers. Any
1346 topics matching the pattern (which may include wildcards) are
1347 shared. The second parameter defines the direction that the
1348 messages will be shared in, so it is possible to import messages
1349 from a remote broker using in, export messages to a remote broker
1350 using out or share messages in both directions. If this parameter
1351 is not defined, the default of out is used. The QoS level defines
1352 the publish/subscribe QoS level used for this topic and defaults to
1353 0.
1354
1355 The local-prefix and remote-prefix options allow topics to be
1356 remapped when publishing to and receiving from remote brokers. This
1357 allows a topic tree from the local broker to be inserted into the
1358 topic tree of the remote broker at an appropriate place.
1359
1360 For incoming topics, the bridge will prepend the pattern with the
1361 remote prefix and subscribe to the resulting topic on the remote
1362 broker. When a matching incoming message is received, the remote
1363 prefix will be removed from the topic and then the local prefix
1364 added.
1365
1366 For outgoing topics, the bridge will prepend the pattern with the
1367 local prefix and subscribe to the resulting topic on the local
1368 broker. When an outgoing message is processed, the local prefix
1369 will be removed from the topic then the remote prefix added.
1370
1371 When using topic mapping, an empty prefix can be defined using the
1372 place marker "". Using the empty marker for the topic itself is
1373 also valid. The table below defines what combination of empty or
1374 value is valid. The Full Local Topic and Full Remote Topic show the
1375 resulting topics that would be used on the local and remote ends of
1376 the bridge. For example, for the first table row if you publish to
1377 L/topic on the local broker, then the remote broker will receive a
1378 message on the topic R/topic.
1379
1380 ┌────────┬────────┬────────┬─────────────┬────────────┬─────────────┐
1381 │Pattern │ Local │ Remote │ Validity │ Full Local │ Full Remote │
1382 │ │ Prefix │ Prefix │ │ Topic │ Topic │
1383 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1384 │pattern │ L/ │ R/ │ valid │ L/pattern │ R/pattern │
1385 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1386 │pattern │ L/ │ "" │ valid │ L/pattern │ pattern │
1387 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1388 │pattern │ "" │ R/ │ valid │ pattern │ R/pattern │
1389 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1390 │pattern │ "" │ "" │ valid (no │ pattern │ pattern │
1391 │ │ │ │ remapping) │ │ │
1392 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1393 │"" │ local │ remote │ valid │ local │ remote │
1394 │ │ │ │ (remap │ │ │
1395 │ │ │ │ single │ │ │
1396 │ │ │ │ local topic │ │ │
1397 │ │ │ │ to remote) │ │ │
1398 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1399 │"" │ local │ "" │ invalid │ │ │
1400 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1401 │"" │ "" │ remote │ invalid │ │ │
1402 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1403 │"" │ "" │ "" │ invalid │ │ │
1404 └────────┴────────┴────────┴─────────────┴────────────┴─────────────┘
1405 To remap an entire topic tree, use e.g.:
1406
1407 topic # both 2 local/topic/ remote/topic/
1408
1409 This option can be specified multiple times per bridge.
1410
1411 Care must be taken to ensure that loops are not created with this
1412 option. If you are experiencing high CPU load from a broker, it is
1413 possible that you have a loop where each broker is forever
1414 forwarding each other the same messages.
1415
1416 See also the cleansession option if you have messages arriving on
1417 unexpected topics when using incoming topics.
1418
1419 Example Bridge Topic Remapping. The configuration below connects a
1420 bridge to the broker at test.mosquitto.org. It subscribes to the
1421 remote topic $SYS/broker/clients/total and republishes the messages
1422 received to the local topic test/mosquitto/org/clients/total
1423
1424 connection test-mosquitto-org
1425 address test.mosquitto.org
1426 cleansession true
1427 topic clients/total in 0 test/mosquitto/org/ $SYS/broker/
1428
1429 try_private [ true | false ]
1430 If try_private is set to true, the bridge will attempt to indicate
1431 to the remote broker that it is a bridge not an ordinary client. If
1432 successful, this means that loop detection will be more effective
1433 and that retained messages will be propagated correctly. Not all
1434 brokers support this feature so it may be necessary to set
1435 try_private to false if your bridge does not connect properly.
1436
1437 Defaults to true.
1438
1439 SSL/TLS Support
1440 The following options are available for all bridges to configure
1441 SSL/TLS support.
1442
1443 bridge_alpn alpn
1444 Configure the application layer protocol negotiation option for the
1445 TLS session. Useful for brokers that support both websockets and
1446 MQTT on the same port.
1447
1448 bridge_cafile file path
1449 One of bridge_cafile or bridge_capath must be provided to allow
1450 SSL/TLS support.
1451
1452 bridge_cafile is used to define the path to a file containing the
1453 PEM encoded CA certificates that have signed the certificate for
1454 the remote broker.
1455
1456 bridge_capath file path
1457 One of bridge_capath or bridge_cafile must be provided to allow
1458 SSL/TLS support.
1459
1460 bridge_capath is used to define the path to a directory containing
1461 the PEM encoded CA certificates that have signed the certificate
1462 for the remote broker. For bridge_capath to work correctly, the
1463 certificate files must have ".crt" as the file ending and you must
1464 run "openssl rehash <path to bridge_capath>" each time you
1465 add/remove a certificate.
1466
1467 bridge_certfile file path
1468 Path to the PEM encoded client certificate for this bridge, if
1469 required by the remote broker.
1470
1471 bridge_identity identity
1472 Pre-shared-key encryption provides an alternative to certificate
1473 based encryption. A bridge can be configured to use PSK with the
1474 bridge_identity and bridge_psk options. This is the client identity
1475 used with PSK encryption. Only one of certificate and PSK based
1476 encryption can be used on one bridge at once.
1477
1478 bridge_insecure [ true | false ]
1479 When using certificate based TLS, the bridge will attempt to verify
1480 the hostname provided in the remote certificate matches the
1481 host/address being connected to. This may cause problems in testing
1482 scenarios, so bridge_insecure may be set to true to disable the
1483 hostname verification.
1484
1485 Setting this option to true means that a malicious third party
1486 could potentially impersonate your server, so it should always be
1487 set to false in production environments.
1488
1489 bridge_keyfile file path
1490 Path to the PEM encoded private key for this bridge, if required by
1491 the remote broker.
1492
1493 bridge_psk key
1494 Pre-shared-key encryption provides an alternative to certificate
1495 based encryption. A bridge can be configured to use PSK with the
1496 bridge_identity and bridge_psk options. This is the pre-shared-key
1497 in hexadecimal format with no "0x". Only one of certificate and PSK
1498 based encryption can be used on one bridge at once.
1499
1500 bridge_require_ocsp [ true | false ]
1501 When set to true, the bridge requires OCSP on the TLS connection it
1502 opens as client.
1503
1504 bridge_tls_version version
1505 Configure the version of the TLS protocol to be used for this
1506 bridge. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. Defaults
1507 to tlsv1.2. The remote broker must support the same version of TLS
1508 for the connection to succeed.
1509
1511 mosquitto.conf
1512
1514 mosquitto bug information can be found at
1515 https://github.com/eclipse/mosquitto/issues
1516
1518 mosquitto(8), mosquitto_passwd(1), mosquitto-tls(7), mqtt(7),
1519 limits.conf(5)
1520
1522 Roger Light <roger@atchoo.org>
1523
1524
1525
1526Mosquitto Project 09/18/2023 MOSQUITTO.CONF(5)