1MOSQUITTO.CONF(5) File formats and conventions MOSQUITTO.CONF(5)
2
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 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 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 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 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 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 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 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 Both certificate and PSK based encryption are configured on a
83 per-listener basis.
84 Authentication plugins can be created to augment the password_file,
86 acl_file and psk_file options with e.g. SQL based lookups.
87 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 If this parameter is defined then only the topics listed will have
100 access. Topic access is added with lines of the format:
101 topic [read|write|readwrite|deny] <topic>
103 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 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 user <username>
118 The username referred to here is the same as in password_file. It
120 is not the clientid.
121 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 pattern [read|write|readwrite|deny] <topic>
127 The patterns available for substition are:
129 • %c to match the client id of the client
131 • %u to match the username of the client
133 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 Example:
139 pattern write sensor/%u/data
141 Allow access for bridge connection messages:
143 pattern write $SYS/broker/connection/%c/state
145 If the first character of a line of the ACL file is a # it is
147 treated as a comment.
148 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 Reloaded on reload signal. The currently loaded ACLs will be freed
154 and reloaded. Existing subscriptions will be affected after the
155 reload.
156 See also https://mosquitto.org/documentation/dynamic-security/
158 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 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 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 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 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 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 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 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 Defaults to true.
200 This option applies globally.
202 Reloaded on reload signal.
204 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 See also the auto_id_prefix option.
211 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 Reloaded on reload signal.
217 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 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 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 Defaults to true.
237 Applies to the current authentication plugin being configured.
239 Not currently reloaded on reload signal.
241 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 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 Reloaded on reload signal.
252 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 This option applies globally.
261 Reloaded on reload signal.
263 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 This option applies globally.
272 Reloaded on reload signal.
274 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 This option applies globally, regardless of the
286 per_listener_settings option.
287 clientid_prefixes prefix
289 This option is deprecated and will be removed in a future version.
290 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 This option applies globally.
298 Reloaded on reload signal. Note that currently connected clients
300 will be unaffected by any changes.
301 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 This option applies globally.
307 Reloaded on reload signal.
309 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 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 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 00.conf
328 01.conf
329 A.conf
330 a.conf
331 B.conf
332 b.conf
333 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 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 include_dir one.d
343 include_dir two.d
344 Then the config files would be loaded in this order:
346 # files from one.d
348 B.conf
349 C.conf
350 # files from two.d
351 A.conf
352 D.conf
353 log_dest destinations
355 Send log messages to a particular destination. Possible
356 destinations are: stdout stderr syslog topic file dlt.
357 stdout and stderr log to the console on the named output.
359 syslog uses the userspace syslog facility which usually ends up in
361 /var/log/messages or similar.
362 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 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 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 Use "log_dest none" if you wish to disable logging. Defaults to
381 stderr. This option may be specified multiple times.
382 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 Reloaded on reload signal.
388 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 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 Reloaded on reload signal.
401 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 log_timestamp_format %Y-%m-%dT%H:%M:%S
409 Reloaded on reload signal.
412 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 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 Reloaded on reload signal.
424 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 See also the max_inflight_messages option.
434 This option applies globally.
436 Reloaded on reload signal.
438 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 This option applies globally.
447 Reloaded on reload signal.
449 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 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 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 This option applies globally.
474 Reloaded on reload signal.
476 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 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 Setting below 20 bytes is forbidden because it is likely to
494 interfere with normal client operation even with small payloads.
495 This option applies globally.
497 Reloaded on reload signal.
499 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 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 This option applies globally.
513 Reloaded on reload signal.
515 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 This option applies globally.
523 Reloaded on reload signal.
525 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 This option is only available if memory tracking support is
538 compiled in.
539 Reloaded on reload signal. Setting to a lower value and reloading
541 will not result in memory being freed.
542 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 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 This option applies globally.
557 Reloaded on reload signal.
559 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 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 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 See also mosquitto_passwd(1) and
582 https://mosquitto.org/documentation/dynamic-security/
583 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 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 The default behaviour is for this to be set to false, which
598 maintains the settings behaviour from previous versions of
599 mosquitto.
600 Reloaded on reload signal.
602 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 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 This option applies globally.
621 Reloaded on reload signal.
623 persistence_file file name
625 The filename to use for the persistent database. Defaults to
626 mosquitto.db.
627 This option applies globally.
629 Reloaded on reload signal.
631 persistence_location path
633 The path where the persistence database should be stored. If not
634 given, then the current directory is used.
635 This option applies globally.
637 Reloaded on reload signal.
639 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 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 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 • persistent_client_expiration 2m
658 • persistent_client_expiration 14d
660 • persistent_client_expiration 1y
662 As this is a non-standard option, the default if not set is to
664 never expire persistent clients.
665 This option applies globally.
667 Reloaded on reload signal.
669 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 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 Not reloaded on reload signal.
680 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 Applies to the current plugin being configured.
687 This is also available as the auth_opt_* option, but this use is
689 deprecated and will be removed in a future version.
690 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 Can be specified multiple times to load multiple plugins. The
697 plugins will be processed in the order that they are specified.
698 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 Not currently reloaded on reload signal.
703 See also https://mosquitto.org/documentation/dynamic-security/
705 This is also available as the auth_plugin option, but this use is
707 deprecated and will be removed in a future version.
708 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 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 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 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 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 This option applies globally.
738 Reloaded on reload signal.
740 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 This option applies globally.
747 Reloaded on reload signal.
749 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 This option applies globally.
757 Reloaded on reload signal.
759 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 Set to 0 to disable publishing the $SYS hierarchy completely.
766 This option applies globally.
768 Reloaded on reload signal.
770 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 This option applies globally.
781 Reloaded on reload signal.
783 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 This setting has no effect on Windows and so you should run
795 mosquitto as the user you wish it to run as.
796 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 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 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 It is recommended to use an explicit listener rather than rely on
817 the implicit default listener options like this.
818 Not reloaded on reload signal.
820 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 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 This option is not available on Windows.
831 Not reloaded on reload signal.
833 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 Not reloaded on reload signal.
841 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 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 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 This option may be specified multiple times. See also the
860 mount_point option.
861 Not reloaded on reload signal.
863 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 Not reloaded on reload signal.
871 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 Not reloaded on reload signal.
881 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 Not reloaded on reload signal.
889 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 Not reloaded on reload signal.
900 port port number
902 This option is deprecated and will be removed in a future version.
903 Use the listener instead.
904 Set the network port for the default listener to listen on.
906 Defaults to 1883.
907 Not reloaded on reload signal.
909 It is recommended to use an explicit listener rather than rely on
911 the implicit default listener options like this.
912 protocol value
914 Set the protocol to accept for the current listener. Can be mqtt,
915 the default, or websockets if available.
916 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 Not reloaded on reload signal.
923 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 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 Not reloaded on reload signal.
937 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 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 This does not apply globally, but on a per-listener basis.
950 See also use_identity_as_username.
952 Not reloaded on reload signal.
954 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 To use this option, log_type websockets must also be enabled.
962 Defaults to 0.
963 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 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 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 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 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 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 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 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 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 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 openssl dhparam -out dhparam.pem 2048
1019 keyfile file path
1021 Path to the PEM encoded server key. This option and certfile must
1022 be present to enable certificate based TLS encryption.
1023 The private key pointed to by this option will be reloaded when
1025 Mosquitto receives a SIGHUP signal. This can be used to load new
1026 keys prior to the existing ones expiring.
1027 require_certificate [ true | false ]
1029 By default an SSL/TLS enabled listener will operate in a similar
1030 fashion to a https enabled web server, in that the server has a
1031 certificate signed by a CA and the client will verify that it is a
1032 trusted certificate. The overall aim is encryption of the network
1033 traffic. By setting require_certificate to true, a client
1034 connecting to this listener must provide a valid certificate in
1035 order for the network connection to proceed. This allows access to
1036 the broker to be controlled outside of the mechanisms provided by
1037 MQTT.
1038 tls_engine engine
1040 A valid openssl engine id. These can be listed with openssl engine
1041 command.
1042 tls_engine_kpass_sha1 engine_kpass_sha1
1044 SHA1 of the private key password when using an TLS engine. Some TLS
1045 engines such as the TPM engine may require the use of a password in
1046 order to be accessed. This option allows a hex encoded SHA1 hash of
1047 the password to the engine directly, instead of the user being
1048 prompted for the password.
1049 tls_keyform [ pem | engine ]
1051 Specifies the type of private key in use when making TLS
1052 connections.. This can be "pem" or "engine". This parameter is
1053 useful when a TPM module is being used and the private key has been
1054 created with it. Defaults to "pem", which means normal private key
1055 files are used.
1056 tls_version version
1058 Configure the minimum version of the TLS protocol to be used for
1059 this listener. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. If
1060 left unset, the default of allowing TLS v1.3 and v1.2.
1061 In Mosquitto version 1.6.x and earlier, this option set the only
1063 TLS protocol version that was allowed, rather than the minimum.
1064 use_identity_as_username [ true | false ]
1066 If require_certificate is true, you may set
1067 use_identity_as_username to true to use the CN value from the
1068 client certificate as a username. If this is true, the
1069 password_file option will not be used for this listener.
1070 This takes priority over use_subject_as_username if both are set to
1072 true.
1073 See also use_subject_as_username
1075 use_subject_as_username [ true | false ]
1077 If require_certificate is true, you may set use_subject_as_username
1078 to true to use the complete subject value from the client
1079 certificate as a username. If this is true, the password_file
1080 option will not be used for this listener.
1081 The subject will be generated in a form similar to CN=test
1083 client,OU=Production,O=Server,L=Nottingham,ST=Nottinghamshire,C=GB.
1084 See also use_identity_as_username
1086 Pre-shared-key based SSL/TLS Support
1088 The following options are available for all listeners to configure
1089 pre-shared-key based SSL support. See also "Certificate based SSL/TLS
1090 support".
1091 ciphers cipher:list
1093 When using PSK, the encryption ciphers used will be chosen from the
1094 list of available PSK ciphers. If you want to control which ciphers
1095 are available, use this option. The list of available ciphers can
1096 be optained using the "openssl ciphers" command and should be
1097 provided in the same format as the output of that command.
1098 psk_hint hint
1100 The psk_hint option enables pre-shared-key support for this
1101 listener and also acts as an identifier for this listener. The hint
1102 is sent to clients and may be used locally to aid authentication.
1103 The hint is a free form string that doesn't have much meaning in
1104 itself, so feel free to be creative.
1105 If this option is provided, see psk_file to define the pre-shared
1107 keys to be used or create a security plugin to handle them.
1108 tls_version version
1110 Configure the minimum version of the TLS protocol to be used for
1111 this listener. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. If
1112 left unset, the default of allowing TLS v1.3 and v1.2.
1113 In Mosquitto version 1.6.x and earlier, this option set the only
1115 TLS protocol version that was allowed, rather than the minimum.
1116 use_identity_as_username [ true | false ]
1118 Set use_identity_as_username to have the psk identity sent by the
1119 client used as its username. The username will be checked as
1120 normal, so password_file or another means of authentication
1121 checking must be used. No password will be used.
1122
1124 Multiple bridges (connections to other brokers) can be configured using
1125 the following variables.
1126 Bridges cannot currently be reloaded on reload signal.
1128 address address[:port] [address[:port]], addresses address[:port]
1130 [address[:port]]
1131 Specify the address and optionally the port of the bridge to
1132 connect to. This must be given for each bridge connection. If the
1133 port is not specified, the default of 1883 is used.
1134 If you use an IPv6 address, then the port is not optional.
1136 Multiple host addresses can be specified on the address config. See
1138 the round_robin option for more details on the behaviour of bridges
1139 with multiple addresses.
1140 bridge_attempt_unsubscribe [ true | false ]
1142 If a bridge has topics that have "out" direction, the default
1143 behaviour is to send an unsubscribe request to the remote broker on
1144 that topic. This means that changing a topic direction from "in" to
1145 "out" will not keep receiving incoming messages. Sending these
1146 unsubscribe requests is not always desirable, setting
1147 bridge_attempt_unsubscribe to false will disable sending the
1148 unsubscribe request. Defaults to true.
1149 bridge_bind_address ip address
1151 If you need to have the bridge connect over a particular network
1152 interface, use bridge_bind_address to tell the bridge which local
1153 IP address the socket should bind to, e.g. bridge_bind_address
1154 192.168.1.10.
1155 bridge_max_packet_size value
1157 If you wish to restrict the size of messages sent to a remote
1158 bridge, use this option. This sets the maximum number of bytes for
1159 the total message, including headers and payload. Note that MQTT v5
1160 brokers may provide their own maximum-packet-size property. In this
1161 case, the smaller of the two limits will be used. Set to 0 for
1162 "unlimited".
1163 bridge_outgoing_retain [ true | false ]
1165 Some MQTT brokers do not allow retained messages. MQTT v5 gives a
1166 mechanism for brokers to tell clients that they do not support
1167 retained messages, but this is not possible for MQTT v3.1.1 or
1168 v3.1. If you need to bridge to a v3.1.1 or v3.1 broker that does
1169 not support retained messages, set the bridge_outgoing_retain
1170 option to false. This will remove the retain bit on all outgoing
1171 messages to that bridge, regardless of any other setting. Defaults
1172 to true.
1173 bridge_protocol_version version
1175 Set the version of the MQTT protocol to use with for this bridge.
1176 Can be one of mqttv50, mqttv311 or mqttv31. Defaults to mqttv311.
1177 cleansession [ true | false ]
1179 Set the clean session option for this bridge. Setting to false (the
1180 default), means that all subscriptions on the remote broker are
1181 kept in case of the network connection dropping. If set to true,
1182 all subscriptions and messages on the remote broker will be cleaned
1183 up if the connection drops. Note that setting to true may cause a
1184 large amount of retained messages to be sent each time the bridge
1185 reconnects.
1186 If you are using bridges with cleansession set to false (the
1188 default), then you may get unexpected behaviour from incoming
1189 topics if you change what topics you are subscribing to. This is
1190 because the remote broker keeps the subscription for the old topic.
1191 If you have this problem, connect your bridge with cleansession set
1192 to true, then reconnect with cleansession set to false as normal.
1193 local_cleansession [ true | false]
1195 The regular cleansession covers both the local subscriptions and
1196 the remote subscriptions. local_cleansession allows splitting this.
1197 Setting false will mean that the local connection will preserve
1198 subscription, independent of the remote connection.
1199 Defaults to the value of bridge.cleansession unless explicitly
1201 specified.
1202 connection name
1204 This variable marks the start of a new bridge connection. It is
1205 also used to give the bridge a name which is used as the client id
1206 on the remote broker.
1207 keepalive_interval seconds
1209 Set the number of seconds after which the bridge should send a ping
1210 if no other traffic has occurred. Defaults to 60. A minimum value
1211 of 5 seconds is allowed.
1212 idle_timeout seconds
1214 Set the amount of time a bridge using the lazy start type must be
1215 idle before it will be stopped. Defaults to 60 seconds.
1216 local_clientid id
1218 Set the clientid to use on the local broker. If not defined, this
1219 defaults to local.<remote_clientid>. If you are bridging a broker
1220 to itself, it is important that local_clientid and remote_clientid
1221 do not match.
1222 local_password password
1224 Configure the password to be used when connecting this bridge to
1225 the local broker. This may be important when authentication and
1226 ACLs are being used.
1227 local_username username
1229 Configure the username to be used when connecting this bridge to
1230 the local broker. This may be important when authentication and
1231 ACLs are being used.
1232 notifications [ true | false ]
1234 If set to true, publish notification messages to the local and
1235 remote brokers giving information about the state of the bridge
1236 connection. Retained messages are published to the topic
1237 $SYS/broker/connection/<remote_clientid>/state unless otherwise set
1238 with notification_topics. If the message is 1 then the connection
1239 is active, or 0 if the connection has failed. Defaults to true.
1240 This uses the Last Will and Testament (LWT) feature.
1242 notifications_local_only [ true | false ]
1244 If set to true, only publish notification messages to the local
1245 broker giving information about the state of the bridge connection.
1246 Defaults to false.
1247 notification_topic topic
1249 Choose the topic on which notifications will be published for this
1250 bridge. If not set the messages will be sent on the topic
1251 $SYS/broker/connection/<remote_clientid>/state.
1252 remote_clientid id
1254 Set the client id for this bridge connection. If not defined, this
1255 defaults to 'name.hostname', where name is the connection name and
1256 hostname is the hostname of this computer.
1257 This replaces the old "clientid" option to avoid confusion with
1259 local/remote sides of the bridge. "clientid" remains valid for the
1260 time being.
1261 remote_password value
1263 Configure a password for the bridge. This is used for
1264 authentication purposes when connecting to a broker that supports
1265 MQTT v3.1 and up and requires a username and/or password to
1266 connect. This option is only valid if a remote_username is also
1267 supplied.
1268 This replaces the old "password" option to avoid confusion with
1270 local/remote sides of the bridge. "password" remains valid for the
1271 time being.
1272 remote_username name
1274 Configure a username for the bridge. This is used for
1275 authentication purposes when connecting to a broker that supports
1276 MQTT v3.1 and up and requires a username and/or password to
1277 connect. See also the remote_password option.
1278 This replaces the old "username" option to avoid confusion with
1280 local/remote sides of the bridge. "username" remains valid for the
1281 time being.
1282 restart_timeout base cap, restart_timeout constant
1284 Set the amount of time a bridge using the automatic start type will
1285 wait until attempting to reconnect.
1286 This option can be configured to use a constant delay time in
1288 seconds, or to use a backoff mechanism based on "Decorrelated
1289 Jitter", which adds a degree of randomness to when the restart
1290 occurs, starting at the base and increasing up to the cap. Set a
1291 constant timeout of 20 seconds:
1292 restart_timeout 20
1294 Set backoff with a base (start value) of 10 seconds and a cap
1296 (upper limit) of 60 seconds:
1297 restart_timeout 10 30
1299 Defaults to jitter with a base of 5 seconds and cap of 30 seconds.
1301 round_robin [ true | false ]
1303 If the bridge has more than one address given in the
1304 address/addresses configuration, the round_robin option defines the
1305 behaviour of the bridge on a failure of the bridge connection. If
1306 round_robin is false, the default value, then the first address is
1307 treated as the main bridge connection. If the connection fails, the
1308 other secondary addresses will be attempted in turn. Whilst
1309 connected to a secondary bridge, the bridge will periodically
1310 attempt to reconnect to the main bridge until successful.
1311 If round_robin is true, then all addresses are treated as equals.
1313 If a connection fails, the next address will be tried and if
1314 successful will remain connected until it fails.
1315 start_type [ automatic | lazy | once ]
1317 Set the start type of the bridge. This controls how the bridge
1318 starts and can be one of three types: automatic, lazy and once.
1319 Note that RSMB provides a fourth start type "manual" which isn't
1320 currently supported by mosquitto.
1321 automatic is the default start type and means that the bridge
1323 connection will be started automatically when the broker starts and
1324 also restarted after a short delay (30 seconds) if the connection
1325 fails.
1326 Bridges using the lazy start type will be started automatically
1328 when the number of queued messages exceeds the number set with the
1329 threshold option. It will be stopped automatically after the time
1330 set by the idle_timeout parameter. Use this start type if you wish
1331 the connection to only be active when it is needed.
1332 A bridge using the once start type will be started automatically
1334 when the broker starts but will not be restarted if the connection
1335 fails.
1336 threshold count
1338 Set the number of messages that need to be queued for a bridge with
1339 lazy start type to be restarted. Defaults to 10 messages.
1340 topic pattern [[[ out | in | both ] qos-level] local-prefix
1342 remote-prefix]
1343 Define a topic pattern to be shared between the two brokers. Any
1344 topics matching the pattern (which may include wildcards) are
1345 shared. The second parameter defines the direction that the
1346 messages will be shared in, so it is possible to import messages
1347 from a remote broker using in, export messages to a remote broker
1348 using out or share messages in both directions. If this parameter
1349 is not defined, the default of out is used. The QoS level defines
1350 the publish/subscribe QoS level used for this topic and defaults to
1351 0.
1352 The local-prefix and remote-prefix options allow topics to be
1354 remapped when publishing to and receiving from remote brokers. This
1355 allows a topic tree from the local broker to be inserted into the
1356 topic tree of the remote broker at an appropriate place.
1357 For incoming topics, the bridge will prepend the pattern with the
1359 remote prefix and subscribe to the resulting topic on the remote
1360 broker. When a matching incoming message is received, the remote
1361 prefix will be removed from the topic and then the local prefix
1362 added.
1363 For outgoing topics, the bridge will prepend the pattern with the
1365 local prefix and subscribe to the resulting topic on the local
1366 broker. When an outgoing message is processed, the local prefix
1367 will be removed from the topic then the remote prefix added.
1368 When using topic mapping, an empty prefix can be defined using the
1370 place marker "". Using the empty marker for the topic itself is
1371 also valid. The table below defines what combination of empty or
1372 value is valid. The Full Local Topic and Full Remote Topic show the
1373 resulting topics that would be used on the local and remote ends of
1374 the bridge. For example, for the first table row if you publish to
1375 L/topic on the local broker, then the remote broker will receive a
1376 message on the topic R/topic.
1377 ┌────────┬────────┬────────┬─────────────┬────────────┬─────────────┐
1379 │Pattern │ Local │ Remote │ Validity │ Full Local │ Full Remote │
1380 │ │ Prefix │ Prefix │ │ Topic │ Topic │
1381 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1382 │pattern │ L/ │ R/ │ valid │ L/pattern │ R/pattern │
1383 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1384 │pattern │ L/ │ "" │ valid │ L/pattern │ pattern │
1385 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1386 │pattern │ "" │ R/ │ valid │ pattern │ R/pattern │
1387 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1388 │pattern │ "" │ "" │ valid (no │ pattern │ pattern │
1389 │ │ │ │ remapping) │ │ │
1390 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1391 │"" │ local │ remote │ valid │ local │ remote │
1392 │ │ │ │ (remap │ │ │
1393 │ │ │ │ single │ │ │
1394 │ │ │ │ local topic │ │ │
1395 │ │ │ │ to remote) │ │ │
1396 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1397 │"" │ local │ "" │ invalid │ │ │
1398 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1399 │"" │ "" │ remote │ invalid │ │ │
1400 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1401 │"" │ "" │ "" │ invalid │ │ │
1402 └────────┴────────┴────────┴─────────────┴────────────┴─────────────┘
1403 To remap an entire topic tree, use e.g.:
1404 topic # both 2 local/topic/ remote/topic/
1406 This option can be specified multiple times per bridge.
1408 Care must be taken to ensure that loops are not created with this
1410 option. If you are experiencing high CPU load from a broker, it is
1411 possible that you have a loop where each broker is forever
1412 forwarding each other the same messages.
1413 See also the cleansession option if you have messages arriving on
1415 unexpected topics when using incoming topics.
1416 Example Bridge Topic Remapping. The configuration below connects a
1418 bridge to the broker at test.mosquitto.org. It subscribes to the
1419 remote topic $SYS/broker/clients/total and republishes the messages
1420 received to the local topic test/mosquitto/org/clients/total
1421 connection test-mosquitto-org
1423 address test.mosquitto.org
1424 cleansession true
1425 topic clients/total in 0 test/mosquitto/org/ $SYS/broker/
1426 try_private [ true | false ]
1428 If try_private is set to true, the bridge will attempt to indicate
1429 to the remote broker that it is a bridge not an ordinary client. If
1430 successful, this means that loop detection will be more effective
1431 and that retained messages will be propagated correctly. Not all
1432 brokers support this feature so it may be necessary to set
1433 try_private to false if your bridge does not connect properly.
1434 Defaults to true.
1436 SSL/TLS Support
1438 The following options are available for all bridges to configure
1439 SSL/TLS support.
1440 bridge_alpn alpn
1442 Configure the application layer protocol negotiation option for the
1443 TLS session. Useful for brokers that support both websockets and
1444 MQTT on the same port.
1445 bridge_cafile file path
1447 One of bridge_cafile or bridge_capath must be provided to allow
1448 SSL/TLS support.
1449 bridge_cafile is used to define the path to a file containing the
1451 PEM encoded CA certificates that have signed the certificate for
1452 the remote broker.
1453 bridge_capath file path
1455 One of bridge_capath or bridge_cafile must be provided to allow
1456 SSL/TLS support.
1457 bridge_capath is used to define the path to a directory containing
1459 the PEM encoded CA certificates that have signed the certificate
1460 for the remote broker. For bridge_capath to work correctly, the
1461 certificate files must have ".crt" as the file ending and you must
1462 run "openssl rehash <path to bridge_capath>" each time you
1463 add/remove a certificate.
1464 bridge_certfile file path
1466 Path to the PEM encoded client certificate for this bridge, if
1467 required by the remote broker.
1468 bridge_identity identity
1470 Pre-shared-key encryption provides an alternative to certificate
1471 based encryption. A bridge can be configured to use PSK with the
1472 bridge_identity and bridge_psk options. This is the client identity
1473 used with PSK encryption. Only one of certificate and PSK based
1474 encryption can be used on one bridge at once.
1475 bridge_insecure [ true | false ]
1477 When using certificate based TLS, the bridge will attempt to verify
1478 the hostname provided in the remote certificate matches the
1479 host/address being connected to. This may cause problems in testing
1480 scenarios, so bridge_insecure may be set to true to disable the
1481 hostname verification.
1482 Setting this option to true means that a malicious third party
1484 could potentially impersonate your server, so it should always be
1485 set to false in production environments.
1486 bridge_keyfile file path
1488 Path to the PEM encoded private key for this bridge, if required by
1489 the remote broker.
1490 bridge_psk key
1492 Pre-shared-key encryption provides an alternative to certificate
1493 based encryption. A bridge can be configured to use PSK with the
1494 bridge_identity and bridge_psk options. This is the pre-shared-key
1495 in hexadecimal format with no "0x". Only one of certificate and PSK
1496 based encryption can be used on one bridge at once.
1497 bridge_require_ocsp [ true | false ]
1499 When set to true, the bridge requires OCSP on the TLS connection it
1500 opens as client.
1501 bridge_tls_version version
1503 Configure the version of the TLS protocol to be used for this
1504 bridge. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. Defaults
1505 to tlsv1.2. The remote broker must support the same version of TLS
1506 for the connection to succeed.
1507
1509 mosquitto.conf
1510
1512 mosquitto bug information can be found at
1513 https://github.com/eclipse/mosquitto/issues
1514
1516 mosquitto(8), mosquitto_passwd(1), mosquitto-tls(7), mqtt(7),
1517 limits.conf(5)
1518
1520 Roger Light <roger@atchoo.org>
1521Mosquitto Project 08/16/2022 MOSQUITTO.CONF(5)