Commits

Roger Light committed 11eee26

mosquitto.conf man page fixes and cleanup.

Comments (0)

Files changed (2)

   bug #1215084.
 - Use RTLD_GLOBAL when opening authentication plugins on posix systems. Fixes
   resolving of symbols in libraries used by authentication plugins.
+- Add/fix some config documentation.
 
 Client library:
 - Fix support for Python 2.6, 3.0, 3.1.

man/mosquitto.conf.5.xml

 				<term><option>acl_file</option> <replaceable>file path</replaceable></term>
 				<listitem>
 					<para>Set the path to an access control list file. If
-					defined, the contents of the file are used to control
-					client access to topics on the broker.</para>
+						defined, the contents of the file are used to control
+						client access to topics on the broker.</para>
 					<para>If this parameter is defined then only the topics
-					listed will have access. Topic access is added with lines
-					of the format:</para>
+						listed will have access. Topic access is added with
+						lines of the format:</para>
 
 					<para><code>topic [read|write] &lt;topic&gt;</code></para>
 
 					<para>The access type is controlled using "read" or
-					"write". This parameter is optional - if not given then the
-					access is read/write.  &lt;topic&gt; can contain the + or #
-					wildcards as in subscriptions.</para>
+						"write". This parameter is optional - if not given then
+						the access is read/write.  &lt;topic&gt; can contain
+						the + or # wildcards as in subscriptions.</para>
 
 					<para>The first set of topics are applied to anonymous
-					clients, assuming allow_anonymous is true. User specific
-					topic ACLs are added after a user line as follows:</para>
+						clients, assuming <option>allow_anonymous</option> is
+						true. User specific topic ACLs are added after a user
+						line as follows:</para>
 
 					<para><code>user &lt;username&gt;</code></para>
 
 					<para>The username referred to here is the same as in
-					password_file. It is not the clientid.</para>
+						<option>password_fil</option>e. It is not the
+						clientid.</para>
 
 					<para>It is also possible to define ACLs based on pattern
-					substitution within the topic. The form is the same as for
-					the topic keyword, but using pattern as the keyword.</para>
+						substitution within the topic. The form is the same as
+						for the topic keyword, but using pattern as the
+						keyword.</para>
 					<para><code>pattern [read|write] &lt;topic&gt;</code></para>
 					
 					<para>The patterns available for substition are:</para>
 						<listitem><para>%u to match the username of the client</para></listitem>
 					</itemizedlist>
 					<para>The substitution pattern must be the only text for
-					that level of hierarchy. Pattern ACLs apply to all users
-					even if the "user" keyword has previously been
-					given.</para>
+						that level of hierarchy. Pattern ACLs apply to all
+						users even if the "user" keyword has previously been
+						given.</para>
 
 					<para>Example:</para>
 					<para><code>pattern write sensor/%u/data</code></para>
 					<para>If the first character of a line of the ACL file is a
 						# it is treated as a comment.</para>
 
-					<para>Reloaded on reload signal. The currently loaded ACLs will be
-					freed and reloaded. Existing subscriptions will be affected
-					after the reload.</para>
+					<para>Reloaded on reload signal. The currently loaded ACLs
+						will be freed and reloaded. Existing subscriptions will
+						be affected after the reload.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>allow_anonymous</option> [ true | false ]</term>
 				<listitem>
 					<para>Boolean value that determines whether clients that
-					connect without providing a username are allowed to
-					connect. If set to false then another means of connection
-					should be created to control authenticated client access.
-					Defaults to true.</para>
+						connect without providing a username are allowed to
+						connect. If set to <replaceable>false</replaceable>
+						then another means of connection should be created to
+						control authenticated client access.  Defaults to
+						<replaceable>true</replaceable>.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 						be useful if you have a large number of clients
 						subscribed to the same set of topics and want to
 						minimise memory usage.</para>
-					<para>It can be safely set to true if you know in advance
+					<para>It can be safely set to
+						<replaceable>true</replaceable> if you know in advance
 						that your clients will never have overlapping
 						subscriptions, otherwise your clients must be able to
 						correctly deal with duplicate messages even when then
 						have QoS=2.</para>
-					<para>Defaults to true.</para>
+					<para>Defaults to <replaceable>true</replaceable>.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</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>
+						and access control. This allows custom
+						username/password and access control functions to be
+						created.</para>
 					<para>Not currently reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>autosave_interval</option> <replaceable>seconds</replaceable></term>
 				<listitem>
-					<para>The number of seconds that mosquitto will wait 
-					between each time it saves the in-memory database to 
-					disk. If set to 0, the in-memory database will only
-					be saved when mosquitto exits or when receiving the 
-					SIGUSR1 signal. Note that this setting only has an 
-					effect if persistence is enabled.  Defaults to 1800 
-					seconds (30 minutes).</para>
+					<para>The number of seconds that mosquitto will wait
+						between each time it saves the in-memory database to
+						disk. If set to 0, the in-memory database will only be
+						saved when mosquitto exits or when receiving the
+						SIGUSR1 signal. Note that this setting only has an
+						effect if persistence is enabled.  Defaults to 1800
+						seconds (30 minutes).</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
-				<term><option>autosave_on_changes</option> <replaceable>seconds</replaceable></term>
+				<term><option>autosave_on_changes</option> [ true | false ]</term>
 				<listitem>
