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 persistent clients (those with clean session set
642 to false) to be removed if they do not reconnect within a certain
643 time frame. This is a non-standard option. As far as the MQTT spec
644 is concerned, persistent clients persist forever.
645 Badly designed clients may set clean session to false whilst using
647 a randomly generated client id. This leads to persistent clients
648 that will never reconnect. This option allows these clients to be
649 removed.
650 The expiration period should be an integer followed by one of h d w
652 m y for hour, day, week, month and year respectively. For example:
653 • persistent_client_expiration 2m
655 • persistent_client_expiration 14d
657 • persistent_client_expiration 1y
659 As this is a non-standard option, the default if not set is to
661 never expire persistent clients.
662 This option applies globally.
664 Reloaded on reload signal.
666 pid_file file path
668 Write a pid file to the file specified. If not given (the default),
669 no pid file will be written. If the pid file cannot be written,
670 mosquitto will exit.
671 If mosquitto is being automatically started by an init script it
673 will usually be required to write a pid file. This should then be
674 configured as e.g. /var/run/mosquitto/mosquitto.pid
675 Not reloaded on reload signal.
677 plugin_opt_* value
679 Options to be passed to the most recent plugin defined in the
680 configuration file. See the specific plugin instructions for
681 details of what options are available.
682 Applies to the current plugin being configured.
684 This is also available as the auth_opt_* option, but this use is
686 deprecated and will be removed in a future version.
687 plugin file path
689 Specify an external module to use for authentication and access
690 control. This allows custom username/password and access control
691 functions to be created.
692 Can be specified multiple times to load multiple plugins. The
694 plugins will be processed in the order that they are specified.
695 If password_file, or acl_file are used in the config file alongsize
697 plugin, the plugin checks will run after the built in checks.
698 Not currently reloaded on reload signal.
700 See also https://mosquitto.org/documentation/dynamic-security/
702 This is also available as the auth_plugin option, but this use is
704 deprecated and will be removed in a future version.
705 psk_file file path
707 Set the path to a pre-shared-key file. This option requires a
708 listener to be have PSK support enabled. If defined, the contents
709 of the file are used to control client access to the broker. Each
710 line should be in the format "identity:key", where the key is a
711 hexadecimal string with no leading "0x". A client connecting to a
712 listener that has PSK support enabled must provide a matching
713 identity and PSK to allow the encrypted connection to proceed.
714 If per_listener_settings is true, this option applies to the
716 current listener being configured only. If per_listener_settings is
717 false, this option applies to all listeners.
718 Reloaded on reload signal. The currently loaded identity and key
720 data will be freed and reloaded. Clients that are already connected
721 will not be affected.
722 queue_qos0_messages [ true | false ]
724 Set to true to queue messages with QoS 0 when a persistent client
725 is disconnected. These messages are included in the limit imposed
726 by max_queued_messages. Defaults to false.
727 Note that the MQTT v3.1.1 spec states that only QoS 1 and 2
729 messages should be saved in this situation so this is a
730 non-standard option.
731 This option applies globally.
733 Reloaded on reload signal.
735 retain_available [ true | false ]
737 If set to false, then retained messages are not supported. Clients
738 that send a message with the retain bit will be disconnected if
739 this option is set to false. Defaults to true.
740 This option applies globally.
742 Reloaded on reload signal.
744 set_tcp_nodelay [ true | false ]
746 If set to true, the TCP_NODELAY option will be set on client
747 sockets to disable Nagle's algorithm. This has the effect of
748 reducing latency of some messages at potentially increasing the
749 number of TCP packets being sent. Defaults to false.
750 This option applies globally.
752 Reloaded on reload signal.
754 sys_interval seconds
756 The integer number of seconds between updates of the $SYS
757 subscription hierarchy, which provides status information about the
758 broker. If unset, defaults to 10 seconds.
759 Set to 0 to disable publishing the $SYS hierarchy completely.
761 This option applies globally.
763 Reloaded on reload signal.
765 upgrade_outgoing_qos [ true | false ]
767 The MQTT specification requires that the QoS of a message delivered
768 to a subscriber is never upgraded to match the QoS of the
769 subscription. Enabling this option changes this behaviour. If
770 upgrade_outgoing_qos is set true, messages sent to a subscriber
771 will always match the QoS of its subscription. This is a
772 non-standard option not provided for by the spec. Defaults to
773 false.
774 This option applies globally.
776 Reloaded on reload signal.
778 user username
780 When run as root, change to this user and its primary group on
781 startup. If set to "mosquitto" or left unset, and if the
782 "mosquitto" user does not exist, then mosquitto will change to the
783 "nobody" user instead. If this is set to another value and
784 mosquitto is unable to change to this user and group, it will exit
785 with an error. The user specified must have read/write access to
786 the persistence database if it is to be written. If run as a
787 non-root user, this setting has no effect. Defaults to mosquitto.
788 This setting has no effect on Windows and so you should run
790 mosquitto as the user you wish it to run as.
791 Not reloaded on reload signal.
793
795 The network ports that mosquitto listens on can be controlled using
796 listeners. The default listener options can be overridden and further
797 listeners can be created.
798 General Options
800 bind_address address
801 This option is deprecated and will be removed in a future version.
802 Use the listener instead.
803 Listen for incoming network connections on the specified IP
805 address/hostname only. This is useful to restrict access to certain
806 network interfaces. To restrict access to mosquitto to the local
807 host only, use "bind_address localhost". This only applies to the
808 default listener. Use the listener option to control other
809 listeners.
810 It is recommended to use an explicit listener rather than rely on
812 the implicit default listener options like this.
813 Not reloaded on reload signal.
815 bind_interface device
817 Listen for incoming network connections only on the specified
818 interface. This is similar to the bind_address option but is useful
819 when an interface has multiple addresses or the address may change.
820 If used at the same time as the bind_address for the default
822 listener, or the bind address/host part of the listener, then
823 bind_interface will take priority.
824 This option is not available on Windows.
826 Not reloaded on reload signal.
828 http_dir directory
830 When a listener is using the websockets protocol, it is possible to
831 serve http data as well. Set http_dir to a directory which contains
832 the files you wish to serve. If this option is not specified, then
833 no normal http connections will be possible.
834 Not reloaded on reload signal.
836 listener port [bind address/host/unix socket path]
838 Listen for incoming network connection on the specified port. A
839 second optional argument allows the listener to be bound to a
840 specific ip address/hostname. If this variable is used and neither
841 the global bind_address nor port options are used then the default
842 listener will not be started.
843 The bind address/host option allows this listener to be bound to a
845 specific IP address by passing an IP address or hostname. For
846 websockets listeners, it is only possible to pass an IP address
847 here.
848 On systems that support Unix Domain Sockets, this option can also
850 be used to create a Unix socket rather than opening a TCP socket.
851 In this case, the port must be set to 0, and the unix socket path
852 must be given.
853 This option may be specified multiple times. See also the
855 mount_point option.
856 Not reloaded on reload signal.
858 max_connections count
860 Limit the total number of clients connected for the current
861 listener. Set to -1 to have "unlimited" connections. Note that
862 other limits may be imposed that are outside the control of
863 mosquitto. See e.g. limits.conf().
864 Not reloaded on reload signal.
866 max_qos value
868 Limit the QoS value allowed for clients connecting to this
869 listener. Defaults to 2, which means any QoS can be used. Set to 0
870 or 1 to limit to those QoS values. This makes use of an MQTT v5
871 feature to notify clients of the limitation. MQTT v3.1.1 clients
872 will not be aware of the limitation. Clients publishing to this
873 listener with a too-high QoS will be disconnected.
874 Not reloaded on reload signal.
876 max_topic_alias number
878 This option sets the maximum number topic aliases that an MQTT v5
879 client is allowed to create. This option applies per listener.
880 Defaults to 10. Set to 0 to disallow topic aliases. The maximum
881 value possible is 65535.
882 Not reloaded on reload signal.
884 mount_point topic prefix
886 This option is used with the listener option to isolate groups of
887 clients. When a client connects to a listener which uses this
888 option, the string argument is attached to the start of all topics
889 for this client. This prefix is removed when any messages are sent
890 to the client. This means a client connected to a listener with
891 mount point example can only see messages that are published in the
892 topic hierarchy example and below.
893 Not reloaded on reload signal.
895 port port number
897 This option is deprecated and will be removed in a future version.
898 Use the listener instead.
899 Set the network port for the default listener to listen on.
901 Defaults to 1883.
902 Not reloaded on reload signal.
904 It is recommended to use an explicit listener rather than rely on
906 the implicit default listener options like this.
907 protocol value
909 Set the protocol to accept for the current listener. Can be mqtt,
910 the default, or websockets if available.
911 Websockets support is currently disabled by default at compile
913 time. Certificate based TLS may be used with websockets, except
914 that only the cafile, certfile, keyfile, ciphers, and
915 ciphers_tls1.3 options are supported.
916 Not reloaded on reload signal.
918 socket_domain [ ipv4 | ipv6 ]
920 By default, a listener will attempt to listen on all supported IP
921 protocol versions. If you do not have an IPv4 or IPv6 interface you
922 may wish to disable support for either of those protocol versions.
923 In particular, note that due to the limitations of the websockets
924 library, it will only ever attempt to open IPv6 sockets if IPv6
925 support is compiled in, and so will fail if IPv6 is not available.
926 Set to ipv4 to force the listener to only use IPv4, or set to ipv6
928 to force the listener to only use IPv6. If you want support for
929 both IPv4 and IPv6, then do not use the socket_domain option.
930 Not reloaded on reload signal.
932 use_username_as_clientid [ true | false ]
934 Set use_username_as_clientid to true to replace the clientid that a
935 client connected with its username. This allows authentication to
936 be tied to the clientid, which means that it is possible to prevent
937 one client disconnecting another by using the same clientid.
938 Defaults to false.
939 If a client connects with no username it will be disconnected as
941 not authorised when this option is set to true. Do not use in
942 conjunction with clientid_prefixes.
943 See also use_identity_as_username.
945 Not reloaded on reload signal.
947 websockets_log_level level
949 Change the websockets logging level. This is a global option, it is
950 not possible to set per listener. This is an integer that is
951 interpreted by libwebsockets as a bit mask for its lws_log_levels
952 enum. See the libwebsockets documentation for more details.
953 To use this option, log_type websockets must also be enabled.
955 Defaults to 0.
956 websockets_headers_size size
958 Change the websockets headers size. This is a global option, it is
959 not possible to set per listener. This option sets the size of the
960 buffer used in the libwebsockets library when reading HTTP headers.
961 If you are passing large header data such as cookies then you may
962 need to increase this value. If left unset, or set to 0, then the
963 default of 1024 bytes will be used.
964 Certificate based SSL/TLS Support
966 The following options are available for all listeners to configure
967 certificate based SSL support. See also "Pre-shared-key based SSL/TLS
968 support".
969 cafile file path
971 cafile is used to define the path to a file containing the PEM
972 encoded CA certificates that are trusted when checking incoming
973 client certificates.
974 capath directory path
976 capath is used to define a directory that contains PEM encoded CA
977 certificates that are trusted when checking incoming client
978 certificates. For capath to work correctly, the certificates files
979 must have ".pem" as the file ending and you must run "openssl
980 rehash <path to capath>" each time you add/remove a certificate.
981 certfile file path
983 Path to the PEM encoded server certificate. This option and keyfile
984 must be present to enable certificate based TLS encryption.
985 The certificate pointed to by this option will be reloaded when
987 Mosquitto receives a SIGHUP signal. This can be used to load new
988 certificates prior to the existing ones expiring.
989 ciphers cipher:list
991 The list of allowed ciphers for this listener, for TLS v1.2 and
992 earlier only, each separated with a colon. Available ciphers can be
993 obtained using the "openssl ciphers" command.
994 ciphers_tls1.3 cipher:list
996 The list of allowed ciphersuites for this listener, for TLS v1.3,
997 each separated with a colon.
998 crlfile file path
1000 If you have require_certificate set to true, you can create a
1001 certificate revocation list file to revoke access to particular
1002 client certificates. If you have done this, use crlfile to point to
1003 the PEM encoded revocation file.
1004 dhparamfile file path
1006 To allow the use of ephemeral DH key exchange, which provides
1007 forward security, the listener must load DH parameters. This can be
1008 specified with the dhparamfile option. The dhparamfile can be
1009 generated with the command e.g.
1010 openssl dhparam -out dhparam.pem 2048
1012 keyfile file path
1014 Path to the PEM encoded server key. This option and certfile must
1015 be present to enable certificate based TLS encryption.
1016 The private key pointed to by this option will be reloaded when
1018 Mosquitto receives a SIGHUP signal. This can be used to load new
1019 keys prior to the existing ones expiring.
1020 require_certificate [ true | false ]
1022 By default an SSL/TLS enabled listener will operate in a similar
1023 fashion to a https enabled web server, in that the server has a
1024 certificate signed by a CA and the client will verify that it is a
1025 trusted certificate. The overall aim is encryption of the network
1026 traffic. By setting require_certificate to true, a client
1027 connecting to this listener must provide a valid certificate in
1028 order for the network connection to proceed. This allows access to
1029 the broker to be controlled outside of the mechanisms provided by
1030 MQTT.
1031 tls_engine engine
1033 A valid openssl engine id. These can be listed with openssl engine
1034 command.
1035 tls_engine_kpass_sha1 engine_kpass_sha1
1037 SHA1 of the private key password when using an TLS engine. Some TLS
1038 engines such as the TPM engine may require the use of a password in
1039 order to be accessed. This option allows a hex encoded SHA1 hash of
1040 the password to the engine directly, instead of the user being
1041 prompted for the password.
1042 tls_keyform [ pem | engine ]
1044 Specifies the type of private key in use when making TLS
1045 connections.. This can be "pem" or "engine". This parameter is
1046 useful when a TPM module is being used and the private key has been
1047 created with it. Defaults to "pem", which means normal private key
1048 files are used.
1049 tls_version version
1051 Configure the minimum version of the TLS protocol to be used for
1052 this listener. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. If
1053 left unset, the default of allowing TLS v1.3 and v1.2.
1054 In Mosquitto version 1.6.x and earlier, this option set the only
1056 TLS protocol version that was allowed, rather than the minimum.
1057 use_identity_as_username [ true | false ]
1059 If require_certificate is true, you may set
1060 use_identity_as_username to true to use the CN value from the
1061 client certificate as a username. If this is true, the
1062 password_file option will not be used for this listener.
1063 This takes priority over use_subject_as_username if both are set to
1065 true.
1066 See also use_subject_as_username
1068 use_subject_as_username [ true | false ]
1070 If require_certificate is true, you may set use_subject_as_username
1071 to true to use the complete subject value from the client
1072 certificate as a username. If this is true, the password_file
1073 option will not be used for this listener.
1074 The subject will be generated in a form similar to CN=test
1076 client,OU=Production,O=Server,L=Nottingham,ST=Nottinghamshire,C=GB.
1077 See also use_identity_as_username
1079 Pre-shared-key based SSL/TLS Support
1081 The following options are available for all listeners to configure
1082 pre-shared-key based SSL support. See also "Certificate based SSL/TLS
1083 support".
1084 ciphers cipher:list
1086 When using PSK, the encryption ciphers used will be chosen from the
1087 list of available PSK ciphers. If you want to control which ciphers
1088 are available, use this option. The list of available ciphers can
1089 be optained using the "openssl ciphers" command and should be
1090 provided in the same format as the output of that command.
1091 psk_hint hint
1093 The psk_hint option enables pre-shared-key support for this
1094 listener and also acts as an identifier for this listener. The hint
1095 is sent to clients and may be used locally to aid authentication.
1096 The hint is a free form string that doesn't have much meaning in
1097 itself, so feel free to be creative.
1098 If this option is provided, see psk_file to define the pre-shared
1100 keys to be used or create a security plugin to handle them.
1101 tls_version version
1103 Configure the minimum version of the TLS protocol to be used for
1104 this listener. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. If
1105 left unset, the default of allowing TLS v1.3 and v1.2.
1106 In Mosquitto version 1.6.x and earlier, this option set the only
1108 TLS protocol version that was allowed, rather than the minimum.
1109 use_identity_as_username [ true | false ]
1111 Set use_identity_as_username to have the psk identity sent by the
1112 client used as its username. The username will be checked as
1113 normal, so password_file or another means of authentication
1114 checking must be used. No password will be used.
1115
1117 Multiple bridges (connections to other brokers) can be configured using
1118 the following variables.
1119 Bridges cannot currently be reloaded on reload signal.
1121 address address[:port] [address[:port]], addresses address[:port]
1123 [address[:port]]
1124 Specify the address and optionally the port of the bridge to
1125 connect to. This must be given for each bridge connection. If the
1126 port is not specified, the default of 1883 is used.
1127 If you use an IPv6 address, then the port is not optional.
1129 Multiple host addresses can be specified on the address config. See
1131 the round_robin option for more details on the behaviour of bridges
1132 with multiple addresses.
1133 bridge_attempt_unsubscribe [ true | false ]
1135 If a bridge has topics that have "out" direction, the default
1136 behaviour is to send an unsubscribe request to the remote broker on
1137 that topic. This means that changing a topic direction from "in" to
1138 "out" will not keep receiving incoming messages. Sending these
1139 unsubscribe requests is not always desirable, setting
1140 bridge_attempt_unsubscribe to false will disable sending the
1141 unsubscribe request. Defaults to true.
1142 bridge_bind_address ip address
1144 If you need to have the bridge connect over a particular network
1145 interface, use bridge_bind_address to tell the bridge which local
1146 IP address the socket should bind to, e.g. bridge_bind_address
1147 192.168.1.10.
1148 bridge_max_packet_size value
1150 If you wish to restrict the size of messages sent to a remote
1151 bridge, use this option. This sets the maximum number of bytes for
1152 the total message, including headers and payload. Note that MQTT v5
1153 brokers may provide their own maximum-packet-size property. In this
1154 case, the smaller of the two limits will be used. Set to 0 for
1155 "unlimited".
1156 bridge_outgoing_retain [ true | false ]
1158 Some MQTT brokers do not allow retained messages. MQTT v5 gives a
1159 mechanism for brokers to tell clients that they do not support
1160 retained messages, but this is not possible for MQTT v3.1.1 or
1161 v3.1. If you need to bridge to a v3.1.1 or v3.1 broker that does
1162 not support retained messages, set the bridge_outgoing_retain
1163 option to false. This will remove the retain bit on all outgoing
1164 messages to that bridge, regardless of any other setting. Defaults
1165 to true.
1166 bridge_protocol_version version
1168 Set the version of the MQTT protocol to use with for this bridge.
1169 Can be one of mqttv50, mqttv311 or mqttv31. Defaults to mqttv311.
1170 cleansession [ true | false ]
1172 Set the clean session option for this bridge. Setting to false (the
1173 default), means that all subscriptions on the remote broker are
1174 kept in case of the network connection dropping. If set to true,
1175 all subscriptions and messages on the remote broker will be cleaned
1176 up if the connection drops. Note that setting to true may cause a
1177 large amount of retained messages to be sent each time the bridge
1178 reconnects.
1179 If you are using bridges with cleansession set to false (the
1181 default), then you may get unexpected behaviour from incoming
1182 topics if you change what topics you are subscribing to. This is
1183 because the remote broker keeps the subscription for the old topic.
1184 If you have this problem, connect your bridge with cleansession set
1185 to true, then reconnect with cleansession set to false as normal.
1186 local_cleansession [ true | false]
1188 The regular cleansession covers both the local subscriptions and
1189 the remote subscriptions. local_cleansession allows splitting this.
1190 Setting false will mean that the local connection will preserve
1191 subscription, independent of the remote connection.
1192 Defaults to the value of bridge.cleansession unless explicitly
1194 specified.
1195 connection name
1197 This variable marks the start of a new bridge connection. It is
1198 also used to give the bridge a name which is used as the client id
1199 on the remote broker.
1200 keepalive_interval seconds
1202 Set the number of seconds after which the bridge should send a ping
1203 if no other traffic has occurred. Defaults to 60. A minimum value
1204 of 5 seconds is allowed.
1205 idle_timeout seconds
1207 Set the amount of time a bridge using the lazy start type must be
1208 idle before it will be stopped. Defaults to 60 seconds.
1209 local_clientid id
1211 Set the clientid to use on the local broker. If not defined, this
1212 defaults to local.<remote_clientid>. If you are bridging a broker
1213 to itself, it is important that local_clientid and remote_clientid
1214 do not match.
1215 local_password password
1217 Configure the password to be used when connecting this bridge to
1218 the local broker. This may be important when authentication and
1219 ACLs are being used.
1220 local_username username
1222 Configure the username to be used when connecting this bridge to
1223 the local broker. This may be important when authentication and
1224 ACLs are being used.
1225 notifications [ true | false ]
1227 If set to true, publish notification messages to the local and
1228 remote brokers giving information about the state of the bridge
1229 connection. Retained messages are published to the topic
1230 $SYS/broker/connection/<remote_clientid>/state unless otherwise set
1231 with notification_topics. If the message is 1 then the connection
1232 is active, or 0 if the connection has failed. Defaults to true.
1233 This uses the Last Will and Testament (LWT) feature.
1235 notifications_local_only [ true | false ]
1237 If set to true, only publish notification messages to the local
1238 broker giving information about the state of the bridge connection.
1239 Defaults to false.
1240 notification_topic topic
1242 Choose the topic on which notifications will be published for this
1243 bridge. If not set the messages will be sent on the topic
1244 $SYS/broker/connection/<remote_clientid>/state.
1245 remote_clientid id
1247 Set the client id for this bridge connection. If not defined, this
1248 defaults to 'name.hostname', where name is the connection name and
1249 hostname is the hostname of this computer.
1250 This replaces the old "clientid" option to avoid confusion with
1252 local/remote sides of the bridge. "clientid" remains valid for the
1253 time being.
1254 remote_password value
1256 Configure a password for the bridge. This is used for
1257 authentication purposes when connecting to a broker that supports
1258 MQTT v3.1 and up and requires a username and/or password to
1259 connect. This option is only valid if a remote_username is also
1260 supplied.
1261 This replaces the old "password" option to avoid confusion with
1263 local/remote sides of the bridge. "password" remains valid for the
1264 time being.
1265 remote_username name
1267 Configure a username for the bridge. This is used for
1268 authentication purposes when connecting to a broker that supports
1269 MQTT v3.1 and up and requires a username and/or password to
1270 connect. See also the remote_password option.
1271 This replaces the old "username" option to avoid confusion with
1273 local/remote sides of the bridge. "username" remains valid for the
1274 time being.
1275 restart_timeout base cap, restart_timeout constant
1277 Set the amount of time a bridge using the automatic start type will
1278 wait until attempting to reconnect.
1279 This option can be configured to use a constant delay time in
1281 seconds, or to use a backoff mechanism based on "Decorrelated
1282 Jitter", which adds a degree of randomness to when the restart
1283 occurs, starting at the base and increasing up to the cap. Set a
1284 constant timeout of 20 seconds:
1285 restart_timeout 20
1287 Set backoff with a base (start value) of 10 seconds and a cap
1289 (upper limit) of 60 seconds:
1290 restart_timeout 10 30
1292 Defaults to jitter with a base of 5 seconds and cap of 30 seconds.
1294 round_robin [ true | false ]
1296 If the bridge has more than one address given in the
1297 address/addresses configuration, the round_robin option defines the
1298 behaviour of the bridge on a failure of the bridge connection. If
1299 round_robin is false, the default value, then the first address is
1300 treated as the main bridge connection. If the connection fails, the
1301 other secondary addresses will be attempted in turn. Whilst
1302 connected to a secondary bridge, the bridge will periodically
1303 attempt to reconnect to the main bridge until successful.
1304 If round_robin is true, then all addresses are treated as equals.
1306 If a connection fails, the next address will be tried and if
1307 successful will remain connected until it fails.
1308 start_type [ automatic | lazy | once ]
1310 Set the start type of the bridge. This controls how the bridge
1311 starts and can be one of three types: automatic, lazy and once.
1312 Note that RSMB provides a fourth start type "manual" which isn't
1313 currently supported by mosquitto.
1314 automatic is the default start type and means that the bridge
1316 connection will be started automatically when the broker starts and
1317 also restarted after a short delay (30 seconds) if the connection
1318 fails.
1319 Bridges using the lazy start type will be started automatically
1321 when the number of queued messages exceeds the number set with the
1322 threshold option. It will be stopped automatically after the time
1323 set by the idle_timeout parameter. Use this start type if you wish
1324 the connection to only be active when it is needed.
1325 A bridge using the once start type will be started automatically
1327 when the broker starts but will not be restarted if the connection
1328 fails.
1329 threshold count
1331 Set the number of messages that need to be queued for a bridge with
1332 lazy start type to be restarted. Defaults to 10 messages.
1333 topic pattern [[[ out | in | both ] qos-level] local-prefix
1335 remote-prefix]
1336 Define a topic pattern to be shared between the two brokers. Any
1337 topics matching the pattern (which may include wildcards) are
1338 shared. The second parameter defines the direction that the
1339 messages will be shared in, so it is possible to import messages
1340 from a remote broker using in, export messages to a remote broker
1341 using out or share messages in both directions. If this parameter
1342 is not defined, the default of out is used. The QoS level defines
1343 the publish/subscribe QoS level used for this topic and defaults to
1344 0.
1345 The local-prefix and remote-prefix options allow topics to be
1347 remapped when publishing to and receiving from remote brokers. This
1348 allows a topic tree from the local broker to be inserted into the
1349 topic tree of the remote broker at an appropriate place.
1350 For incoming topics, the bridge will prepend the pattern with the
1352 remote prefix and subscribe to the resulting topic on the remote
1353 broker. When a matching incoming message is received, the remote
1354 prefix will be removed from the topic and then the local prefix
1355 added.
1356 For outgoing topics, the bridge will prepend the pattern with the
1358 local prefix and subscribe to the resulting topic on the local
1359 broker. When an outgoing message is processed, the local prefix
1360 will be removed from the topic then the remote prefix added.
1361 When using topic mapping, an empty prefix can be defined using the
1363 place marker "". Using the empty marker for the topic itself is
1364 also valid. The table below defines what combination of empty or
1365 value is valid. The Full Local Topic and Full Remote Topic show the
1366 resulting topics that would be used on the local and remote ends of
1367 the bridge. For example, for the first table row if you publish to
1368 L/topic on the local broker, then the remote broker will receive a
1369 message on the topic R/topic.
1370 ┌────────┬────────┬────────┬─────────────┬────────────┬─────────────┐
1372 │Pattern │ Local │ Remote │ Validity │ Full Local │ Full Remote │
1373 │ │ Prefix │ Prefix │ │ Topic │ Topic │
1374 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1375 │pattern │ L/ │ R/ │ valid │ L/pattern │ R/pattern │
1376 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1377 │pattern │ L/ │ "" │ valid │ L/pattern │ pattern │
1378 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1379 │pattern │ "" │ R/ │ valid │ pattern │ R/pattern │
1380 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1381 │pattern │ "" │ "" │ valid (no │ pattern │ pattern │
1382 │ │ │ │ remapping) │ │ │
1383 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1384 │"" │ local │ remote │ valid │ local │ remote │
1385 │ │ │ │ (remap │ │ │
1386 │ │ │ │ single │ │ │
1387 │ │ │ │ local topic │ │ │
1388 │ │ │ │ to remote) │ │ │
1389 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1390 │"" │ local │ "" │ invalid │ │ │
1391 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1392 │"" │ "" │ remote │ invalid │ │ │
1393 ├────────┼────────┼────────┼─────────────┼────────────┼─────────────┤
1394 │"" │ "" │ "" │ invalid │ │ │
1395 └────────┴────────┴────────┴─────────────┴────────────┴─────────────┘
1396 To remap an entire topic tree, use e.g.:
1397 topic # both 2 local/topic/ remote/topic/
1399 This option can be specified multiple times per bridge.
1401 Care must be taken to ensure that loops are not created with this
1403 option. If you are experiencing high CPU load from a broker, it is
1404 possible that you have a loop where each broker is forever
1405 forwarding each other the same messages.
1406 See also the cleansession option if you have messages arriving on
1408 unexpected topics when using incoming topics.
1409 Example Bridge Topic Remapping. The configuration below connects a
1411 bridge to the broker at test.mosquitto.org. It subscribes to the
1412 remote topic $SYS/broker/clients/total and republishes the messages
1413 received to the local topic test/mosquitto/org/clients/total
1414 connection test-mosquitto-org
1416 address test.mosquitto.org
1417 cleansession true
1418 topic clients/total in 0 test/mosquitto/org/ $SYS/broker/
1419 try_private [ true | false ]
1421 If try_private is set to true, the bridge will attempt to indicate
1422 to the remote broker that it is a bridge not an ordinary client. If
1423 successful, this means that loop detection will be more effective
1424 and that retained messages will be propagated correctly. Not all
1425 brokers support this feature so it may be necessary to set
1426 try_private to false if your bridge does not connect properly.
1427 Defaults to true.
1429 SSL/TLS Support
1431 The following options are available for all bridges to configure
1432 SSL/TLS support.
1433 bridge_alpn alpn
1435 Configure the application layer protocol negotiation option for the
1436 TLS session. Useful for brokers that support both websockets and
1437 MQTT on the same port.
1438 bridge_cafile file path
1440 One of bridge_cafile or bridge_capath must be provided to allow
1441 SSL/TLS support.
1442 bridge_cafile is used to define the path to a file containing the
1444 PEM encoded CA certificates that have signed the certificate for
1445 the remote broker.
1446 bridge_capath file path
1448 One of bridge_capath or bridge_cafile must be provided to allow
1449 SSL/TLS support.
1450 bridge_capath is used to define the path to a directory containing
1452 the PEM encoded CA certificates that have signed the certificate
1453 for the remote broker. For bridge_capath to work correctly, the
1454 certificate files must have ".crt" as the file ending and you must
1455 run "openssl rehash <path to bridge_capath>" each time you
1456 add/remove a certificate.
1457 bridge_certfile file path
1459 Path to the PEM encoded client certificate for this bridge, if
1460 required by the remote broker.
1461 bridge_identity identity
1463 Pre-shared-key encryption provides an alternative to certificate
1464 based encryption. A bridge can be configured to use PSK with the
1465 bridge_identity and bridge_psk options. This is the client identity
1466 used with PSK encryption. Only one of certificate and PSK based
1467 encryption can be used on one bridge at once.
1468 bridge_insecure [ true | false ]
1470 When using certificate based TLS, the bridge will attempt to verify
1471 the hostname provided in the remote certificate matches the
1472 host/address being connected to. This may cause problems in testing
1473 scenarios, so bridge_insecure may be set to true to disable the
1474 hostname verification.
1475 Setting this option to true means that a malicious third party
1477 could potentially impersonate your server, so it should always be
1478 set to false in production environments.
1479 bridge_keyfile file path
1481 Path to the PEM encoded private key for this bridge, if required by
1482 the remote broker.
1483 bridge_psk key
1485 Pre-shared-key encryption provides an alternative to certificate
1486 based encryption. A bridge can be configured to use PSK with the
1487 bridge_identity and bridge_psk options. This is the pre-shared-key
1488 in hexadecimal format with no "0x". Only one of certificate and PSK
1489 based encryption can be used on one bridge at once.
1490 bridge_require_ocsp [ true | false ]
1492 When set to true, the bridge requires OCSP on the TLS connection it
1493 opens as client.
1494 bridge_tls_version version
1496 Configure the version of the TLS protocol to be used for this
1497 bridge. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. Defaults
1498 to tlsv1.2. The remote broker must support the same version of TLS
1499 for the connection to succeed.
1500
1502 mosquitto.conf
1503
1505 mosquitto bug information can be found at
1506 https://github.com/eclipse/mosquitto/issues
1507
1509 mosquitto(8), mosquitto_passwd(1), mosquitto-tls(7), mqtt(7),
1510 limits.conf(5)
1511
1513 Roger Light <roger@atchoo.org>
1514Mosquitto Project 11/17/2021 MOSQUITTO.CONF(5)