mosquitto.conf man page

Note: It is suggested that you use the mosquitto_acl_file plugin instead of this option. Using plugins for authentication and authorisation allows greater control of what listeners they are applied to, without the need for the deprecated per_listener_settings option.

Set the path to an access control list file. If defined, the contents of the file are used to control client access to topics on the broker.

If this parameter is defined then only the topics listed will have access. Topic access is added with lines of the format:

topic [read|write|readwrite|deny] <topic>

The access type is controlled using "read", "write", "readwrite" or "deny". This parameter is optional (unless <topic> includes a space character) - if not given then the access is read/write. <topic> can contain the + or # wildcards as in subscriptions. The "deny" option can used to explicitly deny access to a topic that would otherwise be granted by a broader read/write/readwrite statement. Any "deny" topics are handled before topics that grant read/write access.

The first set of topics are applied to anonymous clients, assuming allow_anonymous is true. User specific topic ACLs are added after a user line as follows:

user <username>

The username referred to here is the same as in password_file. It is not the clientid.

It is also possible to define ACLs based on pattern substitution within the topic. The form is the same as for the topic keyword, but using pattern as the keyword.

pattern [read|write|readwrite|deny] <topic>

The patterns available for substitution are:

The substitution pattern must be the only text for that level of hierarchy. Pattern ACLs apply to all users even if the "user" keyword has previously been given.

Example:

pattern write sensor/%u/data

Allow access for bridge connection messages:

pattern write $SYS/broker/connection/%c/state

If the first character of a line of the ACL file is a # it is treated as a comment.

If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Note: In general it is not possible to grant write access to topics in the $SYS topic tree. The exception is $SYS/broker/connection/+/state.

Reloaded on reload signal. The currently loaded ACLs will be freed and reloaded. Existing subscriptions will be affected after the reload.

See also https://mosquitto.org/documentation/dynamic-security/

Global boolean value that determines whether clients that connect without providing a username are allowed to connect. If set to false then another means of connection should be created to control authenticated client access.

Defaults to false, unless no listeners are defined in the configuration file, in which case it set to true, but connections are only allowed from the local machine.

If you want to control this setting for each listener individually, use the listener_allow_anonymous option.

(Note: Deprecated) If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Reloaded on reload signal.

This option is deprecated and will be removed in a future version. The behaviour will default to true.

If a client is subscribed to multiple subscriptions that overlap, e.g. foo/# and foo/+/baz , then MQTT expects that when the broker receives a message on a topic that matches both subscriptions, such as foo/bar/baz, then the client should only receive the message once.

Mosquitto keeps track of which clients a message has been sent to in order to meet this requirement. This option allows this behaviour to be disabled, which may be useful if you have a large number of clients subscribed to the same set of topics and want to minimise memory usage.

It can be safely set to true if you know in advance that your clients will never have overlapping subscriptions, otherwise your clients must be able to correctly deal with duplicate messages even when then have QoS=2.

Defaults to true.

This option applies globally.

Reloaded on reload signal.

MQTT 3.1.1 and MQTT 5 allow clients to connect with a zero length client id and have the broker generate a client id for them. Use this option to allow/disallow this behaviour. Defaults to true.

See also the auto_id_prefix option.

If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Reloaded on reload signal.

If true then before an ACL check is made, the username/client id of the client needing the check is searched for the presence of either a '+' or '#' character. If either of these characters is found in either the username or client id, then the ACL check is denied before it is sent to the plugin.

This check prevents the case where a malicious user could circumvent an ACL check by using one of these characters as their username or client id. This is the same issue as was reported with mosquitto itself as CVE-2017-7650.

If you are entirely sure that the plugin you are using is not vulnerable to this attack (i.e. if you never use usernames or client ids in topics) then you can disable this extra check and hence have all ACL checks delivered to your plugin by setting this option to false.

Defaults to true.

Applies to the current authentication plugin being configured.

Not currently reloaded on reload signal.

This option is deprecated, please use listener_auto_id_prefix instead.

