MOSQUITTO.CONF(5)

📦

version 2.1.2 · 13 versions

🦋 MOSQUITTO.CONF(5) — mosquitto.conf, the config file for mosquitto 🦋

Okay bestie, gather round, because this is the config file manual for mosquitto, and it is honestly a lot, but we’re gonna get through it together. No cap. 💅

💖 NAME 💖

mosquitto.conf — the configuration file for mosquitto.

📜 SYNOPSIS 📜

mosquitto.conf

🌸 DESCRIPTION 🌸

mosquitto.conf is the configuration file for mosquitto. It can live anywhere as long as mosquitto can read it. By default, mosquitto doesn’t even need a configuration file and will just use the default values listed below. See mosquitto(8) for info on how to load a configuration file. 🫶

Mosquitto can be told to reload the configuration file by sending a SIGHUP signal, as described in the Signals section of mosquitto(8). Not all configuration options can be reloaded, and the details are listed below under each option. ✨

🗂️ SECTIONS 🗂️

The rest of this man page is divided into the following sections:

File Format — a description of the configuration file syntax.
Authentication — a discussion of the authentication options available.
General Options — the general options for configuring Mosquitto.
Listeners — general options for configuring listeners, which are the ways that MQTT clients can connect to Mosquitto, as well as certificate and pre-shared-key based SSL/TLS options.
Configuring Bridges — general options for configuring bridges, which are a way of connecting multiple brokers together, as well as certificate and pre-shared-key based SSL/TLS options.
Other — The Files, Bugs, See Also sections.

📝 FILE FORMAT 📝

All lines with a # as the very first character are treated as a comment. Periodt.

Configuration lines start with a variable name. The variable value is separated from the name by a single space. That’s the whole vibe check. 🎀

🔐 AUTHENTICATION 🔐

The authentication options described below allow a wide range of possibilities when combined with the listener options. This section is here to clarify the possibilities. An overview is also available at https://mosquitto.org/documentation/authentication-methods/ ✨

The simplest option is to have no authentication at all. This is the default if no other options are given. Unauthenticated encrypted support is provided by using the certificate based SSL/TLS based options certfile and keyfile. 🦋

MQTT provides username/password authentication as part of the protocol. Use the password_file option to define the valid usernames and passwords. Be sure to use network encryption if you are using this option, otherwise the username and password will be vulnerable to interception. Use the per_listener_settings option to control whether passwords are required globally or on a per-listener basis. 💀

Mosquitto provides the Dynamic Security plugin, which handles username/password authentication and access control in a much more flexible way than a password file. See https://mosquitto.org/documentation/dynamic-security/ 👑

When using certificate based encryption there are three options that affect authentication. The first is require_certificate, which may be set to true or false. If false, the SSL/TLS component of the client will verify the server but there is no requirement for the client to provide anything for the server: authentication is limited to the MQTT built in username/password. If require_certificate is true, the client must provide a valid certificate in order to connect successfully. In this case, the second and third options, use_identity_as_username and use_subject_as_username, become relevant. If set to true, use_identity_as_username causes the Common Name (CN) from the client certificate to be used instead of the MQTT username for access control purposes. The password is not used because it is assumed that only authenticated clients have valid certificates. This means that any CA certificates you include in cafile or capath will be able to issue client certificates that are valid for connecting to your broker. If use_identity_as_username is false, the client must authenticate as normal (if required by password_file) through the MQTT options. The same principle applies for the use_subject_as_username option, but the entire certificate subject is used as the username instead of just the CN. 🧚

When using pre-shared-key based encryption through the psk_hint and psk_file options, the client must provide a valid identity and key in order to connect to the broker before any MQTT communication takes place. If use_identity_as_username is true, the PSK identity is used instead of the MQTT username for access control purposes. If use_identity_as_username is false, the client may still authenticate using the MQTT username/password if using the password_file option. 🔥

Both certificate and PSK based encryption are configured on a per-listener basis.

Authentication plugins can be created to augment the password_file, acl_file and psk_file options with e.g. SQL based lookups.

It is possible to support multiple authentication schemes at once. A config could be created that had a listener for all of the different encryption options described above and hence a large number of ways of authenticating. 💜

✨ GENERAL OPTIONS ✨

`acl_file` file path

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:

%c to match the client id of the client
%u to match the username of the client

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. 🫶

`allow_anonymous` [ true | false ]

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’s 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.

Important: In version 1.6.x and earlier, this option defaulted to true unless there was another security option set.

Reloaded on reload signal. 🌈

`allow_duplicate_messages` [ true | false ]

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 they have QoS=2. 🔥

Defaults to true.

This option applies globally.

Reloaded on reload signal. 🦋

`allow_zero_length_clientid` [ true | false ]

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. 👑

`auth_plugin_deny_special_chars` [ true | false ]

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. 💅

…that's the whole point of this check, bestie. It stops a shady user from sneaking past an ACL check by literally naming their username or client id after one of those characters. Same exact issue that got reported against mosquitto itself as CVE-2017-7650. 😭

So if you're absolutely sure the plugin you're running isn't vulnerable to that attack (like, you never ever use usernames or client ids inside topics), then you can turn this extra check off and let all your ACL checks go straight through to your plugin by setting this to false.

Defaults to true.

Applies to the current authentication plugin being configured.

Not currently reloaded on reload signal.

auto_id_prefix prefix — okay so this one is deprecated, please use listener_auto_id_prefix instead, girlie. If allow_zero_length_clientid is true, this lets you set a string that gets prefixed onto the automatically generated client ids so they're easier to spot 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, it applies to all listeners.