-					<para>If true, mosquitto will count the number of
-					subscription changes, retained messages received and queued
-					messages and if the total exceeds autosave_interval then
-					the in-memory database will be saved to disk. If false,
-					mosquitto will save the in-memory database to disk by
-					treating autosave_interval as a time in seconds.</para>
+					<para>If <replaceable>true</replaceable>, mosquitto will
+						count the number of subscription changes, retained
+						messages received and queued messages and if the total
+						exceeds <option>autosave_interval</option> then the
+						in-memory database will be saved to disk. If
+						<replaceable>false</replaceable>, mosquitto will save
+						the in-memory database to disk by treating
+						<option>autosave_interval</option> as a time in
+						seconds.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>clientid_prefixes</option> <replaceable>prefix</replaceable></term>
 				<listitem>
 					<para>If defined, only clients that have a clientid with a
-					prefix that matches clientid_prefixes will be allowed to
-					connect to the broker. For example, setting "secure-" here
-					would mean a client "secure-client" could connect but
-					another with clientid "mqtt" couldn't. By default, all
-					client ids are valid.</para>
-					<para>Reloaded on reload signal. Note that currently connected
-					clients will be unaffected by any changes.</para>
+						prefix that matches clientid_prefixes will be allowed
+						to connect to the broker. For example, setting
+						"secure-" here would mean a client "secure-client"
+						could connect but another with clientid "mqtt"
+						couldn't. By default, all client ids are valid.</para>
+					<para>Reloaded on reload signal. Note that currently
+						connected clients will be unaffected by any
+						changes.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
-				<term><option>connection_messages</option> &lt; true | false &gt;</term>
+				<term><option>connection_messages</option> [ true | false ]</term>
 				<listitem>
-					<para>If set to true, the log will include entries when
-					clients connect and disconnect. If set to false, these
-					entries will not appear.</para>
+					<para>If set to <replaceable>true</replaceable>, the log
+						will include entries when clients connect and
+						disconnect. If set to <replaceable>false</replaceable>,
+						these entries will not appear.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 						will be closed and reopened when the broker receives a
 						HUP signal. Only a single file destination may be
 						configured.</para>
-					<para>Use "log_dest none" if you wish to
-					disable logging. Defaults to stderr. This option
-					may be specified multiple times.</para>
+					<para>Use "log_dest none" if you wish to disable logging.
+						Defaults to stderr. This option may be specified
+						multiple times.</para>
 					<para>Note that if the broker is running as a Windows
 						service it will default to "log_dest none" and neither
 						stdout nor stderr logging is available.</para>
 			<varlistentry>
 				<term><option>log_timestamp</option> [ true | false ]</term>
 				<listitem>
-					<para>Boolean value, if set to true a timestamp value will
-					be added to each log entry. The default is true.</para>
+					<para>Boolean value, if set to
+						<replaceable>true</replaceable> a timestamp value will
+						be added to each log entry. The default is
+						<replaceable>true</replaceable>.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>log_type</option> <replaceable>types</replaceable></term>
 				<listitem>
 					<para>Choose types of messages to log. Possible types are:
-					debug, error, warning, notice, information, none, all.
-					Defaults to error, warning, notice and information. This
-					option may be specified multiple times. Note that the debug
-					type (used for decoding incoming/outgoing network packets)
-					is never logged in topics.</para>
+						<replaceable>debug</replaceable>,
+						<replaceable>error</replaceable>,
+						<replaceable>warning</replaceable>,
+						<replaceable>notice</replaceable>,
+						<replaceable>information</replaceable>,
+						<replaceable>none</replaceable>,
+						<replaceable>all</replaceable>.  Defaults to
+						<replaceable>error</replaceable>,
+						<replaceable>warning</replaceable>, <replaceable>notice
+						</replaceable>and
+						<replaceable>information</replaceable>.  This option
+						may be specified multiple times. Note that the
+						<replaceable>debug </replaceable>type (used for
+						decoding incoming/outgoing network packets) is never
+						logged in topics.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>max_inflight_messages</option> <replaceable>count</replaceable></term>
 				<listitem>
 					<para>The maximum number of QoS 1 or 2 messages that can be
-					in the process of being transmitted simultaneously.  This
-					includes messages currently going through handshakes and
-					messages that are being retried. Defaults to 20. Set to 0
-					for no maximum. If set to 1, this will guarantee in-order
-					delivery of messages.</para>
+						in the process of being transmitted simultaneously.
+						This includes messages currently going through
+						handshakes and messages that are being retried.
+						Defaults to 20. Set to 0 for no maximum. If set to 1,
+						this will guarantee in-order delivery of
+						messages.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>max_queued_messages</option> <replaceable>count</replaceable></term>
 				<listitem>
 					<para>The maximum number of QoS 1 or 2 messages to hold in
-					the queue above those messages that are currently in
-					flight. Defaults to 100. Set to 0 for no maximum (not
-					recommended). See also the queue_qos0_messages option.</para>
+						the queue above those messages that are currently in
+						flight. Defaults to 100. Set to 0 for no maximum (not
+						recommended). See also the
+						<option>queue_qos0_messages</option> option.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>password_file</option> <replaceable>file path</replaceable></term>
 				<listitem>
 					<para>Set the path to a password file. If defined, the
