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