Migration guide, plus dynsec doc update, plus toc.
This commit is contained in:
parent
3a7670507a
commit
fc51063d54
15
www/conf.py
15
www/conf.py
@ -1177,7 +1177,20 @@ PRETTY_URLS = True
|
|||||||
# Note: most Nikola-specific extensions are done via the Nikola plugin system,
|
# Note: most Nikola-specific extensions are done via the Nikola plugin system,
|
||||||
# with the MarkdownExtension class and should not be added here.
|
# with the MarkdownExtension class and should not be added here.
|
||||||
# The default is ['fenced_code', 'codehilite']
|
# The default is ['fenced_code', 'codehilite']
|
||||||
MARKDOWN_EXTENSIONS = ['fenced_code', 'codehilite', 'extra']
|
#MARKDOWN_EXTENSIONS = ['fenced_code', 'codehilite', 'extra', 'toc']
|
||||||
|
|
||||||
|
MARKDOWN_EXTENSIONS = ['markdown.extensions.fenced_code', 'markdown.extensions.codehilite', 'markdown.extensions.extra', 'markdown.extensions.toc']
|
||||||
|
|
||||||
|
# Options to be passed to markdown extensions (See https://python-markdown.github.io/reference/)
|
||||||
|
# Default is {} (no config at all)
|
||||||
|
MARKDOWN_EXTENSION_CONFIGS = {
|
||||||
|
DEFAULT_LANG: {
|
||||||
|
'markdown.extensions.toc':{
|
||||||
|
'toc_depth':2
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
# Extra options to pass to the pandoc command.
|
# Extra options to pass to the pandoc command.
|
||||||
# by default, it's empty, is a list of strings, for example
|
# by default, it's empty, is a list of strings, for example
|
||||||
|
@ -27,6 +27,8 @@
|
|||||||
# Other
|
# Other
|
||||||
|
|
||||||
* [Using the snap package] - specific instructions on installing and configuring the Mosquitto snap package.
|
* [Using the snap package] - specific instructions on installing and configuring the Mosquitto snap package.
|
||||||
|
* [Dynamic Security plugin] - details of using the Dynamic Security authentication and access control plugin.
|
||||||
|
* [Migrating from 1.x to 2.0] - details of changes needed to migrate to version 2.0.
|
||||||
|
|
||||||
[mosquitto]:/man/mosquitto-8.html
|
[mosquitto]:/man/mosquitto-8.html
|
||||||
[mosquitto.conf]:/man/mosquitto-conf-5.html
|
[mosquitto.conf]:/man/mosquitto-conf-5.html
|
||||||
@ -40,3 +42,5 @@
|
|||||||
[libmosquitto API documentation]:/api/
|
[libmosquitto API documentation]:/api/
|
||||||
|
|
||||||
[Using the snap package]:/documentation/using-the-snap/
|
[Using the snap package]:/documentation/using-the-snap/
|
||||||
|
[Dynamic Security plugin]:/documentation/dynamic-security/
|
||||||
|
[Migrating from 1.x to 2.0]:/documentation/migrating-to-2-0/
|
||||||
|
@ -9,6 +9,9 @@
|
|||||||
.. type: text
|
.. type: text
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
|
||||||
|
[TOC]
|
||||||
|
|
||||||
## Introduction
|
## Introduction
|
||||||
|
|
||||||
The Dynamic Security plugin is a Mosquitto plugin which provides role based
|
The Dynamic Security plugin is a Mosquitto plugin which provides role based
|
||||||
@ -18,6 +21,7 @@ is running, using a special topic based API.
|
|||||||
It is supported since Mosquitto 2.0, and should be available in all
|
It is supported since Mosquitto 2.0, and should be available in all
|
||||||
installations, but will not be activated by default.
|
installations, but will not be activated by default.
|
||||||
|
|
||||||
|
|
||||||
## Concepts
|
## Concepts
|
||||||
|
|
||||||
This section describes the concepts of how the plugin operates. If you want to
|
This section describes the concepts of how the plugin operates. If you want to
|
||||||
@ -199,8 +203,6 @@ role.
|
|||||||
|
|
||||||
### Priorities
|
### Priorities
|
||||||
|
|
||||||
**FIXME** example needs completing.
|
|
||||||
|
|
||||||
If you are working with more than one role per client or group, or more than
|
If you are working with more than one role per client or group, or more than
|
||||||
one group per client, then it is crucial to understand how roles and ACLs are
|
one group per client, then it is crucial to understand how roles and ACLs are
|
||||||
applied.
|
applied.
|
||||||
@ -238,13 +240,33 @@ Group: `humidity`
|
|||||||
Roles: `humidity`
|
Roles: `humidity`
|
||||||
|
|
||||||
Role: `hallway`
|
Role: `hallway`
|
||||||
|
ACLs: `Z` (priority 3), `A` (priority 1)
|
||||||
|
|
||||||
Role: `input`
|
Role: `input`
|
||||||
|
ACLs: `Z` (priority 3), `A` (priority 3)
|
||||||
|
|
||||||
Role: `output`
|
Role: `output`
|
||||||
|
ACLs: `Z` (priority 3), `A` (priority 1)
|
||||||
|
|
||||||
Role: `humidity`
|
Role: `humidity`
|
||||||
|
ACLs: `Z` (priority 3), `A` (priority 1)
|
||||||
|
|
||||||
|
We are also assuming we are only looking at single ACL type.
|
||||||
|
|
||||||
|
If our client `sensor` triggers an ACL check, the ACLs will be checked in this
|
||||||
|
order, and the first matching ACL will be used to allow/reject the event:
|
||||||
|
|
||||||
|
1. sensor/hallway Z
|
||||||
|
2. sensor/hallway A
|
||||||
|
3. temperature/input A (alphabetical sort)
|
||||||
|
4. temperature/input Z (alphabetical sort)
|
||||||
|
5. temperature/output Z
|
||||||
|
6. temperature/output A
|
||||||
|
7. humidity/humidity Z
|
||||||
|
8. humidity/humidity A
|
||||||
|
|
||||||
|
This is provided as an example that covers all combinations of roles, it is
|
||||||
|
recommended to use as simple a setup as possible for your situation.
|
||||||
|
|
||||||
### Anonymous access
|
### Anonymous access
|
||||||
|
|
||||||
|
206
www/pages/documentation/migrating-to-2-0.md
Normal file
206
www/pages/documentation/migrating-to-2-0.md
Normal file
@ -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
|
Loading…
Reference in New Issue
Block a user