If allow_zero_length_clientid is true, this option allows you to set a string that will be prefixed to the automatically generated client ids to aid visibility in logs. Defaults to auto-.

If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Reloaded on reload signal.

The number of seconds that mosquitto will wait between each time it saves the in-memory database to disk. If set to 0, the in-memory database will only be saved when mosquitto exits or when receiving the SIGUSR1 signal. Note that this setting only has an effect if persistence is enabled. Defaults to 1800 seconds (30 minutes).

This option applies globally.

Reloaded on reload signal.

If true, mosquitto will count the number of subscription changes, retained messages received and queued messages and if the total exceeds autosave_interval then the in-memory database will be saved to disk. If false, mosquitto will save the in-memory database to disk by treating autosave_interval as a time in seconds.

This option applies globally.

Reloaded on reload signal.

This option affects the scenario when a client subscribes to a topic that has retained messages. It is possible that the client that published the retained message to the topic had access at the time they published, but that access has been subsequently removed. If check_retain_source is set to true, the default, the source of a retained message will be checked for access rights before it is republished. When set to false, no check will be made and the retained message will always be published.

This option applies globally, regardless of the per_listener_settings option.

This option is deprecated and will be removed in a future version.

If defined, only clients that have a clientid with a prefix that matches clientid_prefixes will be allowed to connect to the broker. For example, setting "secure-" here would mean a client "secure-client" could connect but another with clientid "mqtt" couldn't. By default, all client ids are valid.

This option applies globally.

Reloaded on reload signal. Note that currently connected clients will be unaffected by any changes.

If set to true, the log will include entries when clients connect and disconnect. If set to false, these entries will not appear.

This option applies globally.

Reloaded on reload signal.

If set to true, the $CONTROL/broker/v1 will be enabled. This currently allows interrogating which plugins are enabled, but in the future will allow access to configuring general broker options. If you enable this you should ensure you have authentication and appropriate access control configured, i.e. only allowing access to $CONTROL/broker/# for a limited set of users.

This option applies globally.

Reloaded on reload signal.

The maximum number of client sessions to allow across the whole broker. In this context a client session means either a client currently connected via the network, or a client that has clean_session = False (MQTT v3.x) and is disconnected, or has disconnected and still hasn't exceeded its session expiry interval (MQTT v5).

See also the max_connections setting, which applies to listeners. If you set global_max_clients to 1000 and max_connections on a listener to 10, then that means only 10 simultaneous connections will be allowed at once, with an overall maximum of 1000 client sessions.

This option applies globally.

Defaults to -1 (unlimited)

Reloaded on reload signal.

The maximum number of currently connected clients to allow across the whole broker.

See also the global_max_clients and max_connections settings.

This option applies globally.

Defaults to -1 (unlimited)

Reloaded on reload signal.

Load an external module to extend broker features. This loads plugins for use across all listeners, regardless of the value of the per_listener_settings option. This option functions the same as the plugin option in all other ways.

If you set per_listener_settings true, then define both a global_plugin and a plugin (which will be attached to a specific listener), then the global plugin will always be processed first.

If you set per_listener_settings false, then global_plugin behaves identically to plugin.

External configuration files may be included by using the include_dir option. This defines a directory that will be searched for config files. All files that end in '.conf' will be loaded as a configuration file. It is best to have this as the last option in the main file. This option will only be processed from the main configuration file. The directory specified must not contain the main configuration file.

The configuration files in include_dir are loaded in case sensitive alphabetical order, with the upper case of each letter ordered before the lower case of the same letter.

00.conf
01.conf
A.conf
a.conf
B.conf
b.conf

If this option is used multiple times, then each include_dir option is processed completely in the order that they are written in the main configuration file.

include_dir one.d
include_dir two.d

# files from one.d
B.conf
C.conf
# files from two.d
A.conf
D.conf

Send log messages to a particular destination. Possible destinations are: stdout stderr syslog topic file dlt android.

stdout and stderr log to the console on the named output.

syslog uses the userspace syslog facility which usually ends up in /var/log/messages or similar.

