Update plugin configuration documentation.

Closes #2286. Thanks to Karl Palsson.

ChangeLog.txt

@@ -40,6 +40,7 @@ Broker:
 - Strict protocol compliance fixes, plus test suite.
 - Fix $share subscriptions not being recovered for durable clients that
  reconnect.
+- Update plugin configuration documentation. Closes #2286.
 
 Client library:
 - If a client uses TLS-PSK then force the default cipher list to use "PSK"

man/mosquitto.conf.5.xml

@@ -258,35 +258,6 @@
  <para>Reloaded on reload signal.</para>
  </listitem>
  </varlistentry>
- <varlistentry>
- <term><option>auth_opt_*</option> <replaceable>value</replaceable></term>
- <listitem>
- <para>Options to be passed to the auth plugin. See the
- specific plugin instructions.</para>
-
- <para>Applies to the current authentication plugin being configured.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>auth_plugin</option> <replaceable>file path</replaceable></term>
- <listitem>
- <para>Specify an external module to use for authentication
- and access control. This allows custom
- username/password and access control functions to be
- created.</para>
- <para>Can be specified multiple times to load multiple
- plugins. The plugins will be processed in the order
- that they are specified.</para>
- <para>If <option>password_file</option>, or
- <option>acl_file</option> are used in the config file
- alongsize <option>auth_plugin</option>, the plugin
- checks will run after the built in checks.</para>
- <para>Not currently reloaded on reload signal.</para>
- <para>See also 
- <ulink url="https://mosquitto.org/documentation/dynamic-security/"/>
- </para>
- </listitem>
- </varlistentry>
  <varlistentry>
  <term><option>auth_plugin_deny_special_chars</option> [ true | false ]</term>
  <listitem>
@@ -796,9 +767,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S
  <option>acl_file</option>, <option>psk_file</option>,
  <option>allow_anonymous</option>,
  <option>allow_zero_length_clientid</option>,
- <option>auth_plugin</option>,
- <option>auth_opt_*</option>,
  <option>auto_id_prefix</option>.</para>
+ <option>plugin</option>,
+ <option>plugin_opt_*</option>,
  <para>Note that if set to true, then a durable client (i.e.
  with clean session set to false) that has disconnected
  will use the ACL settings defined for the listener that
@@ -901,6 +872,50 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S
  <para>Not reloaded on reload signal.</para>
  </listitem>
  </varlistentry>
+ <varlistentry>
+ <term><option>plugin_opt_*</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ Options to be passed to the most recent
+ <option>plugin</option> defined in the
+ configuration file. See the specific
+ plugin instructions for details of what
+ options are available.
+ </para>
+
+ <para>Applies to the current plugin being configured.</para>
+ <para>
+ This is also available as the <option>auth_opt_*</option>
+ option, but this use is deprecated and will be removed
+ in a future version.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>plugin</option> <replaceable>file path</replaceable></term>
+ <listitem>
+ <para>Specify an external module to use for authentication
+ and access control. This allows custom
+ username/password and access control functions to be
+ created.</para>
+ <para>Can be specified multiple times to load multiple
+ plugins. The plugins will be processed in the order
+ that they are specified.</para>
+ <para>If <option>password_file</option>, or
+ <option>acl_file</option> are used in the config file
+ alongsize <option>plugin</option>, the plugin
+ checks will run after the built in checks.</para>
+ <para>Not currently reloaded on reload signal.</para>
+ <para>See also
+ <ulink url="https://mosquitto.org/documentation/dynamic-security/"/>
+ </para>
+ <para>
+ This is also available as the <option>auth_plugin</option>
+ option, but this use is deprecated and will be removed
+ in a future version.
+ </para>
+ </listitem>
+ </varlistentry>
  <varlistentry>
  <term><option>psk_file</option> <replaceable>file path</replaceable></term>
  <listitem>

mosquitto.conf

@@ -19,8 +19,14 @@
 # options are controlled on a per listener basis. The following options are
 # affected:
 #
-# password_file acl_file psk_file auth_plugin auth_opt_* allow_anonymous
-# auto_id_prefix allow_zero_length_clientid
+# acl_file
+# allow_anonymous
+# allow_zero_length_clientid
+# auto_id_prefix
+# password_file
+# plugin
+# plugin_opt_*
+# psk_file
 #
 # Note that if set to true, then a durable client (i.e. with clean session set
 # to false) that has disconnected will use the ACL settings defined for the
@@ -531,16 +537,16 @@
 # offers very little in the way of security.
 #
 # See the TLS client require_certificate and use_identity_as_username options
-# for alternative authentication options. If an auth_plugin is used as well as
-# password_file, the auth_plugin check will be made first.
+# for alternative authentication options. If a plugin is used as well as
+# password_file, the plugin check will be made first.
 #password_file
 
 # Access may also be controlled using a pre-shared-key file. This requires
 # TLS-PSK support and a listener configured to use it. The file should be text
 # lines in the format:
 # identity:key
 # The key should be in hexadecimal format without a leading "0x".
-# If an auth_plugin is used as well, the auth_plugin check will be made first.
+# If an plugin is used as well, the plugin check will be made first.
 #psk_file
 
 # Control access to topics on the broker using an access control list
@@ -594,7 +600,7 @@
 #
 # pattern write sensor/%u/data
 #
-# If an auth_plugin is used as well as acl_file, the auth_plugin check will be
+# If an plugin is used as well as acl_file, the plugin check will be
 # made first.
 #acl_file
 
@@ -603,24 +609,34 @@
 # -----------------------------------------------------------------
 
 # External authentication and access control can be supported with the
-# auth_plugin option. This is a path to a loadable plugin. See also the
-# auth_opt_* options described below.
+# plugin option. This is a path to a loadable plugin. See also the
+# plugin_opt_* options described below.
 #
-# The auth_plugin option can be specified multiple times to load multiple
+# The plugin option can be specified multiple times to load multiple
 # plugins. The plugins will be processed in the order that they are specified
-# here. If the auth_plugin option is specified alongside either of
+# here. If the plugin option is specified alongside either of
 # password_file or acl_file then the plugin checks will be made first.
 #
-#auth_plugin
+# If the per_listener_settings option is false, the plugin will be apply to all
+# listeners. If per_listener_settings is true, then the plugin will apply to
+# the current listener being defined only.
+#
+# This option is also available as `auth_plugin`, but this use is deprecated
+# and will be removed in the future.
+#
+#plugin
 
-# If the auth_plugin option above is used, define options to pass to the
+# If the plugin option above is used, define options to pass to the
 # plugin here as described by the plugin instructions. All options named
-# using the format auth_opt_* will be passed to the plugin, for example:
+# using the format plugin_opt_* will be passed to the plugin, for example:
+#
+# This option is also available as `auth_opt_*`, but this use is deprecated
+# and will be removed in the future.
 #
-# auth_opt_db_host
-# auth_opt_db_port
-# auth_opt_db_username
-# auth_opt_db_password
+# plugin_opt_db_host
+# plugin_opt_db_port
+# plugin_opt_db_username
+# plugin_opt_db_password
 
 
 # =================================================================