Mosquitto 2.0 introduces a number of changes to the behaviour of the broker which new users need to be aware of, and which this document explains.
If you are packaging Mosquitto for distribution, see the Packaging and Distribution section.
If you are a plugin author, see the Plugins section.
Listener behaviour changes
The way in which Mosquitto configures listeners has been changed to help encourage end users to take an informed choice about security, rather than just relying on the previously very forgiving defaults.
Listener without configuration
When Mosquitto is run without a configuration file, or without configuring any listeners, it will now bind to the loopback interfaces 127.0.0.1 and/or ::1. This means that only connections from the local host will be possible. This mode allows automated or manual testing on a local machine without the need for a configuration file. In this mode only, anonymous/unauthenticated users are allowed by default.
This applies to you if you run your broker in a similar way to one of these examples:
mosquitto -p 1883.
If you use this mode and wish to have clients connect from a remote machine, then you will need to use a configuration file:
listener 1883 # Note that this will not allow anonymous access by default.
This configuration binds the listener for port 1883 to the
interface by default, i.e. allows connections on all interfaces. It is still
possible to bind to a specific interface manually, e.g.
Authentication requires configuration
All listeners now require authentication to be configured. This is with the exception of the case where no listener configuration is provided and hence the listener is bound to the loopback interface, as described above.
This means that
allow_anonymous now defaults to false. If you currently have
a broker running that has a listener configured in the configuration file, but
has no other authentication configured and no explicit
setting, then your clients will be unable to connect after upgrading to
There are three choices :
- Configure the in-built
acl_fileoptions for authentication.
- Use an authentication plugin, such as the new dynamic-security plugin, or the third party mosquitto-go-auth plugin.
allow_anonymous true- this should be done only if you have a specific need for unauthenticated clients.
Listener TLS protocol version changes
tls_version option now defines the minimum TLS protocol version to
be used, rather than the exact version. For example, setting
tlsv1.2 would allow both TLS v1.2 and TLS v1.3.
Support for TLS v1.0 has been disabled.
Mixing configuration files with -p
If you configure a listener in your configuration file and use e.g.
on the command line at the same time, you will need to add all listeners to the
configuration file because this behaviour is no longer supported - the port
provided on the command line will be ignored.
If you have a configuration file like this:
listener 1883 # ...
And run Mosquitto like this:
mosquitto -c mosquitto.conf -p 1884
Then you should instead run Mosquitto as
mosquitto -c mosquitto.conf, and use
a configuration file with both listeners in:
listener 1883 # ... listener 1884 # ...
Use of root/privileged user
In versions prior to 2.0, if Mosquitto was run as root it would load TLS certificates, start listeners, and start logging, before dropping to the unprivileged mosquitto user.
This behaviour has changed. In 2.0, Mosquitto load the configuration file and
immediately drop to the configured unprivileged user, which defaults to
mosquitto. If the
mosquitto or manually configured user is not available,
the broker will attempt to drop to the
This means that the only files Mosquitto will access as root are the configuration files, and hence any other files that Mosquitto needs to access or write must be accessible by the unprivileged user.
In particular those people using TLS certificates from Lets Encrypt will need to do something to allow Mosquitto to access those certificates. An example deploy renewal hook script to help with this is at misc/letsencrypt/mosquitto-copy.sh.
It is still possible to force Mosquitto to run as root, but this is strongly recommended against.
pid_file option will now always attempt to write a pid file,
regardless of whether the
-d argument is used when running the broker.
max_queued_messages option has been increased from 100 to 1000 by
default, and now also applies to QoS 0 messages, when a client is connected.
Packaging and Distribution
The components that Mosquitto provides can be categorised as follows:
C/C++ libraries for creating MQTT clients.
General purpose command line MQTT clients. These depend upon libmosquitto.so.1.
The main offering of the project, the Mosquitto broker, plus associated utilities and plugins.
- The mosquitto_passwd utility has changed location.
- The mosquitto_ctrl utility has been added.
- The mosquitto_dynamic_security plugin has been added, this is a Mosquitto specific shared library.
- The mosquitto_ctrl utility requires libmosquitto.so.1.
- Plugin developers would expect to have the header files from libmosquitto available, as well as those from the broker.
mosquitto_ctrl and mosquitto_dynamic_secuity.so require the cJSON library. If it is not detected or desired, those features can be disabled.
Mosquitto 2.0 introduces a new plugin interface which should be simpler to
develop for, and is more easily extendable. A separate document will describe
the new plugin interface. If you have an existing plugin that followed the
mosquitto_plugin.h, then it will continue to work with
Mosquitto 2.0 unless it is compiled using the Mosquitto 2.0 header files,
which contained a mistake in the documentation.
To modify your plugin so that it will work on both of Mosquitto 1.6 and
Mosquitto 2.0, you should change your instance of
mosquitto_auth_plugin_version so that it returns the version of the plugin
interface that you support, i.e.