topic logs to the broker topic '$SYS/broker/log/<severity>', where severity is one of E, W, N, I, M which are error, warning, notice, information and message. Message type severity is used by the subscribe and unsubscribe log_type options and publishes log messages at $SYS/broker/log/M/subscribe and $SYS/broker/log/M/unsubscribe. Debug messages are never logged on topics.

The file destination requires an additional parameter which is the file to be logged to, e.g. "log_dest file /var/log/mosquitto.log". The file will be closed and reopened when the broker receives a HUP signal. Only a single file destination may be configured.

The dlt destination is for the automotive `Diagnostic Log and Trace` tool. This requires that Mosquitto has been compiled with DLT support.

The android destination is for Android only, and will output to the logd daemon.

Use "log_dest none" if you wish to disable logging. Defaults to stderr. This option may be specified multiple times.

Note that if the broker is running as a Windows service it will default to "log_dest none" and neither stdout nor stderr logging is available.

Reloaded on reload signal.

If using syslog logging (not on Windows), messages will be logged to the "daemon" facility by default. Use the log_facility option to choose which of local0 to local7 to log to instead. The option value should be an integer value, e.g. "log_facility 5" to use local5.

Boolean value, if set to true a timestamp value will be added to each log entry. The default is true.

Reloaded on reload signal.

Set the format of the log timestamp. If left unset, this is the number of seconds since the Unix epoch. This option is a free text string which will be passed to the strftime function as the format specifier. To get an ISO 8601 datetime, for example:

log_timestamp_format %Y-%m-%dT%H:%M:%S
					

Reloaded on reload signal.

Choose types of messages to log. Possible types are: debug, error, warning, notice, information, subscribe, unsubscribe, websockets, none, all.

Defaults to error, warning, notice and information. This option may be specified multiple times. Note that the debug type (used for decoding incoming/outgoing network packets) is never logged in topics.

Reloaded on reload signal.

Outgoing QoS 1 and 2 messages will be allowed in flight until this byte limit is reached. This allows control of outgoing message rate based on message size rather than message count. If the limit is set to 100, messages of over 100 bytes are still allowed, but only a single message can be in flight at once. Defaults to 0. (No limit).

See also the max_inflight_messages option.

This option applies globally.

Reloaded on reload signal.

The maximum number of outgoing QoS 1 or 2 messages that can be in the process of being transmitted simultaneously. This includes messages currently going through handshakes and messages that are being retried. Defaults to 20. Set to 0 for no maximum. If set to 1, this will guarantee in-order delivery of messages.

This option applies globally.

Reloaded on reload signal.

For MQTT v5 clients, it is possible to have the server send a "server keepalive" value that will override the keepalive value set by the client. This is intended to be used as a mechanism to say that the server will disconnect the client earlier than it anticipated, and that the client should use the new keepalive value. The max_keepalive option allows you to specify that clients may only connect with keepalive less than or equal to this value, otherwise they will be sent a server keepalive telling them to use max_keepalive. This only applies to MQTT v5 clients. The maximum value is 65535. Set to 0 to allow infinite keepalive. Defaults to 0.

Set to 0 to allow clients to set keepalive = 0, which means no keepalive checks are made and the client will never be disconnected by the broker if no messages are received. You should be very sure this is the behaviour that you want.

For MQTT v3.1.1 and v3.1 clients, there is no mechanism to tell the client what keepalive value they should use. If an MQTT v3.1.1 or v3.1 client specifies a keepalive time greater than max_keepalive they will be sent a CONNACK message with the "identifier rejected" reason code, and disconnected.

This option applies globally.

Reloaded on reload signal.

For MQTT v5 clients, it is possible to have the server send a "maximum packet size" value that will instruct the client it will not accept MQTT packets with size greater than value bytes. This applies to the full MQTT packet, not just the payload. Setting this option to a positive value will set the maximum packet size to that number of bytes. If a client sends a packet which is larger than this value, it will be disconnected. This applies to all clients regardless of the protocol version they are using, but v3.1.1 and earlier clients will of course not have received the maximum packet size information.

Defaults to 2000000 bytes since 2.1. Earlier versions defaulted to no limit.