Reloaded on reload signal.

autosave_interval seconds — the number of seconds mosquitto waits between each time it saves the in-memory database to disk. If you set it to 0, the in-memory database is only saved when mosquitto exits or when it receives the SIGUSR1 signal. Heads up though: this setting only does anything if the built-in persistence is enabled. Defaults to 1800 seconds (that's 30 minutes, bestie 🕰️).

This option applies globally.

Reloaded on reload signal.

autosave_on_changes [ true | false ] — if true, mosquitto counts up the number of subscription changes, retained messages received and queued messages, and if that total exceeds autosave_interval it saves the in-memory database to disk. If false, mosquitto just treats autosave_interval as a time in seconds and saves accordingly.

Applies to built-in persistence only.

This option applies globally.

Reloaded on reload signal.

check_retain_source [ true | false ] — this one's for the scenario where a client subscribes to a topic that has retained messages 👀. It's genuinely possible that whoever published that retained message had access at the time they published, but that access has since been removed. If check_retain_source is true (the default), the source of a retained message gets its access rights checked before it's republished. When it's false, no check is made at all and the retained message will always be published. So like… choose wisely, no cap.

This option applies globally, regardless of the per_listener_settings option.

clientid_prefixes prefix — deprecated and getting removed in a future version, just so you know 💀. If defined, only clients whose clientid has a prefix matching clientid_prefixes are allowed to connect to the broker. For example, setting "secure-" here would mean a client "secure-client" could connect but another one 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.

connection_messages [ true | false ] — if true, the log gets entries whenever clients connect and disconnect. If false, those entries simply don't appear. Iconic for when your logs are doing the most.

This option applies globally.

Reloaded on reload signal.

enable_control_api [ true | false ] — if true, $CONTROL/broker/v1 gets enabled ✨. Right now that lets you interrogate which plugins are enabled, but in the future it'll let you configure general broker options too. 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. That part is not a vibe, it's a requirement.

This option applies globally.

Reloaded on reload signal.

global_max_clients count — the maximum number of client sessions allowed 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 one that has disconnected and still hasn't exceeded its session expiry interval (MQTT v5).

See also the max_connections setting, which applies to listeners. So if you set global_max_clients to 1000 and max_connections on a listener to 10, that means only 10 simultaneous connections are allowed at once, with an overall maximum of 1000 client sessions. Math slay 🧮.

This option applies globally.

Defaults to -1 (unlimited).

Reloaded on reload signal.

global_max_connections count — the maximum number of currently connected clients allowed 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.

global_plugin file path — loads an external module to extend broker features 🧩. This one loads plugins for use across all listeners, regardless of what per_listener_settings is set to. In every other way it functions the same as the plugin option.

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

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

include_dir dir — you can pull in external config files with include_dir! This defines a directory that gets searched for config files, and every file ending in .conf will be loaded as a configuration file. Best practice is to have this as the last option in the main file. This option will only be processed from the main configuration file, and the directory you specify must not contain the main configuration file.

The config 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. Yes, really, it's giving meticulous.

Example Load Order for include_dir. Given the files b.conf, A.conf, 01.conf, a.conf, B.conf, and 00.conf inside include_dir, the config files get loaded in this order:

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 they're written in the main configuration file.

Example Load Order for Multiple include_dir. Assuming a directory one.d containing files B.conf and C.conf, and a second directory two.d containing files A.conf and D.conf, and a config like:

include_dir one.d
include_dir two.d

Then the config files get loaded in this order:

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

log_dest destinations — sends 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. The 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, periodt.

The file destination needs an extra parameter, which is the file to log to, e.g. "log_dest file /var/log/mosquitto.log". That file gets 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 outputs to the logd daemon.

Use "log_dest none" if you want to disable logging entirely. 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.

log_facility local facility — if you're using syslog logging (not on Windows), messages get logged to the "daemon" facility by default. Use log_facility to pick 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.
log_timestamp [ true | false ] — boolean value; if set to true, a timestamp value gets added to each log entry. The default is true.

Reloaded on reload signal.

log_timestamp_format format — sets 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 that gets 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.

log_type types — chooses which 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 — same rules as before, bestie.

Reloaded on reload signal.

max_inflight_bytes count — outgoing QoS 1 and 2 messages are allowed to be in flight until this byte limit is reached. This lets you control your outgoing message rate based on message size rather than message count. So 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.

max_inflight_messages count — the maximum number of outgoing QoS 1 or 2 messages that can be mid-transmission at the same time, bestie. That count includes messages currently going through handshakes and messages that are being retried. Defaults to 20. Set it to 0 for no maximum at all. And if you set it to 1, that guarantees in-order delivery of messages — one at a time, queen behaviour. 👑

This option applies globally.

Reloaded on reload signal.

max_keepalive value — okay so for MQTT v5 clients it's possible to have the server send a "server keepalive" value that overrides the keepalive value the client set. The idea is: the server is basically saying "I'm gonna disconnect you earlier than you expected, so use this new keepalive value instead." The max_keepalive option lets you specify that clients may only connect with keepalive less than or equal to this value — otherwise they get 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's no mechanism to tell the client what keepalive value they should use. So if an MQTT v3.1.1 or v3.1 client specifies a keepalive time greater than max_keepalive, they'll be sent a CONNACK message with the "identifier rejected" reason code, and disconnected. rude but fair.

This option applies globally.

Reloaded on reload signal.

max_packet_size value — for MQTT v5 clients, the server can send a "maximum packet size" value telling 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 — so no sneaking big headers past it. 🕵️‍♀️ Setting this option to a positive value sets the maximum packet size to that number of bytes. If a client sends a packet larger than this value, it will be disconnected. This applies to all clients regardless of the protocol version they're 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's likely to interfere with normal client operation even with small payloads. like pls be serious.

This option applies globally.

Reloaded on reload signal.

max_queued_bytes count — the number of outgoing QoS 1 and 2 messages above those currently in-flight that will be queued (per client) by the broker. Once this limit has been reached, subsequent messages will be silently dropped 🙈 — no note, no goodbye, just gone. This is a hugely important option if you're 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.

max_queued_messages count — 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.

memory_limit limit — this one sets the maximum number of heap memory bytes that the broker will allocate, which means it's a hard limit on memory use by the broker. Memory requests that exceed this value get denied. What actually happens next depends on what got denied, and ngl it's a little dramatic:
- if an incoming message is being processed, the message is dropped and the publishing client gets disconnected;
- if an outgoing message is being sent, the individual message is dropped and the receiving client gets 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. just so you know 💅

message_size_limit limit — sets the maximum publish payload size that the broker will allow. Received messages that exceed this size will not be accepted by the broker. That means the message won't 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 all valid MQTT messages are accepted. MQTT imposes a maximum payload size of 268435455 bytes — that's the actual ceiling, not us being extra.

This option applies globally.

Reloaded on reload signal.

password_file file path — 📌 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 mosquitto_passwd(1). 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_file is 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.

per_listener_settings [ true | false ] — if true, then authentication and access control settings are 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
- plugin
- plugin_opt_*

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.

persistence [ true | false ] — if true, then built-in persistence is enabled. It is recommended that a plugin based persistence is used instead.

If enabled, connection, subscription and message data will be written to 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. lowkey smart honestly.

This option applies globally.

Reloaded on reload signal.

persistence_file file name — the filename to use for the built-in persistent database. Defaults to mosquitto.db.

This option applies globally.

Reloaded on reload signal.

persistence_location path — the path where plugins should store any persistence data, and the path where the built-in persistence will store its data. If not given, then the current directory is used.

This option applies globally.

Reloaded on reload signal.

persistent_client_expiration duration — this option lets the session of persistent clients (those with clean session set to false) that are not currently connected be removed if they don't 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. That leads to persistent clients that connect once and never reconnect — ghost sessions haunting your broker fr. 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:

persistent_client_expiration 2m
persistent_client_expiration 14d
persistent_client_expiration 1y

...and like, yeah, you can put the expiration time in seconds, but that is not me telling you to go pick something tiny, bestie. 🫠 If you're sitting there thinking "wow my clients should all be auto-expired in like a really short time," the move is to go fix the clients, not to crank this down. Fr fr.

And because this is a non-standard option, if you don't set it at all, the default is that persistent clients never expire. Periodt.

This option applies globally.

Reloaded on reload signal. ✨

pid_file file path — writes a pid file to the path you give it. If you don't give one (that's the default), no pid file gets written at all. And if mosquitto can't write the pid file? It just exits. 💀