-					contents of the file are used to control client access to
-					the broker. The file can be created using the
-					<citerefentry><refentrytitle>mosquitto_passwd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-					utility. If mosquitto is compiled without TLS support (it
-					is recommended that TLS support is included), then the
-					password file should be a text file with each line in the
-					format "username:password", where the colon and password
-					are optional but recommended. If allow_anonymous is set to
-					false, only users defined in this file will be able to
-					connect. Setting allow_anonymous to true when password_file
-					is defined is valid and could be used with acl_file to have
-					e.g. read only guest/anonymous accounts and defined users
-					that can publish.</para>
-					<para>Reloaded on reload signal. The currently loaded username and
-					password data will be freed and reloaded. Clients that are
-					already connected will not be affected.</para>
+						contents of the file are used to control client access
+						to the broker. The file can be created using the
+						<citerefentry><refentrytitle>mosquitto_passwd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+						utility. If mosquitto is compiled without TLS support
+						(it is recommended that TLS support is included), then
+						the password file should be a text file with each line
+						in the format "username:password", where the colon and
+						password are optional but recommended. If
+						<option>allow_anonymous</option> is set to
+						<replaceable>false</replaceable>, only users defined in
+						this file will be able to connect. Setting
+						<option>allow_anonymous</option> to
+						<replaceable>true</replaceable> when
+						<replaceable>password_file</replaceable>is defined is
+						valid and could be used with acl_file to have e.g. read
+						only guest/anonymous accounts and defined users that
+						can publish.</para>
+					<para>Reloaded on reload signal. The currently loaded
+						username and password data will be freed and reloaded.
+						Clients that are already connected will not be
+						affected.</para>
 					<para>See also
 						<citerefentry><refentrytitle>mosquitto_passwd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 				</listitem> </varlistentry>
 			<varlistentry>
 				<term><option>persistence</option> [ true | false ]</term>
 				<listitem>
-					<para>Can be true or false. If true, connection,
-					subscription and message data will be written to the disk
-					in mosquitto.db at the location dictated by
-					persistence_location. When mosquitto is restarted, it will
-					reload the information stored in mosquitto.db. The data
-					will be written to disk when mosquitto closes and also at
-					periodic intervals as defined by autosave_interval. Writing
-					of the persistence database may also be forced by sending
-					mosquitto the SIGUSR1 signal. If false, the data will be
-					stored in memory only. Defaults to false.</para>
+					<para>If <replaceable>true</replaceable>, connection,
+						subscription and message data will be written to the
+						disk in mosquitto.db at the location dictated by
+						persistence_location. When mosquitto is restarted, it
+						will reload the information stored in mosquitto.db. The
+						data will be written to disk when mosquitto closes and
+						also at periodic intervals as defined by
+						autosave_interval. Writing of the persistence database
+						may also be forced by sending mosquitto the SIGUSR1
+						signal. If <replaceable>false</replaceable>, the data
+						will be stored in memory only. Defaults to
+						<replaceable>false</replaceable>.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>persistence_file</option> <replaceable>file name</replaceable></term>
 				<listitem>
-					<para>The filename to use for the persistent database. Defaults to mosquitto.db.</para>
+					<para>The filename to use for the persistent database.
+						Defaults to mosquitto.db.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>persistence_location</option> <replaceable>path</replaceable></term>
 				<listitem>
 					<para>The path where the persistence database should be
-					stored. Must end in a trailing slash. If not given, then
-					the current directory is used.</para>
+						stored. Must end in a trailing slash. If not given,
+						then the current directory is used.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>persistent_client_expiration</option> <replaceable>duration</replaceable></term>
 				<listitem>
 					<para>This option allows persistent clients (those with
-					clean session set to false) to be removed if they do not
-					reconnect within a certain time frame. This is a
-					non-standard option. As far as the MQTT spec is concerned,
-					persistent clients persist forever.</para>
+						clean session set to false) to be removed if they do
+						not reconnect within a certain time frame. This is a
+						non-standard option. As far as the MQTT spec is
+						concerned, persistent clients persist forever.</para>
 					<para>Badly designed clients may set clean session to false
-					whilst using a randomly generated client id. This leads to
-					persistent clients that will never reconnect. This option
-					allows these clients to be removed.</para>
+						whilst using a randomly generated client id. This leads
+						to persistent clients that will never reconnect. This
+						option allows these clients to be removed.</para>
 					<para>The expiration period should be an integer followed
-					by one of d w m y for day, week, month and year
-					respectively. For example:</para>
+						by one of d w m y for day, week, month and year
+						respectively. For example:</para>
 					<itemizedlist mark="circle">
 						<listitem><para>persistent_client_expiration 2m</para></listitem>
 						<listitem><para>persistent_client_expiration 14d</para></listitem>
 						<listitem><para>persistent_client_expiration 1y</para></listitem>
 					</itemizedlist>
 					<para>As this is a non-standard option, the default if not
-					set is to never expire persistent clients.</para>
+						set is to never expire persistent clients.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>pid_file</option> <replaceable>file path</replaceable></term>
 				<listitem>
 					<para>Write a pid file to the file specified. If not given
-					(the default), no pid file will be written. If the pid file
-					cannot be written, mosquitto will exit. This option only
-					has an effect is mosquitto is run in daemon mode.</para>
+						(the default), no pid file will be written. If the pid
+						file cannot be written, mosquitto will exit. This
+						option only has an effect is mosquitto is run in daemon
+						mode.</para>
 					<para>If mosquitto is being automatically started by an
-					init script it will usually be required to write a pid
-					file. This should then be configured as
-					/var/run/mosquitto.pid</para>
+						init script it will usually be required to write a pid
+						file. This should then be configured as e.g.
+						/var/run/mosquitto.pid</para>
 					<para>Not reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 						format "identity:key", where the key is a hexadecimal
 						string with no leading "0x". A client connecting to a
 						listener that has PSK support enabled must provide a
-						matching identity and PSK to allow the encrypted connection to proceed.</para>
+						matching identity and PSK to allow the encrypted
+						connection to proceed.</para>
 					<para>Reloaded on reload signal. The currently loaded
 						identity and key data will be freed and reloaded.
 						Clients that are already connected will not be
 			<varlistentry>
 				<term><option>queue_qos0_messages</option> [ true | false ]</term>
 				<listitem>