This option applies to all clients, not just those using MQTT v5, but it is not possible to notify clients using MQTT v3.1.1 or MQTT v3.1 of the limit.

Setting below 20 bytes is forbidden because it is likely to interfere with normal client operation even with small payloads.

This option applies globally.

Reloaded on reload signal.

The number of outgoing QoS 1 and 2 messages above those currently in-flight will be queued (per client) by the broker. Once this limit has been reached, subsequent messages will be silently dropped. This is an important option if you are sending messages at a high rate and/or have clients who are slow to respond or may be offline for extended periods of time. Defaults to 0. (No maximum).

See also the max_queued_messages option. If both max_queued_messages and max_queued_bytes are specified, packets will be queued until the first limit is reached.

This option applies globally.

Reloaded on reload signal.

The maximum number of QoS 1 or 2 messages to hold in the queue (per client) above those messages that are currently in flight. Defaults to 1000. Set to 0 for no maximum (not recommended). See also the queue_qos0_messages and max_queued_bytes options.

This option applies globally.

Reloaded on reload signal.

This option sets the maximum number of heap memory bytes that the broker will allocate, and hence sets a hard limit on memory use by the broker. Memory requests that exceed this value will be denied. The effect will vary depending on what has been denied. If an incoming message is being processed, then the message will be dropped and the publishing client will be disconnected. If an outgoing message is being sent, then the individual message will be dropped and the receiving client will be disconnected. Defaults to no limit.

This option is only available if memory tracking support is compiled in.

Reloaded on reload signal. Setting to a lower value and reloading will not result in memory being freed.

This option sets the maximum publish payload size that the broker will allow. Received messages that exceed this size will not be accepted by the broker. This means that the message will not be forwarded on to subscribing clients, but the QoS flow will be completed for QoS 1 or QoS 2 messages. MQTT v5 clients using QoS 1 or QoS 2 will receive a PUBACK or PUBREC with the "implementation specific error" reason code.

The default value is 0, which means that all valid MQTT messages are accepted. MQTT imposes a maximum payload size of 268435455 bytes.

This option applies globally.

Reloaded on reload signal.

Note: It is suggested that you use the mosquitto_password_file plugin instead of this option. Using plugins for authentication and authorisation allows greater control of what listeners they are applied to, without the need for the deprecated per_listener_settings option.

Set the path to a password file. If defined, the contents of the file are used to control client access to the broker. The file can be created using the mosquitto_passwd(1) utility. If mosquitto is compiled without TLS support (it is recommended that TLS support is included), then the password file should be a text file with each line in the format "username:password", where the colon and password are optional but recommended. If allow_anonymous is set to false, only users defined in this file will be able to connect. Setting allow_anonymous to true when password_fileis defined is valid and could be used with acl_file to have e.g. read only guest/anonymous accounts and defined users that can publish.

If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Reloaded on reload signal. The currently loaded username and password data will be freed and reloaded. Clients that are already connected will not be affected.

See also mosquitto_passwd(1) and https://mosquitto.org/documentation/dynamic-security/

If true, then authentication and access control settings will be controlled on a per-listener basis. The following options are affected:

password_file, acl_file, psk_file, allow_anonymous, allow_zero_length_clientid, auto_id_prefix.

Note that if set to true, then a durable client (i.e. with clean session set to false) that has disconnected will use the ACL settings defined for the listener that it was most recently connected to.

The default behaviour is for this to be set to false, which maintains the settings behaviour from previous versions of mosquitto.

Reloaded on reload signal.

If true, connection, subscription and message data will be written to the disk in mosquitto.db at the location dictated by persistence_location. When mosquitto is restarted, it will reload the information stored in mosquitto.db. The data will be written to disk when mosquitto closes and also at periodic intervals as defined by autosave_interval. Writing of the persistence database may also be forced by sending mosquitto the SIGUSR1 signal. If false, the data will be stored in memory only. Defaults to false.

The persistence file may change its format in a new version. The broker can currently read all old formats, but will only save in the latest format. It should always be safe to upgrade, but cautious users may wish to take a copy of the persistence file before installing a new version so that they can roll back to an earlier version if necessary.

