Introduction

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
  • 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 0.0.0.0 or :: interface by default, i.e. allows connections on all interfaces. It is still possible to bind to a specific interface manually, e.g. listener 1883 192.168.1.1.

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 allow_anonymous setting, then your clients will be unable to connect after upgrading to Mosquitto 2.0.

There are three choices :

  • Configure the in-built password_file and acl_file options for authentication.
  • Use an authentication plugin, such as the new dynamic-security plugin, or the third party mosquitto-go-auth plugin.
  • Set allow_anonymous true - this should be done only if you have a specific need for unauthenticated clients.

Listener TLS protocol version changes

The listener tls_version option now defines the minimum TLS protocol version to be used, rather than the exact version. For example, setting tls_version 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. -p 1883 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 nobody user.

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.

Other behaviour

The pid_file option will now always attempt to write a pid file, regardless of whether the -d argument is used when running the broker.

The 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:

Client libraries

C/C++ libraries for creating MQTT clients.

  • lib/libmosquitto.so.1
  • lib/cpp/libmosquittopp.so.1
  • include/mosquitto.h
  • include/mqtt_protocol.h

Clients

General purpose command line MQTT clients. These depend upon libmosquitto.so.1.

  • client/mosquitto_pub
  • client/mosquitto_sub
  • client/mosquitto_rr

Broker

The main offering of the project, the Mosquitto broker, plus associated utilities and plugins.

  • apps/mosquitto_ctrl/mosquitto_ctrl
  • apps/mosquitto_passwd/mosquitto_passwd
  • plugins/dynamic-security/mosquitto_dynamic_security.so
  • src/mosquitto
  • include/mosquitto_broker.h
  • include/mosquitto_plugin.h

Changes:

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

Dependencies

mosquitto_ctrl and mosquitto_dynamic_secuity.so require the cJSON library. If it is not detected or desired, those features can be disabled.

Plugins

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 guidelines in 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. 4.