-					<para>Set to true to queue messages with QoS 0 when a
-					persistent client is disconnected. These messages are
-					included in the limit imposed by max_queued_messages.
-					Defaults to false.</para>
+					<para>Set to <replaceable>true</replaceable> to queue
+						messages with QoS 0 when a persistent client is
+						disconnected. These messages are included in the limit
+						imposed by max_queued_messages.  Defaults to
+						<replaceable>false</replaceable>.</para>
 					<para>Note that the MQTT v3.1 spec states that only QoS 1
-					and 2 messages should be saved in this situation so this is
-					a non-standard option.</para>
+						and 2 messages should be saved in this situation so
+						this is a non-standard option.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>retained_persistence</option> [ true | false ]</term>
 				<listitem>
 					<para>This is a synonym of the <option>persistence</option>
-					option.</para>
+						option.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>retry_interval</option> <replaceable>seconds</replaceable></term>
 				<listitem>
 					<para>The integer number of seconds after a QoS=1 or QoS=2
-					message has been sent that mosquitto will wait before
-					retrying when no response is received. If unset, defaults
-					to 20 seconds.</para>
+						message has been sent that mosquitto will wait before
+						retrying when no response is received. If unset,
+						defaults to 20 seconds.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>store_clean_interval</option> <replaceable>seconds</replaceable></term>
 				<listitem>
 					<para>The integer number of seconds between the internal
-					message store being cleaned of messages that are no longer
-					referenced.  Lower values will result in lower memory usage
-					but more processor time, higher values will have the
-					opposite effect. Setting a value of 0 means the
-					unreferenced messages will be disposed of as quickly as
-					possible. Defaults to 10 seconds.</para>
+						message store being cleaned of messages that are no
+						longer referenced.  Lower values will result in lower
+						memory usage but more processor time, higher values
+						will have the opposite effect. Setting a value of 0
+						means the unreferenced messages will be disposed of as
+						quickly as possible. Defaults to 10 seconds.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>sys_interval</option> <replaceable>seconds</replaceable></term>
 				<listitem>
 					<para>The integer number of seconds between updates of the
-					$SYS subscription hierarchy, which provides status
-					information about the broker. If unset, defaults to 10
-					seconds.</para>
+						$SYS subscription hierarchy, which provides status
+						information about the broker. If unset, defaults to 10
+						seconds.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 					<para>The MQTT specification requires that the QoS of a
 						message delivered to a subscriber is never upgraded to
 						match the QoS of the subscription. Enabling this option
-						changes this behaviour. If upgrade_outgoing_qos is set
-						true, messages sent to a subscriber will always match
-						the QoS of its subscription. This is a non-standard
-						option not provided for by the spec. Defaults to
-						false.</para>
+						changes this behaviour. If
+						<option>upgrade_outgoing_qos</option> is set
+						<replaceable>true</replaceable>, messages sent to a
+						subscriber will always match the QoS of its
+						subscription. This is a non-standard option not
+						provided for by the spec. Defaults to
+						<replaceable>false</replaceable>.</para>
 					<para>Reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 				<term><option>user</option> <replaceable>username</replaceable></term>
 				<listitem>
 					<para>When run as root, change to this user and its primary
-					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 a non-root user,
-					this setting has no effect. Defaults to mosquitto.</para>
+						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
+						a non-root user, this setting has no effect. Defaults
+						to mosquitto.</para>
 					<para>This setting has no effect on Windows and so you
-					should run mosquitto as the user you wish it to run
-					as.</para>
+						should run mosquitto as the user you wish it to run
+						as.</para>
 					<para>Not reloaded on reload signal.</para>
 				</listitem>
 			</varlistentry>
 					<term><option>bind_address</option> <replaceable>address</replaceable></term>
 					<listitem>
 						<para>Listen for incoming network connections on the
-						specified IP address/hostname only. This is useful 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.</para>
+							specified IP address/hostname only. This is useful
+							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.</para>
 						<para>Not reloaded on reload signal.</para>
 					</listitem>
 				</varlistentry>
 					<term><option>listener</option> <replaceable>port</replaceable></term>
 					<listitem>
 						<para>Listen for incoming network connection on the
-						specified port. A second optional argument allows the
-						listener to be bound to a specific ip address/hostname. If
-						this variable is used and neither bind_address nor port are
-						used then the default listener will not be started. This
-						option may be specified multiple times. See also the
-						mount_point option.</para>
+							specified port. A second optional argument allows
+							the listener to be bound to a specific ip
+							address/hostname. If this variable is used and
+							neither <option>bind_address</option> nor
+							<option>port</option> are used then the default
+							listener will not be started. This option may be
+							specified multiple times. See also the
+							<option>mount_point</option> option.</para>
 						<para>Not reloaded on reload signal.</para>
 					</listitem>
 				</varlistentry>
 				<varlistentry>
 					<term><option>max_connections</option> <replaceable>count</replaceable></term>
 					<listitem>
-						<para>Limit the total number of clients connected for the
-						current listener. Set to <literal>-1</literal> to have
-						"unlimited" connections. Note that other limits may be
-						imposed that are outside the control of mosquitto.  See
-						e.g.
-						<citerefentry><refentrytitle>limits.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+						<para>Limit the total number of clients connected for
+							the current listener. Set to <literal>-1</literal>
+							to have "unlimited" connections. Note that other
+							limits may be imposed that are outside the control
+							of mosquitto.  See e.g.
+							<citerefentry><refentrytitle>limits.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 						<para>Not reloaded on reload signal.</para>
 					</listitem>
 				</varlistentry>
 					<term><option>mount_point</option> <replaceable>topic prefix</replaceable></term>
 					<listitem>
 						<para>This option is used with the listener option to