This option applies globally.

Reloaded on reload signal.

The filename to use for the persistent database. Defaults to mosquitto.db.

This option applies globally.

Reloaded on reload signal.

The path where the persistence database should be stored. If not given, then the current directory is used.

This option applies globally.

Reloaded on reload signal.

This option allows the session of persistent clients (those with clean session set to false) that are not currently connected to be removed if they do not reconnect within a certain time frame. This is a non-standard option in MQTT v3.1. MQTT v3.1.1 and v5.0 allow brokers to remove client sessions.

Badly designed clients may set clean session to false whilst using a randomly generated client id. This leads to persistent clients that connect once and never reconnect. This option allows these clients to be removed. This option allows persistent clients (those with clean session set to false) to be removed if they do not reconnect within a certain time frame.

The expiration period should be an integer followed by one of s h d w m y for second, hour, day, week, month and year respectively. For example:

Although it is possible to specify the expiration time in seconds, this is not a suggestion that you should use a short expiration interval. If you have a system where you think the clients should be automatically expired in a short time you should see about fixing the clients instead where possible.

As this is a non-standard option, the default if not set is to never expire persistent clients.

This option applies globally.

Reloaded on reload signal.

Write a pid file to the file specified. If not given (the default), no pid file will be written. If the pid file cannot be written, mosquitto will exit.

If mosquitto is being automatically started by an init script it will usually be required to write a pid file. This should then be configured as e.g. /var/run/mosquitto/mosquitto.pid

Not reloaded on reload signal.

Options to be passed to the most recent plugin defined in the configuration file. See the specific plugin instructions for details of what options are available.

Applies to the current plugin/global_plugin being configured.

This is also available as the auth_opt_* option, but this use is deprecated and will be removed in a future version.

Specify an external module to use for authentication, access control, and other features. This allows custom username/password and access control functions to be created and other behaviour to be modified.

Can be specified multiple times to load multiple plugins. The plugins will be processed in the order that they are specified.

If password_file, or acl_file are used in the config file alongsize plugin, the plugin checks will run before the built in checks.

Not currently reloaded on reload signal.

If per_listener_settings is set to true, this plugin will be loaded for the current listener only.

See also https://mosquitto.org/documentation/dynamic-security/ and the global_plugin option.

This is also available as the auth_plugin option, but this use is deprecated and will be removed in a future version.

Set the path to a pre-shared-key file. This option requires a listener to be have PSK support enabled. If defined, the contents of the file are used to control client access to the broker. Each line should be in the format "identity:key", where the key is a hexadecimal string with no leading "0x". A client connecting to a listener that has PSK support enabled must provide a matching identity and PSK to allow the encrypted connection to proceed.

If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Reloaded on reload signal. The currently loaded identity and key data will be freed and reloaded. Clients that are already connected will not be affected.

Set to true to queue messages with QoS 0 when a persistent client is disconnected. When bridges topics are configured with QoS level 1 or 2 incoming QoS 0 messages for these topics are also queued. These messages are included in the limit imposed by max_queued_messages. Defaults to false.

Note that the MQTT v3.1.1 spec states that only QoS 1 and 2 messages should be saved in this situation so this is a non-standard option.

This option applies globally.

Reloaded on reload signal.

If set to false, then retained messages are not supported. Clients that send a message with the retain bit will be disconnected if this option is set to false. Defaults to true.

This option applies globally.

Reloaded on reload signal.

The default behaviour of mosquitto is to remove retained messages that have reached their message-expiry-interval property the next time that that message is accessed - either by being replaced by a new message, or on the next subscription that matches the message. If you have a pattern of publishing many retained messages with a message-expiry-interval, but that are not subscribed to, then the expired retained messages will remain in memory. This option configures the broker to periodically check the retained tree for expired messages.

Defaults to off. Setting to a value greater than zero means the broker will make a check at an interval of that number of minutes.

This option applies globally.

Reloaded on reload signal.