If mosquitto is being started automatically by an init script, you'll usually need a pid file, so set it to something like /var/run/mosquitto/mosquitto.pid.

Not reloaded on reload signal.

plugin_opt_* value — options that get passed to the most recent plugin defined in the config file. Go read that specific plugin's instructions to find out which options it actually takes. 🔌

Applies to the current plugin/global_plugin being configured.

It also exists as the auth_opt_* option, but that use is deprecated and will be removed in a future version. (iykyk, use the new one 🎀)

plugin file path — points at an external module to use for authentication, access control, and other features. This is the whole vibe for making custom username/password checks, custom access control functions, and modifying other behaviour. 👑

You can specify it multiple times to load multiple plugins, and they get processed in the order you list them.

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

Not currently reloaded on reload signal.

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

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

This one's also available as the auth_plugin option, but that use is deprecated and will be removed in a future version. 🙈

psk_file file path — sets the path to a pre-shared-key file. This option needs a listener that has PSK support enabled. If you define it, the file's contents control client access to the broker. Every line should be in the format "identity:key", where the key is a hexadecimal string with no leading "0x". A client connecting to a PSK-enabled listener has to hand over a matching identity and PSK before the encrypted connection can proceed. 🔐

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

Reloaded on reload signal ✨ — the currently loaded identity and key data gets freed and reloaded. Clients that are already connected are unaffected. 🫶

queue_qos0_messages [ true | false ] — set to true to queue messages with QoS 0 when a persistent client is disconnected. When bridge topics are configured with QoS level 1 or 2, incoming QoS 0 messages for those topics get queued too. These messages count toward the limit set by max_queued_messages. Defaults to false.

Heads up though: the MQTT v3.1.1 spec says 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.

retain_available [ true | false ] — if you set it to false, retained messages aren't supported at all. Clients that send a message with the retain bit get disconnected when this is false. Defaults to true. 😭

This option applies globally.

Reloaded on reload signal.

retain_expiry_interval minutes — so mosquitto's default behaviour is to remove retained messages that have hit their message-expiry-interval property the next time that message gets accessed — either because it got replaced by a new message, or on the next subscription that matches it. But if you've got a pattern of publishing loads of retained messages with a message-expiry-interval and nobody ever subscribes to them, those expired retained messages just... sit in memory. 🧠💀 This option configures the broker to periodically check the retained tree for expired messages.

Defaults to off. Setting it to a value greater than zero means the broker checks at an interval of that many minutes.

This option applies globally.

Reloaded on reload signal.

set_tcp_nodelay [ true | false ] — if true, the TCP_NODELAY option gets set on client sockets, which disables Nagle's algorithm. Effect: lower latency for some messages, at the potential cost of sending more TCP packets. Defaults to false. ⚡