-						isolate groups of clients. When a client connects to a
-						listener which uses this option, the string argument is
-						attached to the start of all topics for this client. This
-						prefix is removed when any messages are sent to the client.
-						This means a client connected to a listener with mount
-						point <option>example</option> can only see messages that
-						are published in the topic hierarchy
-						<option>example</option> and above.</para>
+							isolate groups of clients. When a client connects
+							to a listener which uses this option, the string
+							argument is attached to the start of all topics for
+							this client. This prefix is removed when any
+							messages are sent to the client.  This means a
+							client connected to a listener with mount point
+							<replaceable>example</replaceable> can only see
+							messages that are published in the topic hierarchy
+							<replaceable>example</replaceable> and above.</para>
 						<para>Not reloaded on reload signal.</para>
 					</listitem>
 				</varlistentry>
 					<term><option>port</option> <replaceable>port number</replaceable></term>
 					<listitem>
 						<para>Set the network port for the default listener to
-						listen on. Defaults to 1883.</para>
+							listen on. Defaults to 1883.</para>
 						<para>Not reloaded on reload signal.</para>
 					</listitem>
 				</varlistentry>
 					<term><option>cafile</option> <replaceable>file path</replaceable></term>
 					<listitem>
 						<para>At least one of <option>cafile</option> or
-							<option>capath</option> must be provided to allow SSL
-							support.</para>
-						<para>cafile is used to define the path to a file
-							containing the PEM encoded CA certificates that are
-							trusted.</para>
+							<option>capath</option> must be provided to allow
+							SSL support.</para>
+						<para><option>cafile</option> is used to define the
+							path to a file containing the PEM encoded CA
+							certificates that are trusted.</para>
 					</listitem>
 				</varlistentry>
 				<varlistentry>
 					<term><option>capath</option> <replaceable>directory path</replaceable></term>
 					<listitem>
 						<para>At least one of <option>cafile</option> or
-							<option>capath</option> must be provided to allow SSL
-							support.</para>
-						<para>capath is used to define a directory that contains
-							PEM encoded CA certificates that are trusted. For
-							capath to work correctly, the certificates files
-							must have ".crt" as the file ending and you must
-							run "c_rehash &lt;path to capath&gt;" each time you
+							<option>capath</option> must be provided to allow
+							SSL support.</para>
+						<para><option>capath</option> is used to define a
+							directory that contains PEM encoded CA certificates
+							that are trusted. For <option>capath</option> to
+							work correctly, the certificates files must have
+							".pem" as the file ending and you must run
+							"c_rehash &lt;path to capath&gt;" each time you
 							add/remove a certificate.</para>
 					</listitem>
 				</varlistentry>
 				<varlistentry>
 					<term><option>require_certificate</option> [ true | false ]</term>
 					<listitem>
-						<para>By default an SSL/TLS enabled listener will operate in a
-							similar fashion to a https enabled web server, in that
-							the server has a certificate signed by a CA and the
-							client will verify that it is a trusted certificate.
-							The overall aim is encryption of the network traffic.
-							By setting require_certificate 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.</para>
+						<para>By default an SSL/TLS enabled listener will
+							operate in a similar fashion to a https enabled web
+							server, in that the server has a certificate signed
+							by a CA and the client will verify that it is a
+							trusted certificate.  The overall aim is encryption
+							of the network traffic.  By setting
+							<option>require_certificate</option> to
+							<replaceable>true</replaceable>, 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.</para>
 					</listitem>
 				</varlistentry>
 				<varlistentry>
 					<term><option>use_identity_as_username</option> [ true | false ]</term>
 					<listitem>
-						<para>If require_certificate is true, you may set
-							use_identity_as_username to true to use the CN value from the
-							client certificate as a username. If this is true, the
-							password_file option will not be used for this
-							listener.</para>
+						<para>If <option>require_certificate</option> is
+							<replaceable>true</replaceable>, you may set
+							<option>use_identity_as_username</option> to
+							<replaceable>true</replaceable> to use the CN value
+							from the client certificate as a username. If this
+							is <replaceable>true</replaceable>, the
+							<option>password_file</option> option will not be
+							used for this listener.</para>
 					</listitem>
 				</varlistentry>
 				<varlistentry>
 					<term><option>crlfile</option> <replaceable>file path</replaceable></term>
 					<listitem>
-						<para>If you have require_certificate set to true, you can
+						<para>If you have <option>require_certificate</option>
+							set to <replaceable>true</replaceable>, you can
 							create a certificate revocation list file to revoke
-							access to particular client certificates. If you have
-							done this, use crlfile to point to the PEM encoded
-							revocation file.</para>
+							access to particular client certificates. If you
+							have done this, use crlfile to point to the PEM
+							encoded revocation file.</para>
 					</listitem>
 				</varlistentry>
 			</variablelist>
 				<varlistentry>
 					<term><option>psk_hint</option> <replaceable>hint</replaceable></term>
 					<listitem>
-						<para>The psk_hint option enables pre-shared-key
-							support for this listener and also acts as an
-							identifier for this listener. The hint is sent to
-							clients and may be used locally to aid
+						<para>The <option>psk_hint</option> option enables
+							pre-shared-key support for this listener and also
+							acts as an identifier for this listener. The hint
+							is sent to clients and may be used locally to aid
 							authentication. The hint is a free form string that
 							doesn't have much meaning in itself, so feel free
 							to be creative.</para>
 						<para>If this option is provided, see