If set to true, the TCP_NODELAY option will be set on client sockets to disable Nagle's algorithm. This has the effect of reducing latency of some messages at potentially increasing the number of TCP packets being sent. Defaults to false.

This option applies globally.

Reloaded on reload signal.

The integer number of seconds between updates of the $SYS subscription hierarchy, which provides status information about the broker. If unset, defaults to 10 seconds.

Set to 0 to disable publishing the $SYS hierarchy completely.

This option applies globally.

Reloaded on reload signal.

The MQTT specification requires that the QoS of a message delivered to a subscriber is never upgraded to match the QoS of the subscription. Enabling this option changes this behaviour. If upgrade_outgoing_qos is set true, messages sent to a subscriber will always match the QoS of its subscription. This is a non-standard option not provided for by the spec. Defaults to false.

This option applies globally.

Reloaded on reload signal.

When run as root, change to this user and its primary group on startup. If set to "mosquitto" or left unset, and if the "mosquitto" user does not exist, then mosquitto will change to the "nobody" user instead. If this is set to another value and mosquitto is unable to change to this user and group, it will exit with an error. The user specified must have read/write access to the persistence database if it is to be written. If run as a non-root user, this setting has no effect. Defaults to mosquitto.

This setting has no effect on Windows and so you should run mosquitto as the user you wish it to run as.

Not reloaded on reload signal.

Specify the address and optionally the port of the bridge to connect to. This must be given for each bridge connection. If the port is not specified, the default of 1883 is used.

If you use an IPv6 address, then the port is not optional.

Multiple host addresses can be specified on the address config. See the round_robin option for more details on the behaviour of bridges with multiple addresses.

If a bridge has topics that have "out" direction, the default behaviour is to send an unsubscribe request to the remote broker on that topic. This means that changing a topic direction from "in" to "out" will not keep receiving incoming messages. Sending these unsubscribe requests is not always desirable, setting bridge_attempt_unsubscribe to false will disable sending the unsubscribe request. Defaults to true.

If you need to have the bridge connect over a particular network interface, use bridge_bind_address to tell the bridge which local IP address the socket should bind to, e.g. bridge_bind_address 192.168.1.10.

If you wish to restrict the size of messages sent to a remote bridge, use this option. This sets the maximum number of bytes for the total message, including headers and payload. Note that MQTT v5 brokers may provide their own maximum-packet-size property. In this case, the smaller of the two limits will be used. Set to 0 for "unlimited".

If the bridge is using MQTT v5, this option sets the maximum number of topic aliases that the bridge will allow the remote broker to configure. Defaults to 10, maximum of 65535. Set to 0 to disable incoming topic aliases completely.

Some MQTT brokers do not allow retained messages. MQTT v5 gives a mechanism for brokers to tell clients that they do not support retained messages, but this is not possible for MQTT v3.1.1 or v3.1. If you need to bridge to a v3.1.1 or v3.1 broker that does not support retained messages, set the bridge_outgoing_retain option to false. This will remove the retain bit on all outgoing messages to that bridge, regardless of any other setting. Defaults to true.

Set the version of the MQTT protocol to use with for this bridge. Can be one of mqttv50, mqttv311 or mqttv31. Defaults to mqttv311.

If the bridge is using MQTT v5.0 then use bridge_receive_maximum to limit the number QoS 1 or 2 messages that can be in-flight at once. Must be 1-65535. Defaults to max_inflight_messages, which defaults to 20.

If the bridge is using MQTT v5.0 then use bridge_session_expiry_interval to set the session expiry interval. Set to 0 to have the session expire immediately when the connection drops. Set to 0xFFFFFFFF to have an infinite expiry interval. Otherwise the expiry interval is set to the number of seconds that you specify. Defaults to 0.

Set TCP keepalive parameters for this bridge connection. Use this option to allow you to set a long MQTT keepalive value, whilst still being able to detect the connection dropping in a reasonable time.

This may be useful when bridging to services that bill for PINGREQ messages.

Disabled by default.