This option applies globally.

Reloaded on reload signal.

sys_interval seconds — the integer number of seconds between updates of the $SYS subscription hierarchy, which hands out status info about the broker. If you don't set it, it defaults to 10 seconds.

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

This option applies globally.

Reloaded on reload signal.

upgrade_outgoing_qos [ true | false ] — okay so the MQTT spec says the QoS of a message delivered to a subscriber must never get upgraded to match the QoS of the subscription. Turning this on changes that behaviour. If upgrade_outgoing_qos is true, messages sent to a subscriber will always match the QoS of its subscription. This is a non-standard option that the spec doesn't provide for. Defaults to false. 👑

This option applies globally.

Reloaded on reload signal.

user username — when run as root, change to this user and its primary group on startup. If it's set to "mosquitto" or left unset, and the "mosquitto" user doesn't exist, then mosquitto switches to the "nobody" user instead. If it's set to some other value and mosquitto can't change to that user and group, it exits with an error. The user you specify must have read/write access to the persistence database if that database is going to be written. If you're running as a non-root user, this setting does nothing. Defaults to mosquitto. 🌸

This setting has no effect on Windows, so on Windows you should just run mosquitto as the user you want it running as.

Not reloaded on reload signal.

🎧 LISTENERS 🎧

The network ports mosquitto listens on are controlled with listeners, bestie. You can override the default listener's options and spin up extra listeners too. 💅

General Options

accept_protocol_versions versions — which protocol versions get accepted. This sets what versions of the MQTT protocol will be accepted on this listener. It can be any combination of 3, 4, 5 in a comma separated list, like:

# Allow v5.0 only:
listener 1883
accept_protocol_versions 5

# Allow v3.1 and v3.1.1:
listener 1884
accept_protocol_versions 3, 4

Defaults to allowing all versions. 🌈

Reloaded on reload signal.

bind_address address — this option is deprecated and will be removed in a future version. Use the listener instead. 🚩

Listens for incoming network connections on the specified IP address/hostname only. Super useful for restricting access to certain network interfaces. To restrict access to mosquitto to the local host only, use "bind_address localhost". This one only applies to the default listener — use the listener option to control other listeners.

It's recommended to use an explicit listener rather than relying on implicit default listener options like this.

Not reloaded on reload signal.

bind_interface device — listens for incoming network connections only on the specified interface. Similar to bind_address, but this one's the move when an interface has multiple addresses or the address might change. 🔌

If it's used at the same time as bind_address for the default listener, or the bind address/host part of the listener, then bind_interface takes priority.

This option isn't available on Windows and AIX. 🙅

Not reloaded on reload signal.

enable_proxy_protocol [ 2 | 1 ] — enables PROXY protocol support for this listener. Versions 1 and 2 are supported, and if you have the choice then version 2 is the recommended one because it gives you access to TLS information and supports Unix sockets. 💖

This option requires a load balancer/proxy such as HAProxy sitting in front of Mosquitto, with that proxy configured to use the PROXY protocol.

The PROXY protocol is how information about client socket connections gets sent from the proxy to the broker. Without it, the connection info and logs in the broker contain the IP address and port of the proxy itself instead of the client's. 😬

Only enable this when a trusted proxy sits in front of Mosquitto and no other external access to Mosquitto is possible. Giving external access to a listener with this option enabled is a security risk, especially if you're using client certificates on the proxy.

When using PROXY version 2, this option can be used with TLS termination on the proxy. In that case, TLS information gets passed to the broker as well. Use proxy_protocol_v2_require_tls to reject clients that don't use TLS — that one's strongly recommended. Enabling require_certificate on the listener makes the broker check the TLS information provided to make sure the client gave a valid certificate. Enabling use_identity_as_username as well means the commonName value from the certificate gets used as the client username instead of whatever was in the CONNECT packet. In both cases, the listener must not have TLS configured. 🎀

You can't use the use_subject_as_username, certfile, or keyfile options together with enable_proxy_protocol. 🚫

Not reloaded on reload signal.

http_dir directory — when a listener is using the http_api protocol, it's possible to serve http data as well. Set http_dir to a directory containing the files you want to serve. If you don't specify this option, then no normal http connections are possible at all. 🌐

This option is also available for websockets listeners if Mosquitto is compiled with websockets support provided by libwebsockets. Heads up though — this is not the default, and it's getting yeeted in version 3.0. 💀

Not reloaded on reload signal.

listener port [bind address/host/unix socket path] — ok so this is the big one: listen for incoming network connections on the port you give it. The second argument is optional and it lets you bind that listener to a specific ip address/hostname. ⚡ Little plot twist: if you use this variable and you're not using the global bind_address or port options, then the default listener will not be started at all.

The bind address/host thing is how you pin a listener to a specific IP — just pass an IP address or a hostname. For websockets listeners though, it's only possible to pass an IP address here, no hostnames, sorry bestie. 🫶

On systems that support Unix Domain Sockets, you can also use this option to create a Unix socket instead of opening a TCP socket. In that case the port must be set to 0, and you gotta give the unix socket path.

This option may be specified multiple times. See also the mount_point option, they're besties.

Not reloaded on reload signal.

listener_allow_anonymous [ true | false ] — a boolean that decides whether clients connecting without a username are allowed to connect to this specific listener. If you set it, it overrides whatever allow_anonymous says. If you set it to false then you need another means of connection to control authenticated client access. 🔐

If you don't set it explicitly, the value from allow_anonymous will be used.

Not reloaded on reload signal.