-							psk_file to define the pre-shared keys to be used
-							or create a security plugin to handle them.</para>
+							<option>psk_file</option> to define the pre-shared
+							keys to be used or create a security plugin to
+							handle them.</para>
 					</listitem>
 				</varlistentry>
 				<varlistentry>
 					<term><option>use_identity_as_username</option> [ true | false ]</term>
 					<listitem>
-						<para>Set use_identity_as_username to have the psk
-							identity sent by the client used as its username.
-							The username will be checked as normal, so
-							password_file or another means of authentication
-							checking must be used. No password will be
-							used.</para>
+						<para>Set <option>use_identity_as_username</option> to
+							have the psk identity sent by the client used as
+							its username.  The username will be checked as
+							normal, so <option>password_file</option> or
+							another means of authentication checking must be
+							used. No password will be used.</para>
 					</listitem>
 				</varlistentry>
 				<varlistentry>
 						<para>When using PSK, the encryption ciphers used will
 							be chosen from the list of available PSK ciphers.
 							If you want to control which ciphers are available,
-							use the "ciphers" option.  The list of available
-							ciphers can be optained using the "openssl ciphers"
-							command and should be provided in the same format
-							as the output of that command.</para>
+							use this option.  The list of available ciphers can
+							be optained using the "openssl ciphers" command and
+							should be provided in the same format as the output
+							of that command.</para>
 					</listitem>
 				</varlistentry>
 			</variablelist>
 				<term><option>addresses</option> <replaceable>address[:port]</replaceable> <replaceable>[address[:port]]</replaceable></term>
 				<listitem>
 					<para>Specify the address and optionally the port of the
-					bridge to connect to. This must be given for each bridge
-					connection. If the port is not specified, the default of
-					1883 is used.</para>
+						bridge to connect to. This must be given for each
+						bridge connection. If the port is not specified, the
+						default of 1883 is used.</para>
 					<para>Multiple host addresses can be specified on the
 						address config. See the <option>round_robin</option>
 						option for more details on the behaviour of bridges
 				<term><option>cleansession</option> [ true | false ]</term>
 				<listitem>
 					<para>Set the clean session option for this bridge. Setting
-					to false (the default), means that all subscriptions on the
-					remote broker are kept in case of the network connection
-					dropping. If set to true, all subscriptions and messages on
-					the remote broker will be cleaned up if the connection
-					drops. Note that setting to true may cause a large amount
-					of retained messages to be sent each time the bridge
-					reconnects.</para>
-					<para>If you are using bridges with cleansession set to false
-					(the default), then you may get unexpected behaviour from
-					incoming topics if you change what topics you are
-					subscribing to. This is because the remote broker keeps the
-					subscription for the old topic. If you have this problem,
-					connect your bridge with cleansession set to true, then
-					reconnect with cleansession set to false as normal.</para>
+						to <replaceable>false</replaceable> (the default),
+						means that all subscriptions on the remote broker are
+						kept in case of the network connection dropping. If set
+						to <replaceable>true</replaceable>, all subscriptions
+						and messages on the remote broker will be cleaned up if
+						the connection drops. Note that setting to
+						<replaceable>true</replaceable> may cause a large
+						amount of retained messages to be sent each time the
+						bridge reconnects.</para>
+					<para>If you are using bridges with
+						<option>cleansession</option> set to
+						<replaceable>false</replaceable> (the default), then
+						you may get unexpected behaviour from incoming topics
+						if you change what topics you are subscribing to. This
+						is because the remote broker keeps the subscription for
+						the old topic.  If you have this problem, connect your
+						bridge with <option>cleansession</option> set to
+						<replaceable>true</replaceable>, then reconnect with
+						cleansession set to <replaceable>false</replaceable> as
+						normal.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>clientid</option> <replaceable>id</replaceable></term>
 				<listitem>
 					<para>Set the client id for this bridge connection. If not
-					defined, this defaults to 'name.hostname', where name is
-					the connection name and hostname is the hostname of this
-					computer.</para>
+						defined, this defaults to 'name.hostname', where name
+						is the connection name and hostname is the hostname of
+						this computer.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>connection</option> <replaceable>name</replaceable></term>
 				<listitem>
 					<para>This variable marks the start of a new bridge
-					connection. It is also used to give the bridge a
-					name which is used as the client id on the remote
-					broker.</para>
+						connection. It is also used to give the bridge a name
+						which is used as the client id on the remote
+						broker.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>keepalive_interval</option> <replaceable>seconds</replaceable></term>
 				<listitem>
 					<para>Set the number of seconds after which the bridge
-					should send a ping if no other traffic has occurred.
-					Defaults to 60. A minimum value of 5 seconds
-					isallowed.</para>
+						should send a ping if no other traffic has occurred.
+						Defaults to 60. A minimum value of 5 seconds
+						isallowed.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>idle_timeout</option> <replaceable>seconds</replaceable></term>
 				<listitem>
 					<para>Set the amount of time a bridge using the lazy start
-					type must be idle before it will be stopped. Defaults to
-					60 seconds.</para>
+						type must be idle before it will be stopped. Defaults
+						to 60 seconds.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>notifications</option> [ true | false ]</term>
 				<listitem>
