diff --git a/ChangeLog.txt b/ChangeLog.txt index 722eaf41..35b8a953 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -4,6 +4,10 @@ Broker: - Fix support for libwebsockets 3.x. - Fix slow websockets performance when sending large messages. Closes #1390. +Documentation: +- Improve details on global/per listener options in the mosquitto.conf man page. + Closes #274. + Build: - Fix missing function warnings on NetBSD. - Fix WITH_STATIC_LIBRARIES using CMake on Windows. Closes #1369. diff --git a/man/mosquitto.conf.5.xml b/man/mosquitto.conf.5.xml index bcc88bc6..68d48b5d 100644 --- a/man/mosquitto.conf.5.xml +++ b/man/mosquitto.conf.5.xml @@ -132,7 +132,7 @@ for the topic keyword, but using pattern as the keyword. pattern [read|write|readwrite] <topic> - + The patterns available for substition are: %c to match the client id of the client @@ -151,6 +151,13 @@ If the first character of a line of the ACL file is a # it is treated as a comment. + If is + true, this option applies to + the current listener being configured only. If + is + false, this option applies + to all listeners. + Reloaded on reload signal. The currently loaded ACLs will be freed and reloaded. Existing subscriptions will be affected after the reload. @@ -171,6 +178,14 @@ username/password or TLS-PSK checks, then defaults to false. + + If is + true, this option applies to + the current listener being configured only. If + is + false, this option applies + to all listeners. + Reloaded on reload signal. @@ -196,17 +211,28 @@ correctly deal with duplicate messages even when then have QoS=2. Defaults to true. + + This option applies globally. + Reloaded on reload signal. [ true | false ] - MQTT 3.1.1 allows clients to connect with a zero + MQTT 3.1.1 and MQTT 5 allow clients to connect with a zero length client id and have the broker generate a client id for them. Use this option to allow/disallow this behaviour. Defaults to true. See also the option. + + If is + true, this option applies to + the current listener being configured only. If + is + false, this option applies + to all listeners. + Reloaded on reload signal. @@ -214,7 +240,9 @@ value Options to be passed to the auth plugin. See the - specific plugin instructions. + specific plugin instructions. + + Applies to the current authentication plugin being configured. @@ -256,6 +284,8 @@ checks delivered to your plugin by setting this option to false. Defaults to true. + + Applies to the current authentication plugin being configured. Not currently reloaded on reload signal. @@ -267,6 +297,14 @@ to set a string that will be prefixed to the automatically generated client ids to aid visibility in logs. Defaults to . + + If is + true, this option applies to + the current listener being configured only. If + is + false, this option applies + to all listeners. + Reloaded on reload signal. @@ -280,6 +318,9 @@ SIGUSR1 signal. Note that this setting only has an effect if persistence is enabled. Defaults to 1800 seconds (30 minutes). + + This option applies globally. + Reloaded on reload signal. @@ -295,6 +336,9 @@ the in-memory database to disk by treating as a time in seconds. + + This option applies globally. + Reloaded on reload signal. @@ -325,6 +369,9 @@ "secure-" here would mean a client "secure-client" could connect but another with clientid "mqtt" couldn't. By default, all client ids are valid. + + This option applies globally. + Reloaded on reload signal. Note that currently connected clients will be unaffected by any changes. @@ -337,6 +384,9 @@ will include entries when clients connect and disconnect. If set to false, these entries will not appear. + + This option applies globally. + Reloaded on reload signal. @@ -502,9 +552,11 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S count QoS 1 and 2 messages will be allowed in flight until this byte - limit is reached. Defaults to 0. (No limit) - See also the option. - + limit is reached. Defaults to 0. (No limit) + See also the option. + + This option applies globally. + Reloaded on reload signal. @@ -518,6 +570,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S Defaults to 20. Set to 0 for no maximum. If set to 1, this will guarantee in-order delivery of messages. + + This option applies globally. + Reloaded on reload signal. @@ -537,6 +592,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S max_keepalive. This only applies to MQTT v5 clients. The maximum value allowable, and default value, is 65535. Do not set below 10 seconds. + + This option applies globally. + Reloaded on reload signal. @@ -559,6 +617,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S Setting below 20 bytes is forbidden because it is likely to interfere with normal client operation even with small payloads. + + This option applies globally. + Reloaded on reload signal. @@ -572,6 +633,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S If both max_queued_messages and max_queued_bytes are specified, packets will be queued until the first limit is reached. + + This option applies globally. + Reloaded on reload signal. @@ -583,8 +647,10 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S in flight. Defaults to 100. Set to 0 for no maximum (not recommended). See also the and - options. - + options. + + This option applies globally. + Reloaded on reload signal. @@ -615,6 +681,10 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S The default value is 0, which means that all valid MQTT messages are accepted. MQTT imposes a maximum payload size of 268435455 bytes. + + This option applies globally. + + Reloaded on reload signal. @@ -638,6 +708,14 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S valid and could be used with acl_file to have e.g. read only guest/anonymous accounts and defined users that can publish. + + If is + true, this option applies to + the current listener being configured only. If + is + false, this option applies + to all listeners. + Reloaded on reload signal. The currently loaded username and password data will be freed and reloaded. Clients that are already connected will not be @@ -693,6 +771,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S copy of the persistence file before installing a new version so that they can roll back to an earlier version if necessary. + + This option applies globally. + Reloaded on reload signal. @@ -701,6 +782,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S The filename to use for the persistent database. Defaults to mosquitto.db. + + This option applies globally. + Reloaded on reload signal. @@ -710,6 +794,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S The path where the persistence database should be stored. Must end in a trailing slash. If not given, then the current directory is used. + + This option applies globally. + Reloaded on reload signal. @@ -735,6 +822,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S As this is a non-standard option, the default if not set is to never expire persistent clients. + + This option applies globally. + Reloaded on reload signal. @@ -765,6 +855,14 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S listener that has PSK support enabled must provide a matching identity and PSK to allow the encrypted connection to proceed. + + If is + true, this option applies to + the current listener being configured only. If + is + false, this option applies + to all listeners. + Reloaded on reload signal. The currently loaded identity and key data will be freed and reloaded. Clients that are already connected will not be @@ -781,6 +879,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S Note that the MQTT v3.1.1 spec states that only QoS 1 and 2 messages should be saved in this situation so this is a non-standard option. + + This option applies globally. + Reloaded on reload signal. @@ -791,6 +892,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S supported. Clients that send a message with the retain bit will be disconnected if this option is set to false. Defaults to true. + + This option applies globally. + Reloaded on reload signal. @@ -810,6 +914,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S has the effect of reducing latency of some messages at potentially increasing the number of TCP packets being sent. Defaults to false. + + This option applies globally. + Reloaded on reload signal. @@ -822,6 +929,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S seconds. Set to 0 to disable publishing the $SYS hierarchy completely. + + This option applies globally. + Reloaded on reload signal. @@ -838,6 +948,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S subscription. This is a non-standard option not provided for by the spec. Defaults to false. + + This option applies globally. + Reloaded on reload signal. @@ -848,7 +961,8 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S group on startup. If mosquitto is unable to change to this user and group, it will exit with an error. The user specified must have read/write access to the - persistence database if it is to be written. If run as + persistence database if it is to be written, and read + access to certificate, password, and ACL files. If run as a non-root user, this setting has no effect. Defaults to mosquitto. This setting has no effect on Windows and so you @@ -876,8 +990,14 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S to restrict access to certain network interfaces. To restrict access to mosquitto to the local host only, use "bind_address localhost". This only - applies to the default listener. Use the listener - variable to control other listeners. + applies to the default listener. Use the + option to control other + listeners. + + It is recommended to use an explicit + rather than rely on the + implicit default listener options like this. + Not reloaded on reload signal. @@ -955,7 +1075,7 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S count - Limit the QoS value allowed when using this + Limit the QoS value allowed for clients connecting to this listener. Defaults to 2, which means any QoS can be used. Set to 0 or 1 to limit to those QoS values. This makes use of an MQTT v5 feature to notify @@ -970,9 +1090,9 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S number This option sets the maximum number topic aliases - that an MQTT v5 client is allowed to create. It + that an MQTT v5 client is allowed to create. This option applies per listener. Defaults to 10. Set to 0 to - disallow topic aliases. + disallow topic aliases. The maximum value possible is 65535. Not reloaded on reload signal. @@ -998,12 +1118,16 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S Set the network port for the default listener to listen on. Defaults to 1883. Not reloaded on reload signal. + + It is recommended to use an explicit + rather than rely on the + implicit default listener options like this. value - Set the protocol to accept for this listener. Can + Set the protocol to accept for the current listener. Can be , the default, or if available. Websockets support is currently disabled by @@ -1095,7 +1219,7 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S file path At least one of or - must be provided to allow + must be provided to enable SSL support. is used to define the path to a file containing the PEM encoded CA @@ -1106,7 +1230,7 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S directory path At least one of or - must be provided to allow + must be provided to enable SSL support. is used to define a directory that contains PEM encoded CA certificates @@ -1170,11 +1294,11 @@ openssl dhparam -out dhparam.pem 2048 trusted certificate. The overall aim is encryption of the network traffic. By setting to - true, the client must - provide a valid certificate in order for the - network connection to proceed. This allows access - to the broker to be controlled outside of the - mechanisms provided by MQTT. + true, a client connecting + to this listener must provide a valid certificate in + order for the network connection to proceed. This + allows access to the broker to be controlled outside + of the mechanisms provided by MQTT. @@ -1462,7 +1586,7 @@ openssl dhparam -out dhparam.pem 2048 [ true | false ] If set to true, only publish - notification messages to the local broker giving + notification messages to the local broker giving information about the state of the bridge connection. Defaults to false.