auto_id_prefix prefix — sets a string that gets prefixed onto the automatically generated client ids (i.e. when a client connects without providing a client id) so they're easier to spot in logs. Defaults to auto-. ✨

Not reloaded on reload signal.

max_connections count — caps the total number of clients connected for the current listener. Set it to -1 for "unlimited" connections (the air quotes are doing a lot of work there 😭). Note that other limits may be imposed that are outside the control of mosquitto — see e.g. limits.conf(). That's not us, that's your system.

Not reloaded on reload signal.

max_qos value — limits the QoS value allowed for clients connecting to this listener. Defaults to 2, which means any QoS can be used. Set it to 0 or 1 to limit to those QoS values. This uses an MQTT v5 feature to notify clients of the limitation — but MQTT v3.1.1 clients will not be aware of it. 💀 Clients publishing to this listener with a too-high QoS will be disconnected, no negotiation, periodt.

Not reloaded on reload signal.

max_topic_alias_broker number — when publishing to MQTT v5 clients, mosquitto can create topic aliases on a first come first serve basis — i.e. the topics that are published to a client first get aliases created for them. This option controls the number of aliases per client. It applies per listener.

Ngl, this behaviour is not guaranteed to remain the same. Future versions might introduce mechanisms for controlling which topics receive aliases. So don't build your whole personality on it. 🦋

This option sets the maximum number of topic aliases that mosquitto will create for an MQTT v5 client, even if the client allows more.

For example, if the client sets topic-alias-maximum to 100 and this option is set to 10, the broker will create at most 10 topic aliases. Likewise, if the client sets topic-alias-maximum to 20 and this option is set to 100, then the broker will create at most 20 topic aliases. Math! 🧮

Defaults to 10. Maximum of 65535. Set to 0 to disable broker-to-client topic aliases completely.

Not reloaded on reload signal.

max_topic_alias number — sets the maximum number of topic aliases that an MQTT v5 client is allowed to create. Applies per listener. Defaults to 10. Set to 0 to disallow topic aliases from clients entirely. The maximum value possible is 65535. 🔥

Not reloaded on reload signal.

mount_point topic prefix — used with the listener option to isolate groups of clients. When a client connects to a listener that uses this option, the string argument gets attached to the start of all topics for that client. The prefix is removed when any messages are sent to the client. So a client connected to a listener with mount point example can only see messages published in the topic hierarchy example and below. Cute little bubble, honestly. 🫧

Not reloaded on reload signal.

port port number — ⚠️ this option is deprecated and will be removed in a future version. Use the listener instead.

Sets the network port for the default listener to listen on. Defaults to 1883.

Not reloaded on reload signal.

It is recommended to use an explicit listener rather than rely on the implicit default listener options like this. Like, genuinely bestie, just use listener. 🙈

protocol value — sets the protocol to accept for the current listener. Can be mqtt, the default, websockets, or http_api.
- mqtt: the standard MQTT listener. the classic. the icon. 👑
- websockets: MQTT tunnelled over WebSockets. If the legacy websockets support using libwebsockets is used, then only a reduced TLS feature set is available — namely cafile, certfile, keyfile, ciphers, and ciphers_tls1.3. That's the whole menu, sorry.
- http_api: this starts the listener as a very simple webserver (see the http_dir option) that can also serve some HTTP API requests. TLS is supported for this listener, however only the certfile and keyfile options are allowed. Authentication is not currently possible — to use this listener it is strongly recommended to bind the listener to the loopback interface and then configure a reverse proxy with the appropriate encryption and authentication. 🚨 Do not skip that part fr fr.

Not reloaded on reload signal.

proxy_protocol_v2_require_tls [ true | false ] — when a listener is using the PROXY protocol, this can require that the client connection is using TLS. If set to true, then the PROXY protocol header must contain a TLS indicator. If it doesn't, the connection gets closed. Defaults to false. 🔒

Not reloaded on reload signal.

socket_domain [ ipv4 | ipv6 ] — by default a listener will attempt to listen on all supported IP protocol versions. If you don't have an IPv4 or IPv6 interface, you may want to disable support for either of those protocol versions. In particular, note that due to the limitations of the websockets library, it will only ever attempt to open IPv6 sockets if IPv6 support is compiled in — and so it will fail if IPv6 is not available. 💀

Set to ipv4 to force the listener to only use IPv4, or ipv6 to force it to only use IPv6. If you want support for both IPv4 and IPv6, then do not use the socket_domain option at all. Just vibe.

Not reloaded on reload signal.

use_username_as_clientid [ true | false ] — set this to true to replace the clientid that a client connected with, with its username. This lets authentication be tied to the clientid, which means it's possible to prevent one client disconnecting another by using the same clientid. Defaults to false.

If a client connects with no username it will be disconnected as not authorised when this option is set to true. Do not use in conjunction with clientid_prefixes. 🚫

This does not apply globally — it's on a per-listener basis.

🎀 Certificate based SSL/TLS Support 🎀

The following options are available for all listeners to configure certificate based SSL support. See also "Pre-shared-key based SSL/TLS support". 🔐

cafile file path — defines the path to a file containing the PEM encoded CA certificates that are trusted when checking incoming client certificates. 📜
capath directory path — defines a directory that contains PEM encoded CA certificates that are trusted when checking incoming client certificates. For capath to work correctly, the certificate files must have ".pem" as the file ending, and you must run openssl rehash <path to capath> each and every time you add/remove a certificate. Yes, every time. 😭

capath is not supported for websockets. 🚫

certfile file path — path to the PEM encoded server certificate. This option and keyfile must both be present to enable certificate based TLS encryption. 🔒

