Migration guide, plus dynsec doc update, plus toc.

www/conf.py

@@ -1177,7 +1177,20 @@ PRETTY_URLS = True
 # Note: most Nikola-specific extensions are done via the Nikola plugin system,
 #       with the MarkdownExtension class and should not be added here.
 # 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.
 # by default, it's empty, is a list of strings, for example

www/pages/documentation.md

@@ -27,6 +27,8 @@
 # Other
 
 * [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.conf]:/man/mosquitto-conf-5.html
@@ -40,3 +42,5 @@
 [libmosquitto API documentation]:/api/
 
 [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/

www/pages/documentation/dynamic-security.md

@@ -9,6 +9,9 @@
 .. type: text
 -->
 
+
+[TOC]
+
 ## Introduction
 
 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
 installations, but will not be activated by default.
 
+
 ## Concepts
 
 This section describes the concepts of how the plugin operates. If you want to
@@ -199,8 +203,6 @@ role.
 
 ### Priorities
 
-**FIXME** example needs completing.
-
 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
 applied.
@@ -238,13 +240,33 @@ Group: `humidity`
 Roles: `humidity`
 
 Role: `hallway`
+ACLs: `Z` (priority 3), `A` (priority 1)
 
 Role: `input`
+ACLs: `Z` (priority 3), `A` (priority 3)
 
 Role: `output`
+ACLs: `Z` (priority 3), `A` (priority 1)
 
 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
 

www/pages/documentation/migrating-to-2-0.md

@@ -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