It specifies the maximum amount of time (in milliseconds) that transmitted data may remain unacknowledged at TCP level. Popular Linux distributions seem to set this time to "up to 20 minutes with system defaults" (from Linux tcp man page). The default time is related to tcp_retries2. Reducing this value helps detecting dropped connections faster.

Be aware that when used in combination with TCP Keepalive, it might change the latter's behavior.

You can find more details about this setting at: https://blog.cloudflare.com/when-tcp-sockets-refuse-to-die/

Only available on Linux.

Set the clean session option for this bridge. Setting to false (the default), means that all subscriptions on the remote broker are kept in case of the network connection dropping. If set to true, all subscriptions and messages on the remote broker will be cleaned up if the connection drops. Note that setting to true may cause a large amount of retained messages to be sent each time the bridge reconnects.

If you are using bridges with cleansession set to false (the default), then you may get unexpected behaviour from incoming topics if you change what topics you are subscribing to. This is because the remote broker keeps the subscription for the old topic. If you have this problem, connect your bridge with cleansession set to true, then reconnect with cleansession set to false as normal.

The regular cleansession covers both the local subscriptions and the remote subscriptions. local_cleansession allows splitting this. Setting false will mean that the local connection will preserve subscription, independent of the remote connection.

Defaults to the value of bridge.cleansession unless explicitly specified.

This variable marks the start of a new bridge connection. It is also used to give the bridge a name which is used as the client id on the remote broker.

Set the number of seconds after which the bridge should send a ping if no other traffic has occurred. Defaults to 60. A minimum value of 5 seconds is allowed.

Set the amount of time a bridge using the lazy start type must be idle before it will be stopped. Defaults to 60 seconds.

Set the clientid to use on the local broker. If not defined, this defaults to local.<remote_clientid>. If you are bridging a broker to itself, it is important that local_clientid and remote_clientid do not match.

Configure the password to be used when connecting this bridge to the local broker. This may be important when authentication and ACLs are being used.

Configure the username to be used when connecting this bridge to the local broker. This may be important when authentication and ACLs are being used.

If set to true, publish notification messages to the local and remote brokers giving information about the state of the bridge connection. Retained messages are published to the topic $SYS/broker/connection/<remote_clientid>/state unless otherwise set with notification_topics. If the message is 1 then the connection is active, or 0 if the connection has failed. Defaults to true.

This uses the Last Will and Testament (LWT) feature.

If set to true, only publish notification messages to the local broker giving information about the state of the bridge connection. Defaults to false.

Choose the topic on which notifications will be published for this bridge. If not set the messages will be sent on the topic $SYS/broker/connection/<remote_clientid>/state.

Set the client id for this bridge connection. If not defined, this defaults to 'name.hostname', where name is the connection name and hostname is the hostname of this computer.

This replaces the old "clientid" option to avoid confusion with local/remote sides of the bridge. "clientid" remains valid for the time being.

Configure a password for the bridge. This is used for authentication purposes when connecting to a broker that supports MQTT v3.1 and up and requires a username and/or password to connect. This option is only valid if a remote_username is also supplied.

This replaces the old "password" option to avoid confusion with local/remote sides of the bridge. "password" remains valid for the time being.

Configure a username for the bridge. This is used for authentication purposes when connecting to a broker that supports MQTT v3.1 and up and requires a username and/or password to connect. See also the remote_password option.

This replaces the old "username" option to avoid confusion with local/remote sides of the bridge. "username" remains valid for the time being.

Set the amount of time a bridge using the automatic start type will wait until attempting to reconnect.

This option can be configured to use a constant delay time in seconds, or to use a backoff mechanism based on "Decorrelated Jitter", which adds a degree of randomness to when the restart occurs, starting at the base and increasing up to the cap. The backoff time will be reset to base after a successful connection. When stable is specified, the backoff time will be reset only if the connection remains open for at least stable seconds. Base has a minimum of 1 second and a maximum of 3600 seconds. Cap has a minimum of base, and a maximum of 7200 seconds.

Set a constant timeout of 20 seconds:

restart_timeout 20

Set backoff with a base (start value) of 10 seconds and a cap (upper limit) of 60 seconds:

restart_timeout 10 60

Same as previous example, but wait for the connection to be stable for at least 30 seconds before resetting the backoff:

restart_timeout 10 60 30

Defaults to jitter with a base of 5 seconds and cap of 30 seconds.

If the bridge has more than one address given in the address/addresses configuration, the round_robin option defines the behaviour of the bridge on a failure of the bridge connection. If round_robin is false, the default value, then the first address is treated as the main bridge connection. If the connection fails, the other secondary addresses will be attempted in turn. Whilst connected to a secondary bridge, the bridge will periodically attempt to reconnect to the main bridge until successful.

If round_robin is true, then all addresses are treated as equals. If a connection fails, the next address will be tried and if successful will remain connected until it fails.

Set the start type of the bridge. This controls how the bridge starts and can be one of three types: automatic, lazy and once. Note that RSMB provides a fourth start type "manual" which isn't currently supported by mosquitto.

automatic is the default start type and means that the bridge connection will be started automatically when the broker starts and also restarted after a short delay (30 seconds) if the connection fails.

Bridges using the lazy start type will be started automatically when the number of queued messages exceeds the number set with the threshold option. It will be stopped automatically after the time set by the idle_timeout parameter. Use this start type if you wish the connection to only be active when it is needed.

A bridge using the once start type will be started automatically when the broker starts but will not be restarted if the connection fails.

Set the number of messages that need to be queued for a bridge with lazy start type to be restarted. Defaults to 10 messages.

Define a topic pattern to be shared between the two brokers. Any topics matching the pattern (which may include wildcards) are shared. The pattern may be enclosed in double quotes in case it contains a space. The second parameter defines the direction that the messages will be shared in, so it is possible to import messages from a remote broker using in, export messages to a remote broker using out or share messages in both directions. If this parameter is not defined, the default of out is used. The QoS level defines the publish/subscribe QoS level used for this topic and defaults to 0.

The local-prefix and remote-prefix options allow topics to be remapped when publishing to and receiving from remote brokers. This allows a topic tree from the local broker to be inserted into the topic tree of the remote broker at an appropriate place.

For incoming topics, the bridge will prepend the pattern with the remote prefix and subscribe to the resulting topic on the remote broker. When a matching incoming message is received, the remote prefix will be removed from the topic and then the local prefix added.

For outgoing topics, the bridge will prepend the pattern with the local prefix and subscribe to the resulting topic on the local broker. When an outgoing message is processed, the local prefix will be removed from the topic then the remote prefix added.

When using topic mapping, an empty prefix can be defined using the place marker "". Using the empty marker for the topic itself is also valid. The table below defines what combination of empty or value is valid. The Full Local Topic and Full Remote Topic show the resulting topics that would be used on the local and remote ends of the bridge. For example, for the first table row if you publish to L/topic on the local broker, then the remote broker will receive a message on the topic R/topic.

To remap an entire topic tree, use e.g.:

topic # both 2 local/topic/ remote/topic/

This option can be specified multiple times per bridge.

Care must be taken to ensure that loops are not created with this option. If you are experiencing high CPU load from a broker, it is possible that you have a loop where each broker is forever forwarding each other the same messages.

See also the cleansession option if you have messages arriving on unexpected topics when using incoming topics.

connection test-mosquitto-org
address test.mosquitto.org
cleansession true
topic clients/total in 0 test/mosquitto/org/ $SYS/broker/

If try_private is set to true, the bridge will attempt to indicate to the remote broker that it is a bridge not an ordinary client. If successful, this means that loop detection will be more effective and that retained messages will be propagated correctly. Not all brokers support this feature so it may be necessary to set try_private to false if your bridge does not connect properly.

Defaults to true.

If you change bridge options in the configuration file, those configuration changes are applied during a bridge reconnection. The bridge_reload_type option determines when that reconnection happens, and can be set to either lazy or immediate.

lazy is the default, and means that any connected bridge will remain in its current state until a natural reconnection happens, at which point the new configuration will be used.

immediate forces a reconnection and so uses the new configuration straight away.