The certificate pointed to by this option will be reloaded when mosquitto receives a SIGHUP signal. This is how you load new certificates before the existing ones expire — very main character prep energy. ⭐

ciphers cipher:list — the list of allowed ciphers for this listener, for TLS v1.2 and earlier only, each separated with a colon. Available ciphers can be obtained using the openssl ciphers command. 💅
ciphers_tls1.3 cipher:list — the list of allowed ciphersuites for this listener, for TLS v1.3, each separated with a colon. ✨
crlfile file path — okay so if you've got require_certificate set to true, you can also make a certificate revocation list file to literally revoke access for specific client certs 🚫💅. If you've done that, point crlfile at the PEM encoded revocation file, done.
dhparamfile file path — if you wanna allow ephemeral DH key exchange (which is the whole "forward security" serve ✨), the listener has to load DH parameters. That's what this option is for, bestie. And you can generate that file like this:

openssl dhparam -out dhparam.pem 2048

disable_client_cert_date_checks [ true | false ] — set this to true and it flips the certificate verification behaviour so that client certificates which are expired or not yet valid are still allowed — but only when you're using require_certificate true 🙈.

Defaults to false

keyfile file path — if tls_keyform equals "pem", this is the path to the PEM encoded server key. This option and certfile must both be present to enable certificate based TLS encryption 🔐. If tls_keyform is "engine", this instead represents the engine handle of the private key.

The private key pointed to by this option gets reloaded when Mosquitto receives a SIGHUP signal — which is lowkey iconic because it means you can load new keys before the existing ones expire 👑

require_certificate [ true | false ] — ngl by default an SSL/TLS enabled listener works kinda like a https enabled web server: server has a certificate signed by a CA, client verifies it's trusted, and the overall goal is encryption of the network traffic 🌸. But set require_certificate to true and now a client connecting to this listener must provide a valid certificate for the network connection to even proceed. Which means you can control access to the broker outside of the mechanisms MQTT itself provides. main character security energy fr 💅
tls_engine engine — a valid openssl engine id. You can list them with the openssl engine command 🧚
tls_engine_kpass_sha1 engine_kpass_sha1 — the SHA1 of the private key password when you're using a TLS engine. Some TLS engines, like the TPM engine, may need a password to be accessed. This option lets you hand over a hex encoded SHA1 hash of the password to the engine directly, instead of making the user get prompted for it 🙅‍♀️
tls_keyform [ pem | engine ] — specifies the type of private key in use when making TLS connections. Can be "pem" or "engine". This one is useful when a TPM module is being used and the private key was created with it ✨. Defaults to "pem", which means normal private key files are used.
tls_version version — configures the minimum version of the TLS protocol used for this listener. Possible values are tlsv1.3 and tlsv1.2. If you leave it unset, the default is to allow TLS v1.3 and v1.2 🎀

Heads up though — in Mosquitto version 1.6.x and earlier, this option set the only TLS protocol version that was allowed, rather than the minimum. Different vibe, same name, don't get caught out 💀

use_identity_as_username [ true | false ] — if require_certificate is true, you can set this to true and use the CN value from the client certificate as the username 🫶. When it's true, the password_file option will not be used for this listener.

This one takes priority over use_subject_as_username if both are set to true.

💜 Pre-shared-key based SSL/TLS Support 💜

Okay bestie, the following options are available for all listeners to configure pre-shared-key based SSL support. See also "Certificate based SSL/TLS support" 👀

ciphers cipher:list — when using PSK, the encryption ciphers used get chosen from the list of available PSK ciphers. If you wanna control which ciphers are available, this is your option 🎀. You can get the list of available ciphers with the "openssl ciphers" command, and you should provide them in the same format as that command's output.
psk_hint hint — the psk_hint option enables pre-shared-key support for this listener and also acts as an identifier for it ✨. The hint is sent to clients and may be used locally to aid authentication. It's a free form string with not much meaning in itself, so feel free to be creative, go off, be unhinged 🌈

If you provide this option, see psk_file to define the pre-shared keys to be used, or create a security plugin to handle them.

tls_version version — configures the minimum version of the TLS protocol used for this listener. Possible values are tlsv1.3 and tlsv1.2. Unset means the default of allowing TLS v1.3 and v1.2 🦋

Same lore as before: in Mosquitto version 1.6.x and earlier, this option set the only TLS protocol version that was allowed, rather than the minimum.

use_identity_as_username [ true | false ] — set this to have the psk identity sent by the client used as its username 💅. The username gets checked as normal, so password_file or another means of authentication checking must be used. No password will be used.

🌈 CONFIGURING BRIDGES 🌈

Multiple bridges (aka connections to other brokers) can be configured using the following variables, bestie 🫶

Reloaded on reload signal.

address address[:port] [address[:port]], addresses address[:port] [address[:port]] — specify the address and optionally the port of the bridge to connect to. This must be given for each bridge connection, no skipping 🙅‍♀️. If the port isn't specified, the default of 1883 is used.

If you're using an IPv6 address, then the port is not optional, periodt.

You can specify multiple host addresses on the address config — see the round_robin option for more details on how bridges behave with multiple addresses ✨

