-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Migration guide, plus dynsec doc update, plus toc.
- Loading branch information
Showing
4 changed files
with
248 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,206 @@ | ||
<!-- | ||
.. title: Migrating from 1.x to 2.0 | ||
.. slug: migrating-to-2-0 | ||
.. date: 2020-12-03 12:25:28 UTC | ||
.. tags: | ||
.. category: | ||
.. link: | ||
.. description: | ||
.. type: text | ||
--> | ||
|
||
[TOC] | ||
|
||
## 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`. | ||
|
||
[misc/letsencrypt/mosquitto-copy.sh]:https://github.com/eclipse/mosquitto/tree/master/misc/letsencrypt | ||
[dynamic-security plugin]:/documentation/dynamic-security/ | ||
[mosquitto-go-auth plugin]:https://github.com/iegomez/mosquitto-go-auth |