-					<para>If set to true, publish notification messages to the
-					local and remote brokers giving information about the state
-					of the bridge connection. Retained messages are published
-					to the topic $SYS/broker/connection/&lt;clientid&gt;/state
-					unless otherwise set with notification_topics.  If the
-					message is 1 then the connection is active, or 0 if the
-					connection has failed. Defaults to true.</para>
+					<para>If set to <replaceable>true</replaceable>, publish
+						notification messages to the local and remote brokers
+						giving information about the state of the bridge
+						connection. Retained messages are published to the
+						topic $SYS/broker/connection/&lt;clientid&gt;/state
+						unless otherwise set with
+						<option>notification_topic</option>s.  If the message
+						is 1 then the connection is active, or 0 if the
+						connection has failed. Defaults to
+						<replaceable>true</replaceable>.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 					<para>Choose the topic on which notifications will be
 						published for this bridge. If not set the messages will
 						be sent on the topic
-						$SYS/bridge/connection/&lt;clientid&gt;/state.</para>
+						$SYS/broker/connection/&lt;clientid&gt;/state.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>password</option> <replaceable>value</replaceable></term>
 				<listitem>
 					<para>Configure a password for the bridge. This is used for
-					authentication purposes when connecting to a broker that
-					support MQTT v3.1 and requires a username and/or password
-					to connect. This option is only valid if a username is also
-					supplied.</para>
+						authentication purposes when connecting to a broker
+						that support MQTT v3.1 and requires a username and/or
+						password to connect. This option is only valid if a
+						username is also supplied.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 					<para>If the bridge has more than one address given in the
 						address/addresses configuration, the round_robin option
 						defines the behaviour of the bridge on a failure of the
-						bridge connection. If round_robin is false, the default
-						value, then the first address is treated as the main
-						bridge connection. If the connection fails, the other
+						bridge connection. If round_robin is
+						<replaceable>false</replaceable>, the default value,
+						then the first address is treated as the main bridge
+						connection. If the connection fails, the other
 						secondary addresses will be attempted in turn. Whilst
 						connected to a secondary bridge, the bridge will
 						periodically attempt to reconnect to the main bridge
 						until successful.</para>
-					<para>If round_robin is true, then all addresses are
-						treated as equals. If a connection fails, the next
-						address will be tried and if successful will remain
-						connected until it fails.</para>
+					<para>If round_robin is <replaceable>true</replaceable>,
+						then all addresses are treated as equals. If a
+						connection fails, the next address will be tried and if
+						successful will remain connected until it fails.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>start_type</option> [ automatic | lazy | once ]</term>
 				<listitem>
 					<para>Set the start type of the bridge. This controls how
-					the bridge starts and can be one of three types: automatic,
-					lazy and once. Note that RSMB provides a fourth start type
-					"manual" which isn't currently supported by
-					mosquitto.</para>
+						the bridge starts and can be one of three types:
+						<replaceable>automatic</replaceable>, <replaceable>lazy
+						</replaceable>and <replaceable>once</replaceable>. Note
+						that RSMB provides a fourth start type "manual" which
+						isn't currently supported by mosquitto.</para>
 
-					<para>"automatic" is the default start type and means that
-					the bridge connection will be started automatically when
-					the broker starts and also restarted after a short delay
-					(30 seconds) if the connection fails.</para>
+					<para><replaceable>automatic</replaceable> is the default
+						start type and means that the bridge connection will be
+						started automatically when the broker starts and also
+						restarted after a short delay (30 seconds) if the
+						connection fails.</para>
 
-					<para>Bridges using the "lazy" start type will be started
-					automatically when the number of queued messages exceeds
-					the number set with the "threshold" parameter. It will be
-					stopped automatically after the time set by the
-					"idle_timeout" parameter. Use this start type if you wish
-					the connection to only be active when it is needed.</para>
+					<para>Bridges using the <replaceable>lazy</replaceable>
+						start type will be started automatically when the
+						number of queued messages exceeds the number set with
+						the <option>threshold</option> option. It will be
+						stopped automatically after the time set by the
+						<option>idle_timeout</option> parameter. Use this start
+						type if you wish the connection to only be active when
+						it is needed.</para>
 
-					<para>A bridge using the "once" start type will be started
-					automatically when the broker starts but will not be
-					restarted if the connection fails.</para>
+					<para>A bridge using the <replaceable>once</replaceable>
+						start type will be started automatically when the
+						broker starts but will not be restarted if the
+						connection fails.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>threshold</option> <replaceable>count</replaceable></term>
 				<listitem>
-					<para>Set the number of messages that need to be queued
-					for a bridge with lazy start type to be restarted.
-					Defaults to 10 messages.</para>
+					<para>Set the number of messages that need to be queued for
+						a bridge with lazy start type to be restarted.
+						Defaults to 10 messages.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>topic</option> <replaceable>pattern</replaceable> [[[ out | in | both ] qos-level] local-prefix remote-prefix]</term>
 				<listitem>
 					<para>Define a topic pattern to be shared between the two
-					brokers. Any topics matching the pattern (which may include
-					wildcards) are shared. The second parameter defines the
-					direction that the messages will be shared in, so it is
-					possible to import messages from a remote broker using
-					"in", export messages to a remote broker using "out" or
-					share messages in both directions. If this parameter is not
-					defined, the default of "out" is used. The QoS level
-					defines the publish/subscribe QoS level used for this topic
-					and defaults to 0.</para>
-					<para>The local-prefix and remote-prefix options allow
+						brokers. Any topics matching the pattern (which may
+						include wildcards) are shared. The second parameter
+						defines the direction that the messages will be shared
+						in, so it is possible to import messages from a remote
+						broker using <replaceable>in</replaceable>, export
+						messages to a remote broker using
+						<replaceable>out</replaceable> or share messages in
+						both directions. If this parameter is not defined, the
+						default of <replaceable>out</replaceable> is used. The
+						QoS level defines the publish/subscribe QoS level used
+						for this topic and defaults to 0.</para>
+					<para>The <replaceable>local-prefix</replaceable> and
+						<replaceable>remote-prefix</replaceable> options allow
 						topics to be remapped when publishing to and receiving
 						from remote brokers. This allows a topic tree from the
 						local broker to be inserted into the topic tree of the
 						message is processed, the local prefix will be removed
 						from the topic then the remote prefix added.</para>
 					<para>When using topic mapping, an empty prefix can be