bridge_attempt_unsubscribe [ true | false ] — so if a bridge has topics with "out" direction, the default behaviour is to send an unsubscribe request to the remote broker for that topic. Which means changing a topic direction from "in" to "out" won't keep receiving incoming messages. But sending these unsubscribe requests isn't always the vibe you want, so setting bridge_attempt_unsubscribe to false disables sending the unsubscribe request. Defaults to true.
bridge_bind_address ip address — if you need the bridge to 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 🧚
bridge_max_packet_size value — if you wanna restrict the size of messages sent to a remote bridge, this is the one 💅. It sets the maximum number of bytes for the total message, headers and payload included. Note that MQTT v5 brokers may provide their own maximum-packet-size property — in that case, the smaller of the two limits gets used. Set to 0 for "unlimited".
bridge_max_topic_alias value — if the bridge is using MQTT v5, this option sets the maximum number of topic aliases the bridge will let the remote broker configure. Defaults to 10, maximum of 65535. Set to 0 to disable incoming topic aliases completely 🎀
bridge_outgoing_retain [ true | false ] — some MQTT brokers just don't allow retained messages, and that's their business 😭. MQTT v5 gives brokers a way to tell clients they don't support retained messages, but that's not possible for MQTT v3.1.1 or v3.1. So if you need to bridge to a v3.1.1 or v3.1 broker that doesn't support retained messages, set bridge_outgoing_retain to false. This removes the retain bit on all outgoing messages to that bridge, regardless of any other setting. Defaults to true.
bridge_protocol_version version — sets the version of the MQTT protocol to use for this bridge. Can be one of mqttv50, mqttv311 or mqttv31. Defaults to mqttv311.
bridge_receive_maximum count — if the bridge is using MQTT v5.0, use bridge_receive_maximum to limit the number of 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.
bridge_session_expiry_interval interval — if the bridge is using MQTT v5.0, 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.
bridge_tcp_keepalive idle interval counter — sets TCP keepalive parameters for this bridge connection. Use this to allow a long MQTT keepalive value while 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.

bridge_tcp_user_timeout timeout — 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 the Linux tcp man page). The default time is related to tcp_retries2. Reducing this value helps detect 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.

cleansession [ true | false ] — sets the clean session option for this bridge. Setting it to false (the default) means all subscriptions on the remote broker are kept in case the network connection drops 🫶. If set to true, all subscriptions and messages on the remote broker get cleaned up if the connection drops. Note that setting it to true may cause a large amount of retained messages to be sent each time the bridge reconnects — so like, be aware, bestie 💀

okay so if your bridge has cleansession set to false (which is the default, bestie), you may get unexpected behaviour from incoming topics if you change what topics you're subscribing to. this is because the remote broker keeps the subscription for the old topic — lowkey clingy. if you have this problem, connect your bridge with cleansession set to true, then reconnect with cleansession set to false as normal. slay. 💅

local_cleansession [ true | false] — the regular cleansession covers both the local subscriptions and the remote subscriptions. local_cleansession lets you split this. setting it to false means the local connection will preserve subscription, independent of the remote connection. defaults to the value of bridge.cleansession unless explicitly specified. periodt.
connection name — this variable marks the start of a new bridge connection. it also gives the bridge a name, and that name is used as the client id on the remote broker. ✨
keepalive_interval seconds — 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. 🫶
idle_timeout seconds — set the amount of time a bridge using the lazy start type must be idle before it will be stopped. defaults to 60 seconds.
local_clientid id — 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. no cap, this one matters. 😭
local_password password — 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.
local_username username — 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.
notifications [ true | false ] — 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. <highkey>obsessed with LWT</highkey>. 🎀
notifications_local_only [ true | false ] — if set to true, only publish notification messages to the local broker giving information about the state of the bridge connection. defaults to false.
notification_topic topic — 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.
remote_clientid id — 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.
remote_password value — 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.
remote_username name — 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.
restart_timeout base cap [stable], restart_timeout constant — 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. ngl, the jitter is doing a lot. 💜

round_robin [ true | false ] — 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. vibe check: main-character address vs all-addresses-equal. 🌈
start_type [ automatic | lazy | once ] — 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. automatic has main character energy, fr fr. 👑
threshold count — set the number of messages that need to be queued for a bridge with lazy start type to be restarted. defaults to 10 messages.
topic pattern [[[ out | in | both ] qos-level] local-prefix remote-prefix] — 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. the prefix remapping ate, no crumbs. 🦋

Okay so picture this: you're doing topic mapping, and you want an empty prefix. You write it as the place marker "" — that's your little void token, bestie. Using the empty marker for the topic itself is also totally valid. The table below defines what combination of empty or value is valid — I'm giving it to you row by row because tables are so not the vibe here. 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.

Pattern pattern, Local Prefix L/, Remote Prefix R/ → valid ✨ Full Local Topic L/pattern, Full Remote Topic R/pattern
Pattern pattern, Local Prefix L/, Remote Prefix "" → valid ✨ Full Local Topic L/pattern, Full Remote Topic pattern
Pattern pattern, Local Prefix "", Remote Prefix R/ → valid ✨ Full Local Topic pattern, Full Remote Topic R/pattern
Pattern pattern, Local Prefix "", Remote Prefix "" → valid (no remapping) ✨ Full Local Topic pattern, Full Remote Topic pattern
Pattern "", Local Prefix local, Remote Prefix remote → valid (remap single local topic to remote) ✨ Full Local Topic local, Full Remote Topic remote
Pattern "", Local Prefix local, Remote Prefix "" → invalid 💀
Pattern "", Local Prefix "", Remote Prefix remote → invalid 💀
Pattern "", Local Prefix "", Remote Prefix "" → invalid 💀

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. Stack 'em up, queen. 👑

⚠️ 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.

Lowkey the most iconic fail state: two brokers screaming the same message at each other until the heat death of the universe. 😭 Don't do that.

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

Example Bridge Topic Remapping. The configuration below connects a bridge to the broker at test.mosquitto.org. It subscribes to the remote topic $SYS/broker/clients/total and republishes the messages received to the local topic test/mosquitto/org/clients/total

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

