Additional documentation

www/pages/documentation.md

@@ -13,25 +13,43 @@
 
 * [mosquitto] - running the Mosquitto broker
 * [mosquitto.conf] - the Mosquitto broker configuration file
+* [mosquitto_ctrl] - command line utility for managing Mosquitto broker configuration
+* [mosquitto_ctrl_dynsec] - `mosquitto_ctrl` batch mode for the dynamic-security plugin
+* [mosquitto_ctrl_shell] - `mosquitto_ctrl` interactive shell mode (recommended)
 * [mosquitto_passwd] - command line utility for generating Mosquitto password files
 * [mosquitto_pub] - command line utility for publishing messages to a broker
 * [mosquitto_rr] - command line utility for simple request/response with a broker
+* [mosquitto_signal] - command line utility for sending signals to a broker, most useful on Windows
 * [mosquitto_sub] - command line utility for subscribing to topics on a broker
 * [mosquitto-tls] - brief cheat sheet for creating x509 certificates
 * [mqtt] - description of MQTT features
 
-# libmosquitto API
+# Listeners
 
-* [libmosquitto API documentation]
+* [Using Mosquitto with HAProxy] - using Mosquitto with HAProxy with or without TLS termination.
+* [Replacing the per_listener_settings option](/documentation/listeners/per_listener_settings/)
+
+# Persistence
+
+* [Sqlite](/documentation/persistence/sqlite/)
+
+# Plugins
+
+* [ACL file] - replacement for the `acl_file` option.
+* [Password file] - replacement for the `password_file` option.
+* [Dynamic Security] - details of using the Dynamic Security authentication and access control plugin.
+* [Sparkplug Aware] - make Mosquitto fully compliant with the Sparkplug protocol.
 
 # Other
 
 * [Authentication methods] - details on the different authentication options available.
-* [Dynamic Security plugin] - details of using the Dynamic Security authentication and access control plugin.
-* [Using Mosquitto with HAProxy] - using Mosquitto with HAProxy with or without TLS termination.
 * [Using the snap package] - specific instructions on installing and configuring the Mosquitto snap package.
 * [Migrating from 1.x to 2.0] - details of changes needed to migrate to version 2.0.
 
+# libmosquitto API
+
+* [libmosquitto API documentation]
+
 # Third party
 
 These are some Mosquitto documentation hosted by third parties.
@@ -43,19 +61,27 @@ These are some Mosquitto documentation hosted by third parties.
 
 [mosquitto]:/man/mosquitto-8.html
 [mosquitto.conf]:/man/mosquitto-conf-5.html
+[mosquitto_ctrl]:(/man/mosquitto_ctrl-1.html)
+[mosquitto_ctrl_dynsec]:(/man/mosquitto_ctrl_dynsec-1.html)
+[mosquitto_ctrl_shell]:(/man/mosquitto_ctrl_shell-1.html)
 [mosquitto_passwd]:/man/mosquitto_passwd-1.html
 [mosquitto_pub]:/man/mosquitto_pub-1.html
 [mosquitto_rr]:/man/mosquitto_rr-1.html
+[mosquitto_signal]:(/man/mosquitto_signal-1.html)
 [mosquitto_sub]:/man/mosquitto_sub-1.html
 [mosquitto-tls]:/man/mosquitto-tls-7.html
 [mqtt]:/man/mqtt-7.html
 
+
 [libmosquitto API documentation]:/api/
 
 [Authentication methods]:/documentation/authentication-methods/
 [Using the snap package]:/documentation/using-the-snap/