-						defined using the place marker "". Using the empty
-						marker for the topic itself is also valid. The table
-						below defines what combination of empty or value is
+						defined using the place marker
+						<replaceable>""</replaceable>. Using the empty marker
+						for the topic itself is also valid. The table below
+						defines what combination of empty or value is
 						valid.</para>
 					<informaltable>
 						<tgroup cols="5">
 topic # both 2 local/topic/ remote/topic/</programlisting>
 
 					<para>This option can be specified multiple times per
-					bridge.</para>
+						bridge.</para>
 					<para>Care must be taken to ensure that loops are not
-					created with this option. If you are experiencing high CPU
-					load from a broker, it is possible that you have a loop
-					where each broker is forever forwarding each other the same
-					messages.</para>
+						created with this option. If you are experiencing high
+						CPU load from a broker, it is possible that you have a
+						loop where each broker is forever forwarding each other
+						the same messages.</para>
 					<para>See also the <option>cleansession</option> option if
 						you have messages arriving on unexpected topics when
 						using incoming topics.</para>
 			<varlistentry>
 				<term><option>try_private</option> [ true | false ]</term>
 				<listitem>
-					<para>If try_private is set to true, the bridge will
+					<para>If try_private is set to
+						<replaceable>true</replaceable>, the bridge will
 						attempt to indicate to the remote broker that it is a
 						bridge not an ordinary client. If successful, this
 						means that loop detection will be more effective and
 						that retained messages will be propagated correctly.
 						Not all brokers support this feature so it may be
-						necessary to set try_private to false if your bridge
-						does not connect properly.</para>
-					<para>Defaults to true.</para>
+						necessary to set <option>try_private</option> to
+						<replaceable>false</replaceable> if your bridge does
+						not connect properly.</para>
+					<para>Defaults to <replaceable>true</replaceable>.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
 				<term><option>username</option> <replaceable>name</replaceable></term>
 				<listitem>
-					<para>Configure a username for the bridge. This is used for
-					authentication purposes when connecting to a broker that
-					support MQTT v3.1 and requires a username and/or password
-					to connect. See also the password option.</para>
+					<para>Configure a <option>username</option> for the bridge.
+						This is used for authentication purposes when
+						connecting to a broker that support MQTT v3.1 and
+						requires a username and/or password to connect. See
+						also the <option>password</option> option.</para>
 				</listitem>
 			</varlistentry>
 		</variablelist>
 		<refsect2>
 			<title>SSL/TLS Support</title>
-			<para>The following options are available for all listeners to configure SSL/TLS support.</para>
+			<para>The following options are available for all bridges to
+				configure SSL/TLS support.</para>
 			<variablelist>
 				<varlistentry>
 					<term><option>bridge_cafile</option> <replaceable>file path</replaceable></term>
 					<listitem>
 						<para>Pre-shared-key encryption provides an alternative
 							to certificate based encryption. A bridge can be
-							configured to use PSK with the bridge_identity and
-							bridge_psk options.  This is the client identity
-							used with PSK encryption. Only one of certificate
-							and PSK based encryption can be used on one bridge
-							at once.</para>
+							configured to use PSK with the
+							<option>bridge_identity</option> and
+							<option>bridge_psk</option> options.  This is the
+							client identity used with PSK encryption. Only one
+							of certificate and PSK based encryption can be used
+							on one bridge at once.</para>
+					</listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>bridge_insecure</option> [ true | false ]</term>
+					<listitem>
+						<para>When using certificate based TLS, the bridge will
+							attempt to verify the hostname provided in the
+							remote certificate matches the host/address being
+							connected to. This may cause problems in testing
+							scenarios, so <option>bridge_insecure</option> may
+							be set to <replaceable>false</replaceable> to
+							disable the hostname verification.</para>
+						<para>Setting this option to
+							<replaceable>true</replaceable> means that a
+							malicious third party could potentially inpersonate
+							your server, so it should always be set to
+							<replaceable>false</replaceable> in production
+							environments.</para>
 					</listitem>
 				</varlistentry>
 				<varlistentry>
 					<listitem>
 						<para>Pre-shared-key encryption provides an alternative
 							to certificate based encryption. A bridge can be
-							configured to use PSK with the bridge_identity and
-							bridge_psk options.  This is the pre-shared-key in
-							hexadecimal format with no "0x". Only one of
-							certificate and PSK based encryption can be used on
-							one bridge at once.</para>
+							configured to use PSK with the
+							<option>bridge_identity</option> and
+							<option>bridge_psk</option> options.  This is the
+							pre-shared-key in hexadecimal format with no "0x".
+							Only one of certificate and PSK based encryption
+							can be used on one bridge at once.</para>
+					</listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>bridge_tls_version</option> <replaceable>version</replaceable></term>
+					<listitem>
+						<para>Configure the version of the TLS protocol to be
+							used for this bridge. Possible values are
+							<replaceable>tlsv1.2</replaceable>,
+							<replaceable>tlsv1.1</replaceable> and
+							<replaceable>tlsv1</replaceable>. Defaults to
+							<replaceable>tlsv1.2</replaceable>. The remote
+							broker must support the same version of TLS for the
+							connection to succeed.</para>
 					</listitem>
 				</varlistentry>
 			</variablelist>