try_private [ true | false ] — 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.
bridge_reload_type [ lazy | immediate ] — 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. No waiting era. ⚡

🌸 SSL/TLS Support 🌸

The following options are available for all bridges to configure SSL/TLS support. Lock it down, bestie. 🔒

bridge_alpn alpn — configure the application layer protocol negotiation option for the TLS session. Useful for brokers that support both websockets and MQTT on the same port.
bridge_cafile file path — at least one of bridge_cafile, bridge_capath, or bridge_tls_use_os_certs must be provided to allow SSL/TLS support, so like, pick one. 💅

bridge_cafile is used to define the path to a file containing the PEM encoded CA certificates that have signed the certificate for the remote broker.

bridge_capath file path — at least one of bridge_cafile, bridge_capath, or bridge_tls_use_os_certs must be provided to allow SSL/TLS support.

bridge_capath is used to define the path to a directory containing the PEM encoded CA certificates that have signed the certificate for the remote broker. For bridge_capath to work correctly, the certificate files must have ".crt" as the file ending and you must run "openssl rehash <path to bridge_capath>" each time you add/remove a certificate. Yes, every single time. Annoying? Yes. Necessary? Also yes. 🫠

bridge_certfile file path — path to the PEM encoded client certificate for this bridge, if required by the remote broker.
bridge_identity identity — pre-shared-key encryption provides an alternative to certificate based encryption. A bridge can be configured to use PSK with the bridge_identity and bridge_psk options. This is the client identity used with PSK encryption. Only one of certificate and PSK based encryption can be used on one bridge at once. Pick a lane. 🎀
bridge_insecure [ true | false ] — when using certificate based TLS, the bridge will attempt to verify the hostname provided in the remote certificate matches the host/address being connected to. This may cause problems in testing scenarios, so bridge_insecure may be set to true to disable the hostname verification.

💀 Setting this option to true means that a malicious third party could potentially impersonate your server, so it should always be set to false in production environments. Fr fr, do not ship this to prod.

bridge_keyfile file path — path to the PEM encoded private key for this bridge, if required by the remote broker.
bridge_psk key — pre-shared-key encryption provides an alternative to certificate based encryption. A bridge can be configured to use PSK with the bridge_identity and bridge_psk options. This is the pre-shared-key in hexadecimal format with no "0x". Only one of certificate and PSK based encryption can be used on one bridge at once.
bridge_require_ocsp [ true | false ] — when set to true, the bridge requires OCSP on the TLS connection it opens as client.
bridge_tls_use_os_certs [ true | false ] — at least one of bridge_cafile, bridge_capath, or bridge_tls_use_os_certs must be provided to allow SSL/TLS support.

Set bridge_tls_use_os_certs to true to enable TLS for this bridge, and to configure it to trust the default certificates provided by openssl. This is typically a large number of certificates. Defaults to false.

bridge_tls_version version — configure the version of the TLS protocol to be used for this bridge. Possible values are tlsv1.3 and tlsv1.2. Defaults to tlsv1.2. The remote broker must support the same version of TLS for the connection to succeed. Both ends or it's a no. 🤝
bridge_ciphers cipher:list — the list of allowed ciphers for this bridge, for TLS v1.2 and earlier only, each separated with a colon. Available ciphers can be obtained using the "openssl ciphers" command.
bridge_ciphers_tls1.3 cipher:list — the list of allowed ciphersuites for this bridge, for TLS v1.3, each separated with a colon.

🎀 FILES 🎀

mosquitto.conf

🐛 BUGS 🐛

mosquitto bug information can be found at https://github.com/eclipse-mosquitto/mosquitto/issues — go report it, bestie, they're actually nice about it.

💖 AUTHOR 💖

Roger Light <roger@atchoo.org>

And that's the whole page, bestie!! 🎉 This finale was brought to you by the Mosquitto Project, dated 02/09/2026, and filed under MOSQUITTO.CONF(5). Go forth and bridge responsibly. 🦋✨

📦 where this page comes from

alpine 3.24: mosquitto-doc 2.1.2-r1 · EPL-1.0 OR EPL-2.0
fedora 44: mosquitto 2.1.2-1.fc44 · EPL-2.0
fedora 44: mosquitto 2.1.2-1.fc44 · EPL-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

MOSQUITTO.CONF(5)

🦋 MOSQUITTO.CONF(5) — mosquitto.conf, the config file for mosquitto 🦋

💖 NAME 💖

📜 SYNOPSIS 📜

🌸 DESCRIPTION 🌸

🗂️ SECTIONS 🗂️

📝 FILE FORMAT 📝

🔐 AUTHENTICATION 🔐

✨ GENERAL OPTIONS ✨

acl_file file path

allow_anonymous [ true | false ]

allow_duplicate_messages [ true | false ]

allow_zero_length_clientid [ true | false ]

auth_plugin_deny_special_chars [ true | false ]

🎧 LISTENERS 🎧

General Options

🎀 Certificate based SSL/TLS Support 🎀

💜 Pre-shared-key based SSL/TLS Support 💜

🌈 CONFIGURING BRIDGES 🌈

🌸 SSL/TLS Support 🌸

🎀 FILES 🎀

🐛 BUGS 🐛

👀 SEE ALSO 👀

💖 AUTHOR 💖

`acl_file` file path

`allow_anonymous` [ true | false ]

`allow_duplicate_messages` [ true | false ]

`allow_zero_length_clientid` [ true | false ]

`auth_plugin_deny_special_chars` [ true | false ]