-[Dynamic Security plugin]:/documentation/dynamic-security/
-[Using Mosquitto with HAProxy]:/documentation/haproxy/
+[Dynamic Security]:/documentation/dynamic-security/
+[ACL file]:/documentation/plugins/acl-file/
+[Password file]:/documentation/plugins/password-file/
+[Sparkplug Aware]:/documentation/plugins/sparkplug-aware/
+[Using Mosquitto with HAProxy]:/documentation/listeners/haproxy/
 [Migrating from 1.x to 2.0]:/documentation/migrating-to-2-0/
 
 [Steve's internet guide]: http://www.steves-internet-guide.com/

www/pages/documentation/listeners/per_listener_settings.md

@@ -0,0 +1,69 @@
+<!--
+.. title: Replacing the per_listener_settings option
+.. slug: per-listener-settings
+.. date: 2026-01-29 09:00:00 UTC
+.. tags:
+.. category:
+.. link:
+.. description:
+.. type: text
+-->
+
+
+[TOC]
+
+## Introduction
+
+The `per_listener_settings` option was introduced in version 1.5 as a way to
+allow security options such as `allow_anonymous` and `password_file` to be
+applied on a per-listener basis, rather than globally as was the only option
+before. It was however a poorly thought out idea that has lead to a great deal
+of confusion, and since version 2.1 is deprecated. It will be removed in
+version 3.0.
+
+This document sets out how to remove the use of this option whilst keeping the
+same functionality in your configuration. These changes require version 2.1.
+
+## Authentication
+
+* Replace the `acl_file` option with the [mosquitto_acl_file](/documentation/plugins/acl-file/) plugin.
+* Replace the `password_file` option with the [mosquitto_password_file](/documentation/plugins/password-file/) plugin.
+* Replace the use of `allow_anonymous` with the listener specific
+`listener_allow_anonymous`. If `listener_allow_anonymous` is set for a
+listener, this overrides any value set by `allow_anonymous`.
+* Replace `auto_id_prefix` with `listener_auto_id_prefix`.
+`allow_zero_length_clientid` has no replacement.
+
+## Plugins
+
+Prior to 2.1, plugins could be loaded with the `plugin` or `global_plugin`
+options, where `plugin` would be applied to all plugins or a single plugin,
+depending on the `per_listener_setting` value, and `global_plugin` would always
+apply to all listeners.
+
+`global_plugin` should still be used to load a plugin across all listener.
+
+To use a plugin on some listeners only, use `plugin_load`, which loads a plugin
+into the broker, and `plugin_use` which applies it to a listener.
+
+For example:
+
+```
+plugin_load dynsec /usr/lib/mosquitto_dynamic_security.so
+plugin_opt_config_file /mosquitto/data/dynamic-security.json
+
+listener 1883
+plugin_use dynsec
+
+listener 1884
+listener_allow_anonymous true
+
+listener 1885
+plugin_use dynsec
+```
+
+This configuration loads the dynamic-security plugin and uses it with the
+listeners on ports 1883 and 1885. The listener on port 1884 does not have the
+plugin applied, and also allows anonymous connections (so is very insecure,
+anything connecting to that port can publish/subscribe to anything).
+

www/pages/documentation/persistence/sqlite.md

@@ -0,0 +1,53 @@
+<!--
+.. title: Sqlite Persistence
+.. slug: sqlite
+.. date: 2026-01-30 09:00:00 UTC
+.. tags:
+.. category:
+.. link:
+.. description:
+.. type: text
+-->
+
+## Introduction
+
+Available since version 2.1.
+
+This plugin provides a replacement for the traditional mosquitto persistence
+normally enabled with `persistence true`.
+
+This plugin should be preferred when you are interested in persistence, because
+it saves changes to disk as they are made, where as the traditional persistence
+only takes periodic snapshots.
+
+## Usage
+
+The plugin requires minimal configuration.
+
+The `plugin_opt_sync` option can be set to `extra`, `full`, `normal`, or `off`,
+with a default of `normal`. This option controls how hard sqlite works to
+ensure data is on the disk before continuing. This is better described by
+[sqlite themselves](https://www.sqlite.org/pragma.html#pragma_synchronous).
+
+The `plugin_opt_page_size` option sets the database page size, as described
+[here](https://www.sqlite.org/pragma.html#pragma_page_size).
+
+The `plugin_opt_flush_period` option is a positive integer number of seconds,
+defaulting to 5, that the plugin will batch database updates over in order to
+improve performance.
+
+# Config
+
+Windows:
+```
+persistence_location <path to save mosquitto.sqlite3>
+global_plugin C:\Program Files\Mosquitto\mosquitto_persist_sqlite.dll
+plugin_opt_acl_file <my acl file path>
+```
+
+Other:
+```
+persistence_location <path to save mosquitto.sqlite3>
+global_plugin /path/to/mosquitto_persist_sqlite.so
+plugin_opt_acl_file <my acl file path>
+```

www/pages/documentation/plugins/acl-file.md

@@ -0,0 +1,100 @@
+<!--
+.. title: ACL file Plugin
+.. slug: acl-file
+.. date: 2026-01-30 09:00:00 UTC
+.. tags:
+.. category:
+.. link:
+.. description:
+.. type: text
+-->
+
+## Introduction
+
+Available since version 2.1.
+
+This plugin provides the same functionality as the `acl_file` option, and
+should be the preferred way of using an ACL file.
+
+The [dynamic-security plugin](/documentation/dynamic-security/) provides a more
+powerful approach to authentication and authorisation.
+
+## Usage
+
+Control access to topics on the broker using an access control list file. If
+this parameter is defined then only the topics listed will have access.  If the
+first character of a line of the ACL file is a `#` it is treated as a comment.
+
+Topic access is added with lines of the format:
+
+```
+topic [read|write|readwrite|deny] <topic>
+```
+
+The access type is controlled using `read`, `write`, `readwrite` or `deny`.
+This parameter is optional (unless `<topic>` contains a space character) - if
+not given then the access is read/write.  `<topic>` can contain the `+` or `#` 
+wildcards as in subscriptions.
+
+The `deny` option can used to explicitly deny access to a topic that would
+otherwise be granted by a broader read/write/readwrite statement. Any `deny`
+topics are handled before topics that grant read/write access.
+
+The first set of topics are applied to anonymous clients, assuming anonymous
+access is allowed. User specific topic ACLs are added after a user line as
+follows:
+
+```
+user <username>
+```
+
+The username referred to here is the same as provided in the CONNECT packet. It
+is not the clientid.
+
+If is also possible to define ACLs based on pattern substitution within the
+topic.
+
+```
+pattern [read|write|readwrite] <topic>
+```
+
+The patterns available for substitution are:
+
+* %c to match the client id of the client
+* %u to match the username of the client
+
+The substitution pattern must be the only text for that level of hierarchy.
+
+The form is the same as for the topic keyword, but using pattern as the
+keyword.
+
+Pattern ACLs apply to all users even if the `user` keyword has previously
+been given.
+
+If using bridges with usernames and ACLs, connection messages can be allowed
+with the following pattern:
+
+```
+pattern write $SYS/broker/connection/%c/state
+```
+
+
+Example:
+
+```
+pattern write sensor/%u/data
+```
+
+# Config
+
+Windows:
+```
+global_plugin C:\Program Files\Mosquitto\mosquitto_acl_file.dll
+plugin_opt_acl_file <my acl file path>
+```
+
+Other:
+```
+global_plugin /path/to/mosquitto_acl_file.so
+plugin_opt_acl_file <my acl file path>
+```

www/pages/documentation/plugins/password-file.md

@@ -0,0 +1,38 @@
+<!--
+.. title: Password file Plugin
+.. slug: password-file
+.. date: 2026-01-30 09:00:00 UTC
+.. tags:
+.. category:
+.. link:
+.. description:
+.. type: text
+-->
+
+## Introduction
+
+Available since version 2.1.
+
+This plugin provides the same functionality as the `password_file` option, and
+should be the preferred way of using an password file.
+
+The [dynamic-security plugin](/documentation/dynamic-security/) provides a more
+powerful approach to authentication and authorisation.
+
+## Usage
+
+Generate password files using the [mosquitto_passwd](/man/mosquitto_passwd-1.html) utility.
+
+# Config
+
+Windows:
+```
+global_plugin C:\Program Files\Mosquitto\mosquitto_password_file.dll
+plugin_opt_password_file <my password file path>
+```
+
+Other:
+```
+global_plugin /path/to/mosquitto_password_file.so
+plugin_opt_password_file <my password file path>
+```

www/pages/documentation/plugins/sparkplug-aware.md

@@ -0,0 +1,41 @@
+<!--
+.. title: Sparkplug Aware Plugin
+.. slug: sparkplug-aware
+.. date: 2026-01-30 09:00:00 UTC
+.. tags:
+.. category:
+.. link:
+.. description:
+.. type: text
+-->
+
+Available since version 2.1.
+
+The [Sparkplug protocol](https://sparkplug.eclipse.org/) provides a unified way
+to manage topics, device lifetime, and payload format. It is typically intended
+for use in Industrial Internet of Things applications, such as in factories.
+
+The Sparkplug specification makes certain requirements on clients and brokers.
+For brokers there are two levels of conformance: Sparkplug Compliant and
+Sparkplug Aware.
+
+Any MQTT broker that conforms to the MQTT v3.1.1 or v5.0 protocol meets the
+requirements to be Sparkplug Compliant.
+
+A Sparkplug Aware broker also needs to monitor birth messages from Sparkplug
+nodes and devices, and republish them to the appropriate topic within
+`$sparkplug/certificates/spBv1.0/`
+
+Loading this plugin makes provides Sparkplug Aware support for Mosquitto.
+
+## Config
+
+Windows:
+```
+global_plugin C:\Program Files\Mosquitto\mosquitto_sparkplug_aware.dll
+```
+
+Other:
+```
+global_plugin /path/to/mosquitto_sparkplug_aware.so
+```