From e43d36020f85491daeae87bcd9dc744c5b31ddfe Mon Sep 17 00:00:00 2001 From: "Roger A. Light" Date: Tue, 31 Aug 2021 10:57:48 +0100 Subject: [PATCH] Update plugin configuration documentation. Closes #2286. Thanks to Karl Palsson. --- ChangeLog.txt | 1 + man/mosquitto.conf.5.xml | 77 ++++++++++++++++++++++++---------------- mosquitto.conf | 50 +++++++++++++++++--------- 3 files changed, 80 insertions(+), 48 deletions(-) diff --git a/ChangeLog.txt b/ChangeLog.txt index b6f9aa9ba3..3889adcd73 100644 --- a/ChangeLog.txt +++ b/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" diff --git a/man/mosquitto.conf.5.xml b/man/mosquitto.conf.5.xml index 44459de7ec..078d8eba6e 100644 --- a/man/mosquitto.conf.5.xml +++ b/man/mosquitto.conf.5.xml @@ -258,35 +258,6 @@ Reloaded on reload signal. - - value - - Options to be passed to the auth plugin. See the - specific plugin instructions. - - Applies to the current authentication plugin being configured. - - - - file path - - Specify an external module to use for authentication - and access control. This allows custom - username/password and access control functions to be - created. - Can be specified multiple times to load multiple - plugins. The plugins will be processed in the order - that they are specified. - If , or - are used in the config file - alongsize , the plugin - checks will run after the built in checks. - Not currently reloaded on reload signal. - See also - - - - [ true | false ] @@ -796,9 +767,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S , , , , - , - , . + , + , 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 Not reloaded on reload signal. + + value + + + Options to be passed to the most recent + defined in the + configuration file. See the specific + plugin instructions for details of what + options are available. + + + Applies to the current plugin being configured. + + This is also available as the + option, but this use is deprecated and will be removed + in a future version. + + + + + file path + + Specify an external module to use for authentication + and access control. This allows custom + username/password and access control functions to be + created. + Can be specified multiple times to load multiple + plugins. The plugins will be processed in the order + that they are specified. + If , or + are used in the config file + alongsize , the plugin + checks will run after the built in checks. + Not currently reloaded on reload signal. + See also + + + + This is also available as the + option, but this use is deprecated and will be removed + in a future version. + + + file path diff --git a/mosquitto.conf b/mosquitto.conf index 5b1f785b8b..ee1073086e 100644 --- a/mosquitto.conf +++ b/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,8 +537,8 @@ # 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 @@ -540,7 +546,7 @@ # 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 # =================================================================