mosquitto

MQTT broker

mosquitto [-c config file] [-d | --daemon] [-p port number] [-v]

-c
--config-file
Load configuration from a file. default in mosquitto.conf(5)
-d
--daemon
background as a daemon.
-p pppp
--port
Listen pppp default 1883. in addition to the setting in config .
Multiple occurances are permitted,This socket will be bound to all network interfaces.
-v
--verbose
equivalent log_type to all in config,

CONFIGURATION

configured using a configuration file as described in mosquitto.conf(5) mosquitto-tls(7).

BROKER STATUS

Clients can find information about the broker by subscribing to topics in the $SYS hierarchy as follows. Topics marked as static are only sent once per client on subscription. All other topics are updated every sys_interval seconds. If sys_interval is 0, then updates are not sent. Note that if you are using a command line client to interact with the $SYS topics and your shell interprets $ as an environment variable, you need to place the topic in single quotes '$SYS/...' or to escape the dollar symbol: \$SYS/... otherwise the $SYS will be treated as an environment variable. $SYS/broker/bytes/received The total number of bytes received since the broker started. $SYS/broker/bytes/sent The total number of bytes sent since the broker started. $SYS/broker/clients/connected, $SYS/broker/clients/active (deprecated) The number of currently connected clients. $SYS/broker/clients/expired The number of disconnected persistent clients that have been expired and removed through the persistent_client_expiration option. $SYS/broker/clients/disconnected, $SYS/broker/clients/inactive (deprecated) The total number of persistent clients (with clean session disabled) that are registered at the broker but are currently disconnected. $SYS/broker/clients/maximum The maximum number of clients that have been connected to the broker at the same time. $SYS/broker/clients/total The total number of active and inactive clients currently connected and registered on the broker. $SYS/broker/connection/# When bridges are configured to/from the broker, common practice is to provide a status topic that indicates the state of the connection. This is provided within $SYS/broker/connection/ by default. If the value of the topic is 1 the connection is active, if 0 then it is not active. See the Bridges section below for more information on bridges. $SYS/broker/heap/current size The current size of the heap memory in use by mosquitto. Note that this topic may be unavailable depending on compile time options. $SYS/broker/heap/maximum size The largest amount of heap memory used by mosquitto. Note that this topic may be unavailable depending on compile time options. $SYS/broker/load/connections/+ The moving average of the number of CONNECT packets received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of connections received in 1 minute, averaged over 1, 5 or 15 minutes. $SYS/broker/load/bytes/received/+ The moving average of the number of bytes received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of bytes received in 1 minute, averaged over 1, 5 or 15 minutes. $SYS/broker/load/bytes/sent/+ The moving average of the number of bytes sent by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of bytes sent in 1 minute, averaged over 1, 5 or 15 minutes. $SYS/broker/load/messages/received/+ The moving average of the number of all types of MQTT messages received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of messages received in 1 minute, averaged over 1, 5 or 15 minutes. $SYS/broker/load/messages/sent/+ The moving average of the number of all types of MQTT messages sent by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of messages send in 1 minute, averaged over 1, 5 or 15 minutes. $SYS/broker/load/publish/dropped/+ The moving average of the number of publish messages dropped by the broker over different time intervals. This shows the rate at which durable clients that are disconnected are losing messages. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of messages dropped in 1 minute, averaged over 1, 5 or 15 minutes. $SYS/broker/load/publish/received/+ The moving average of the number of publish messages received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of publish messages received in 1 minute, averaged over 1, 5 or 15 minutes. $SYS/broker/load/publish/sent/+ The moving average of the number of publish messages sent by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of publish messages sent in 1 minute, averaged over 1, 5 or 15 minutes. $SYS/broker/load/sockets/+ The moving average of the number of socket connections opened to the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of socket connections in 1 minute, averaged over 1, 5 or 15 minutes. $SYS/broker/messages/inflight The number of messages with QoS>0 that are awaiting acknowledgments. $SYS/broker/messages/received The total number of messages of any type received since the broker started. $SYS/broker/messages/sent The total number of messages of any type sent since the broker started. $SYS/broker/publish/messages/dropped The total number of publish messages that have been dropped due to inflight/queuing limits. See the max_inflight_messages and max_queued_messages options in mosquitto.conf(5) for more information. $SYS/broker/publish/messages/received The total number of PUBLISH messages received since the broker started. $SYS/broker/publish/messages/sent The total number of PUBLISH messages sent since the broker started. $SYS/broker/retained messages/count The total number of retained messages active on the broker. $SYS/broker/store/messages/count, $SYS/broker/messages/stored (deprecated) The number of messages currently held in the message store. This includes retained messages and messages queued for durable clients. $SYS/broker/store/messages/bytes The number of bytes currently held by message payloads in the message store. This includes retained messages and messages queued for durable clients. $SYS/broker/subscriptions/count The total number of subscriptions active on the broker. $SYS/broker/version The version of the broker. Static.

WILDCARD TOPIC SUBSCRIPTIONS

In addition to allowing clients to subscribe to specific topics, mosquitto also allows the use of two wildcards in subscriptions. + is the wildcard used to match a single level of hierarchy. For example, for a topic of "a/b/c/d", the following example subscriptions will match: o a/b/c/d o +/b/c/d o a/+/c/d o a/+/+/d o +/+/+/+ The following subscriptions will not match: o a/b/c o b/+/c/d o +/+/+ The second wildcard is # and is used to match all subsequent levels of hierarchy. With a topic of "a/b/c/d", the following example subscriptions will match: o a/b/c/d o # o a/# o a/b/# o a/b/c/# o +/b/c/# The $SYS hierarchy does not match a subscription of "#". If you want to observe the entire $SYS hierarchy, subscribe to $SYS/#. Note that the wildcards must be only ever used on their own, so a subscription of "a/b+/c" is not valid use of a wildcard. The # wildcard must only ever be used as the final character of a subscription.

BRIDGES

Multiple brokers can be connected together with the bridging functionality. This is useful where it is desirable to share information between locations, but where not all of the information needs to be shared. An example could be where a number of users are running a broker to help record power usage and for a number of other reasons. The power usage could be shared through bridging all of the user brokers to a common broker, allowing the power usage of all users to be collected and compared. The other information would remain local to each broker. For information on configuring bridges, see mosquitto.conf(5).

SIGNALS

SIGHUP Upon receiving the SIGHUP signal, mosquitto will attempt to reload configuration file data, assuming that the -c argument was provided when mosquitto was started. Not all configuration parameters can be reloaded without restarting. See mosquitto.conf(5) for details. SIGUSR1 Upon receiving the SIGUSR1 signal, mosquitto will write the persistence database to disk. This signal is only acted upon if persistence is enabled. SIGUSR2 The SIGUSR2 signal causes mosquitto to print out the current subscription tree, along with information about where retained messages exist. This is intended as a testing feature only and may be removed at any time. FILES /etc/mosquitto/mosquitto.conf Configuration file. See mosquitto.conf(5). /var/lib/mosquitto/mosquitto.db Persistent message data storage location if persist enabled. /etc/hosts.allow, /etc/hosts.deny Host access control via tcp-wrappers as described in hosts_access(5). BUGS mosquitto bug information can be found at https://github.com/eclipse/mosquitto/issues SEE ALSO mqtt(7), mosquitto-tls(7), mosquitto.conf(5), hosts_access(5), mosquitto_passwd(1), mosquitto_pub(1), mosquitto_sub(1), libmosquitto(3)

config<.h2> mosquitto.conf - the configuration file for mosquitto mosquitto.conf is the configuration file for mosquitto. This file can reside anywhere as long as mosquitto can read it. By default, mosquitto does not need a configuration file and will use the default values listed below. See mosquitto(8) for information on how to load a configuration file. FILE FORMAT All lines with a # as the very first character are treated as a comment. Configuration lines start with a variable name. The variable value is separated from the name by a single space. AUTHENTICATION The authentication options described below allow a wide range of possibilities in conjunction with the listener options. This section aims to clarify the possibilities. The simplest option is to have no authentication at all. This is the default if no other options are given. Unauthenticated encrypted support is provided by using the certificate based SSL/TLS based options cafile/capath, certfile and keyfile. MQTT provides username/password authentication as part of the protocol. Use the password_file option to define the valid usernames and passwords. Be sure to use network encryption if you are using this option otherwise the username and password will be vulnerable to interception. Use the per_listener_settings to control whether passwords are required globally or on a per-listener basis. When using certificate based encryption there are three options that affect authentication. The first is require_certificate, which may be set to true or false. If false, the SSL/TLS component of the client will verify the server but there is no requirement for the client to provide anything for the server: authentication is limited to the MQTT built in username/password. If require_certificate is true, the client must provide a valid certificate in order to connect successfully. In this case, the second and third options, use_identity_as_username and use_subject_as_username, become relevant. If set to true, use_identity_as_username causes the Common Name (CN) from the client certificate to be used instead of the MQTT username for access control purposes. The password is not used because it is assumed that only authenticated clients have valid certificates. File formats and conventions NAME mosquitto.conf - the configuration file for mosquitto
mosquitto.conf Reside anywhere mosquitto can read Optional. Configuration lines start with a variable name. The variable value is separated from the name by a single space.

AUTHENTICATION

Default none.
if no other options are given. Unauthenticated encrypted support is provided by using the certificate based SSL/TLS based options cafile/capath, certfile and keyfile. username/password authentication as the password_file option to define the valid usernames and passwords. Use network encryption with this to prevent username and password will be vulnerable to interception.
The per_listener_settings controls whether passwords are required globally or on a per-listener basis.

With certificate based encryption

    :
  1. require_certificate true|false, false: the SSL/TLS component of the client will verify the server but there is no requirement for the client to provide anything for the server: authentication is limited to the MQTT built in username/password
    . true: the client must provide a valid certificate in order to connect successfully. In this case, the second and third options, use_identity_as_username and use_subject_as_username become relevant. If set to true, use_identity_as_username causes the Common Name (CN) from the client certificate to be used instead of the MQTT username for access control purposes. The password is not used because it is assumed that only authenticated clients have valid certificates. This means that any CA certificates you include in cafile or capath will be able to issue client certificates that are valid for connecting to your broker. If use_identity_as_username is false, the client must authenticate as normal (if required by password_file) through the MQTT options. The same principle applies for the use_subject_as_username option, but the entire certificate subject is used as the username instead of just the CN.

    When using pre-shared-key based encryption through the psk_hint and psk_file options, the client must provide a valid identity and key in order to connect to the broker before any MQTT communication takes place. If use_identity_as_username is true, the PSK identity is used instead of the MQTT username for access control purposes. If use_identity_as_username is false, the client may still authenticate using the MQTT username/password if using the password_file option.

    Both certificate and PSK based encryption are configured on a per-listener basis. Authentication plugins can be created to augment the password_file, acl_file and psk_file options with e.g. SQL based lookups.

    It is possible to support multiple authentication schemes at once. A config could be created that had a listener for all of the different encryption options described above and hence a large number of ways of authenticating.

    
    GENERAL OPTIONS
           acl_file file path
               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.
    
               If this parameter is defined then only the topics listed will have access. Topic access is added with lines of the format:
    
               topic [read|write|readwrite] 
    
               The access type is controlled using "read", "write" or "readwrite". This parameter is optional (unless  includes a
               space character) - if not given then the access is read/write.  can contain the + or # wildcards as in subscriptions.
    
               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:
    
               user 
    
               The username referred to here is the same as in password_file. It is not the clientid.
    
               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.
    
               pattern [read|write|readwrite] 
    
               The patterns available for substition are:
    
               o   %c to match the client id of the client
    
               o   %u to match the username of the client
    
               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.
    
               Example:
    
               pattern write sensor/%u/data
    
               Allow access for bridge connection messages:
    
               pattern write $SYS/broker/connection/%c/state
    
               If the first character of a line of the ACL file is a # it is treated as a comment.
    
               Reloaded on reload signal. The currently loaded ACLs will be freed and reloaded. Existing subscriptions will be affected
               after the reload.
    
           allow_anonymous [ true | false ]
               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 if no other security options are set. If any other authentication options are set, then allow_anonymous
               defaults to false.
    
               Reloaded on reload signal.
    
           allow_duplicate_messages [ true | false ]
               If a client is subscribed to multiple subscriptions that overlap, e.g. foo/# and foo/+/baz , then MQTT expects that when the
               broker receives a message on a topic that matches both subscriptions, such as foo/bar/baz, then the client should only
               receive the message once.
    
               Mosquitto keeps track of which clients a message has been sent to in order to meet this requirement. This option allows this
               behaviour to be disabled, which may be useful if you have a large number of clients subscribed to the same set of topics and
               want to minimise memory usage.
    
               It can be safely set to true 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.
    
               Defaults to true.
    
               Reloaded on reload signal.
    
           allow_zero_length_clientid [ true | false ]
               MQTT 3.1.1 allows 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 auto_id_prefix option.
    
               Reloaded on reload signal.
    
           auth_opt_* value
               Options to be passed to the auth plugin. See the specific plugin instructions.
    
           auth_plugin 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 password_file, or acl_file are used in the config file alongsize auth_plugin, the plugin checks will run after the build
               in checks.
    
               Not currently reloaded on reload signal.
    
           auth_plugin_deny_special_chars [ true | false ]
               If true then before an ACL check is made, the username/client id of the client needing the check is searched for the presence
               of either a '+' or '#' character. If either of these characters is found in either the username or client id, then the ACL
               check is denied before it is sent to the plugin.
    
               This check prevents the case where a malicious user could circumvent an ACL check by using one of these characters as their
               username or client id. This is the same issue as was reported with mosquitto itself as CVE-2017-7650.
    
               If you are entirely sure that the plugin you are using is not vulnerable to this attack (i.e. if you never use usernames or
               client ids in topics) then you can disable this extra check and hence have all ACL checks delivered to your plugin by setting
               this option to false.
    
               Defaults to true.
    
               Not currently reloaded on reload signal.
    
           auto_id_prefix prefix
               If allow_zero_length_clientid is true, this option allows you to set a string that will be prefixed to the automatically
               generated client ids to aid visibility in logs. Defaults to no prefix.
    
               Reloaded on reload signal.
    
           autosave_interval seconds
               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).
    
               Reloaded on reload signal.
    
           autosave_on_changes [ true | false ]
               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.
    
               Reloaded on reload signal.
    
           check_retain_source [ true | false ]
               This option affects the scenario when a client subscribes to a topic that has retained messages. It is possible that the
               client that published the retained message to the topic had access at the time they published, but that access has been
               subsequently removed. If check_retain_source is set to true, the default, the source of a retained message will be checked
               for access rights before it is republished. When set to false, no check will be made and the retained message will always be
               published.
    
               This option applies globally, regardless of the per_listener_settings option.
    
           clientid_prefixes prefix
               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.
    
               Reloaded on reload signal. Note that currently connected clients will be unaffected by any changes.
    
           connection_messages [ true | false ]
               If set to true, the log will include entries when clients connect and disconnect. If set to false, these entries will not
               appear.
    
               Reloaded on reload signal.
    
           include_dir dir
               External configuration files may be included by using the include_dir option. This defines a directory that will be searched
               for config files. All files that end in '.conf' will be loaded as a configuration file. It is best to have this as the last
               option in the main file. This option will only be processed from the main configuration file. The directory specified must
               not contain the main configuration file.
    
               The configuration files in include_dir are loaded in case sensitive alphabetical order, with the upper case of each letter
               ordered before the lower case of the same letter.
    
               Example Load Order for include_dir.  Given the files b.conf, A.conf, 01.conf, a.conf, B.conf, and 00.conf inside include_dir,
               the config files would be loaded in this order:
    
                   00.conf
                   01.conf
                   A.conf
                   a.conf
                   B.conf
                   b.conf
    
               If this option is used multiple times, then each include_dir option is processed completely in the order that they are
               written in the main configuration file.
    
               Example Load Order for Multiple include_dir.  Assuming a directory one.d containing files B.conf and C.conf, and a second
               directory two.d containing files A.conf and D.conf, and a config:
    
                   include_dir one.d
                   include_dir two.d
    
               Then the config files would be loaded in this order:
    
                   # files from one.d
                   B.conf
                   C.conf
                   # files from two.d
                   A.conf
                   D.conf
    
           log_dest destinations
               Send log messages to a particular destination. Possible destinations are: stdout stderr syslog topic.
    
               stdout and stderr log to the console on the named output.
    
               syslog uses the userspace syslog facility which usually ends up in /var/log/messages or similar and topic logs to the broker
               topic '$SYS/broker/log/', where severity is one of D, E, W, N, I, M which are debug, error, warning, notice,
               information and message. Message type severity is used by the subscribe and unsubscribe log_type options and publishes log
               messages at $SYS/broker/log/M/subscribe and $SYS/broker/log/M/unsubscribe.
    
               The file destination requires an additional parameter which is the file to be logged to, e.g. "log_dest file
               /var/log/mosquitto.log". The file will be closed and reopened when the broker receives a HUP signal. Only a single file
               destination may be configured.
    
               Use "log_dest none" if you wish to disable logging. Defaults to stderr. This option may be specified multiple times.
    
               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.
    
               Reloaded on reload signal.
    
           log_facility local facility
               If using syslog logging (not on Windows), messages will be logged to the "daemon" facility by default. Use the log_facility
               option to choose which of local0 to local7 to log to instead. The option value should be an integer value, e.g. "log_facility
               5" to use local5.
    
           log_timestamp [ true | false ]
               Boolean value, if set to true a timestamp value will be added to each log entry. The default is true.
    
               Reloaded on reload signal.
    
           log_type types
               Choose types of messages to log. Possible types are: debug, error, warning, notice, information, subscribe, unsubscribe,
               websockets, 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.
    
               Reloaded on reload signal.
    
           max_inflight_bytes 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
               max_inflight_messages option.
    
               Reloaded on reload signal.
    
           max_inflight_messages count
               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.
    
               Reloaded on reload signal.
    
           max_queued_bytes count
               QoS 1 and 2 messages above those currently in-flight will be queued (per client) until this limit is exceeded. Defaults to 0.
               (No maximum) See also the max_queued_messages option. If both max_queued_messages and max_queued_bytes are specified, packets
               will be queued until the first limit is reached.
    
               Reloaded on reload signal.
    
           max_queued_messages count
               The maximum number of QoS 1 or 2 messages to hold in the queue (per client) 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 and max_queued_bytes
               options.
    
               Reloaded on reload signal.
    
           message_size_limit limit
               This option sets the maximum publish payload size that the broker will allow. Received messages that exceed this size will
               not be accepted by the broker. The default value is 0, which means that all valid MQTT messages are accepted. MQTT imposes a
               maximum payload size of 268435455 bytes.
    
           password_file file path
               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 mosquitto_passwd(1) 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_fileis 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.
    
               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.
    
               See also mosquitto_passwd(1).
    
           per_listener_settings [ true | false ]
               If true, then authentication and access control settings will be controlled on a per-listener basis. The following options
               are affected:
    
               password_file, acl_file, psk_file, allow_anonymous, allow_zero_length_clientid, auth_plugin, auth_opt_*, auto_id_prefix.
    
               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 it was most recently connected to.
    
               The default behaviour is for this to be set to false, which maintains the settings behaviour from previous versions of
               mosquitto.
    
               Reloaded on reload signal.
    
           persistence [ true | 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.
    
               Reloaded on reload signal.
    
           persistence_file file name
               The filename to use for the persistent database. Defaults to mosquitto.db.
    
               Reloaded on reload signal.
    
           persistence_location path
               The path where the persistence database should be stored. Must end in a trailing slash. If not given, then the current
               directory is used.
    
               Reloaded on reload signal.
    
           persistent_client_expiration duration
               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.
    
               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.
    
               The expiration period should be an integer followed by one of h d w m y for hour, day, week, month and year respectively. For
               example:
    
               o   persistent_client_expiration 2m
    
               o   persistent_client_expiration 14d
    
               o   persistent_client_expiration 1y
    
               As this is a non-standard option, the default if not set is to never expire persistent clients.
    
               Reloaded on reload signal.
    
           pid_file file path
               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.
    
               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 e.g. /var/run/mosquitto.pid
    
               Not reloaded on reload signal.
    
           psk_file file path
               Set the path to a pre-shared-key file. This option requires a listener to be have PSK support enabled. If defined, the
               contents of the file are used to control client access to the broker. Each line should be in the 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.
    
               Reloaded on reload signal. The currently loaded identity and key data will be freed and reloaded. Clients that are already
               connected will not be affected.
    
           queue_qos0_messages [ true | false ]
               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.
    
               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.
    
               Reloaded on reload signal.
    
           retained_persistence [ true | false ]
               This is a synonym of the persistence option.
    
               Reloaded on reload signal.
    
           set_tcp_nodelay [ true | false ]
               If set to true, the TCP_NODELAY option will be set on client sockets to disable Nagle's algorithm. This has the effect of
               reducing latency of some messages at potentially increasing the number of TCP packets being sent. Defaults to false.
    
               Reloaded on reload signal.
    
           store_clean_interval seconds
               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.
    
               Reloaded on reload signal.
    
           sys_interval seconds
               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.
    
               Set to 0 to disable publishing the $SYS hierarchy completely.
    
               Reloaded on reload signal.
    
           upgrade_outgoing_qos [ true | false ]
               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.
    
               Reloaded on reload signal.
    
           user username
               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.
    
               This setting has no effect on Windows and so you should run mosquitto as the user you wish it to run as.
    
               Not reloaded on reload signal.
    
    LISTENERS
           The network ports that mosquitto listens on can be controlled using listeners. The default listener options can be overridden and
           further listeners can be created.
    
       General Options
           bind_address address
               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.
    
               Not reloaded on reload signal.
    
           http_dir directory
               When a listener is using the websockets protocol, it is possible to serve http data as well. Set http_dir to a directory
               which contains the files you wish to serve. If this option is not specified, then no normal http connections will be
               possible.
    
               Not reloaded on reload signal.
    
           listener port [bind address/host]
               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 the global bind_address nor port options are used then the
               default listener will not be started.
    
               The bind address/host option allows this listener to be bound to a specific IP address by passing an IP address or hostname.
               For websockets listeners, it is only possible to pass an IP address here.
    
               This option may be specified multiple times. See also the mount_point option.
    
               Not reloaded on reload signal.
    
           max_connections count
               Limit the total number of clients connected for the current listener. Set to -1 to have "unlimited" connections. Note that
               other limits may be imposed that are outside the control of mosquitto. See e.g.  limits.conf(5).
    
               Not reloaded on reload signal.
    
           mount_point topic prefix
               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 example can only see messages
               that are published in the topic hierarchy example and below.
    
               Not reloaded on reload signal.
    
           port port number
               Set the network port for the default listener to listen on. Defaults to 1883.
    
               Not reloaded on reload signal.
    
           protocol value
               Set the protocol to accept for this listener. Can be mqtt, the default, or websockets if available.
    
               Websockets support is currently disabled by default at compile time. Certificate based TLS may be used with websockets,
               except that only the cafile, certfile, keyfile and ciphers options are supported.
    
               Not reloaded on reload signal.
    
           socket_domain [ ipv4 | ipv6 ]
               By default, a listener will attempt to listen on all supported IP protocol versions. If you do not have an IPv4 or IPv6
               interface you may wish to disable support for either of those protocol versions. In particular, note that due to the
               limitations of the websockets library, it will only ever attempt to open IPv6 sockets if IPv6 support is compiled in, and so
               will fail if IPv6 is not available.
    
               Set to ipv4 to force the listener to only use IPv4, or set to ipv6 to force the listener to only use IPv6. If you want
               support for both IPv4 and IPv6, then do not use the socket_domain option.
    
               Not reloaded on reload signal.
    
           use_username_as_clientid [ true | false ]
               Set use_username_as_clientid to true to replace the clientid that a client connected with with its username. This allows
               authentication to be tied to the clientid, which means that it is possible to prevent one client disconnecting another by
               using the same clientid. Defaults to false.
    
               If a client connects with no username it will be disconnected as not authorised when this option is set to true. Do not use
               in conjunction with clientid_prefixes.
    
               See also use_identity_as_username.
    
               Not reloaded on reload signal.
    
           websockets_log_level level
               Change the websockets logging level. This is a global option, it is not possible to set per listener. This is an integer that
               is interpreted by libwebsockets as a bit mask for its lws_log_levels enum. See the libwebsockets documentation for more
               details.
    
               To use this option, log_type websockets must also be enabled. Defaults to 0.
    
       Certificate based SSL/TLS Support
           The following options are available for all listeners to configure certificate based SSL support. See also "Pre-shared-key based
           SSL/TLS support".
    
           cafile file path
               At least one of cafile or capath must be provided to allow SSL support.
    
               cafile is used to define the path to a file containing the PEM encoded CA certificates that are trusted.
    
           capath directory path
               At least one of cafile or capath must be provided to allow SSL support.
    
               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 ".pem" as the file ending and you must run "openssl rehash " each
               time you add/remove a certificate.
    
           certfile file path
               Path to the PEM encoded server certificate.
    
           ciphers cipher:list
               The list of allowed ciphers, each separated with a colon. Available ciphers can be obtained using the "openssl ciphers"
               command.
    
           crlfile file path
               If you have require_certificate set to true, 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.
    
           keyfile file path
               Path to the PEM encoded keyfile.
    
           require_certificate [ true | false ]
               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.
    
           tls_version version
               Configure the version of the TLS protocol to be used for this listener. Possible values are tlsv1.2, tlsv1.1 and tlsv1. If
               left unset, the default of allowing all of TLS v1.2, v1.1 and v1.0 is used.
    
           use_identity_as_username [ true | false ]
               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.
    
               This takes priority over use_subject_as_username if both are set to true.
    
               See also use_subject_as_username
    
           use_subject_as_username [ true | false ]
               If require_certificate is true, you may set use_subject_as_username to true to use the complete subject value from the client
               certificate as a username. If this is true, the password_file option will not be used for this listener.
    
               The subject will be generated in a form similar to CN=test
               client,OU=Production,O=Server,L=Nottingham,ST=Nottinghamshire,C=GB.
    
               See also use_identity_as_username
    
       Pre-shared-key based SSL/TLS Support
           The following options are available for all listeners to configure pre-shared-key based SSL support. See also "Certificate based
           SSL/TLS support".
    
           ciphers cipher:list
               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 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.
    
           psk_hint hint
               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 authentication. The hint is a free form string that doesn't have much
               meaning in itself, so feel free to be creative.
    
               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.
    
           tls_version version
               Configure the version of the TLS protocol to be used for this listener. Possible values are tlsv1.2, tlsv1.1 and tlsv1. If
               left unset, the default of allowing all of TLS v1.2, v1.1 and v1.0 is used.
    
           use_identity_as_username [ true | false ]
               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.
    
    CONFIGURING BRIDGES
           Multiple bridges (connections to other brokers) can be configured using the following variables.
    
           Bridges cannot currently be reloaded on reload signal.
    
           address address[:port] [address[:port]], addresses address[:port] [address[:port]]
               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.
    
               If you use an IPv6 address, then the port is not optional.
    
               Multiple host addresses can be specified on the address config. See the round_robin option for more details on the behaviour
               of bridges with multiple addresses.
    
           bridge_attempt_unsubscribe [ true | false ]
               If a bridge has topics that have "out" direction, the default behaviour is to send an unsubscribe request to the remote
               broker on that topic. This means that changing a topic direction from "in" to "out" will not keep receiving incoming
               messages. Sending these unsubscribe requests is not always desirable, setting bridge_attempt_unsubscribe to false will
               disable sending the unsubscribe request. Defaults to true.
    
           bridge_protocol_version version
               Set the version of the MQTT protocol to use with for this bridge. Can be one of mqttv31 or mqttv311. Defaults to mqttv31.
    
           cleansession [ true | false ]
               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.
    
               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.
    
           connection name
               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.
    
           keepalive_interval seconds
               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 is allowed.
    
           idle_timeout seconds
               Set the amount of time a bridge using the lazy start type must be idle before it will be stopped. Defaults to 60 seconds.
    
           local_clientid id
               Set the clientid to use on the local broker. If not defined, this defaults to local.. If you are bridging a
               broker to itself, it is important that local_clientid and remote_clientid do not match.
    
           local_password password
               Configure the password to be used when connecting this bridge to the local broker. This may be important when authentication
               and ACLs are being used.
    
           local_username username
               Configure the username to be used when connecting this bridge to the local broker. This may be important when authentication
               and ACLs are being used.
    
           notifications [ true | false ]
               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//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.
    
           notifications_local_only [ true | false ]
               If set to true, only publish notification messages to the local broker giving information about the state of the bridge
               connection. Defaults to false.
    
           notification_topic topic
               Choose the topic on which notifications will be published for this bridge. If not set the messages will be sent on the topic
               $SYS/broker/connection//state.
    
           remote_clientid id
               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.
    
               This replaces the old "clientid" option to avoid confusion with local/remote sides of the bridge. "clientid" remains valid
               for the time being.
    
           remote_password value
               Configure a password for the bridge. This is used for authentication purposes when connecting to a broker that supports MQTT
               v3.1 and up and requires a username and/or password to connect. This option is only valid if a remote_username is also
               supplied.
    
               This replaces the old "password" option to avoid confusion with local/remote sides of the bridge. "password" remains valid
               for the time being.
    
           remote_username name
               Configure a username for the bridge. This is used for authentication purposes when connecting to a broker that supports MQTT
               v3.1 and up and requires a username and/or password to connect. See also the remote_password option.
    
               This replaces the old "username" option to avoid confusion with local/remote sides of the bridge. "username" remains valid
               for the time being.
    
           restart_timeout value
               Set the amount of time a bridge using the automatic start type will wait until attempting to reconnect. Defaults to 30
               seconds.
    
           round_robin [ true | false ]
               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 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.
    
               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.
    
           start_type [ automatic | lazy | once ]
               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.
    
               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.
    
               Bridges using the lazy start type will be started automatically when the number of queued messages exceeds the number set
               with the threshold option. 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.
    
               A bridge using the once start type will be started automatically when the broker starts but will not be restarted if the
               connection fails.
    
           threshold count
               Set the number of messages that need to be queued for a bridge with lazy start type to be restarted. Defaults to 10 messages.
    
           topic pattern [[[ out | in | both ] qos-level] local-prefix remote-prefix]
               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.
    
               The local-prefix and remote-prefix 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 remote broker at an appropriate
               place.
    
               For incoming topics, the bridge will prepend the pattern with the remote prefix and subscribe to the resulting topic on the
               remote broker. When a matching incoming message is received, the remote prefix will be removed from the topic and then the
               local prefix added.
    
               For outgoing topics, the bridge will prepend the pattern with the local prefix and subscribe to the resulting topic on the
               local broker. When an outgoing message is processed, the local prefix will be removed from the topic then the remote prefix
               added.
    
               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 valid. The Full Local Topic and Full
               Remote Topic show the resulting topics that would be used on the local and remote ends of the bridge. For example, for the
               first table row if you publish to L/topic on the local broker, then the remote broker will receive a message on the topic
               R/topic.
    
               +--------+--------------+---------------+---------------------+------------------+-------------------+
               |Pattern | Local Prefix | Remote Prefix | Validity            | Full Local Topic | Full Remote Topic |
               +--------+--------------+---------------+---------------------+------------------+-------------------+
               |pattern | L/           | R/            | valid               | L/pattern        | R/pattern         |
               +--------+--------------+---------------+---------------------+------------------+-------------------+
               |pattern | L/           | ""            | valid               | L/pattern        | pattern           |
               +--------+--------------+---------------+---------------------+------------------+-------------------+
               |pattern | ""           | R/            | valid               | pattern          | R/pattern         |
               +--------+--------------+---------------+---------------------+------------------+-------------------+
               |pattern | ""           | ""            | valid (no           | pattern          | pattern           |
               |        |              |               | remapping)          |                  |                   |
               +--------+--------------+---------------+---------------------+------------------+-------------------+
               |""      | local        | remote        | valid (remap single | local            | remote            |
               |        |              |               | local topic to      |                  |                   |
               |        |              |               | remote)             |                  |                   |
               +--------+--------------+---------------+---------------------+------------------+-------------------+
               |""      | local        | ""            | invalid             |                  |                   |
               +--------+--------------+---------------+---------------------+------------------+-------------------+
               |""      | ""           | remote        | invalid             |                  |                   |
               +--------+--------------+---------------+---------------------+------------------+-------------------+
               |""      | ""           | ""            | invalid             |                  |                   |
               +--------+--------------+---------------+---------------------+------------------+-------------------+
               To remap an entire topic tree, use e.g.:
    
                   topic # both 2 local/topic/ remote/topic/
    
               This option can be specified multiple times per bridge.
    
               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.
    
               See also the cleansession option if you have messages arriving on unexpected topics when using incoming topics.
    
               Example Bridge Topic Remapping.  The configuration below connects a bridge to the broker at test.mosquitto.org. It subscribes
               to the remote topic $SYS/broker/clients/total and republishes the messages received to the local topic
               test/mosquitto/org/clients/total
    
                   connection test-mosquitto-org
                   address test.mosquitto.org
                   cleansession true
                   topic clients/total in 0 test/mosquitto/org $SYS/broker/
    
           try_private [ true | false ]
               If try_private is set to true, 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.
    
               Defaults to true.
    
       SSL/TLS Support
           The following options are available for all bridges to configure SSL/TLS support.
    
           bridge_cafile file path
               One of bridge_cafile or bridge_capath must be provided to allow SSL/TLS support.
    
               bridge_cafile is used to define the path to a file containing the PEM encoded CA certificates that have signed the
               certificate for the remote broker.
    
           bridge_capath file path
               One of bridge_capath or bridge_capath must be provided to allow SSL/TLS support.
    
               bridge_capath is used to define the path to a directory containing the PEM encoded CA certificates that have signed the
               certificate for the remote broker. For bridge_capath to work correctly, the certificate files must have ".crt" as the file
               ending and you must run "openssl rehash " each time you add/remove a certificate.
    
           bridge_certfile file path
               Path to the PEM encoded client certificate for this bridge, if required by the remote broker.
    
           bridge_identity identity
           bridge_identity identity
               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.
    
           bridge_insecure [ true | false ]
               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 bridge_insecure may be set to false to
               disable the hostname verification.
    
               Setting this option to true means that a malicious third party could potentially inpersonate your server, so it should always
               be set to false in production environments.
    
           bridge_keyfile file path
               Path to the PEM encoded private key for this bridge, if required by the remote broker.
    
           bridge_psk key
               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.
    
           bridge_tls_version version
               Configure the version of the TLS protocol to be used for this bridge. Possible values are tlsv1.2, tlsv1.1 and tlsv1.
               Defaults to tlsv1.2. The remote broker must support the same version of TLS for the connection to succeed.
    
    
    SEE ALSO
           mosquitto(8), mosquitto_passwd(1), mosquitto-tls(7), mqtt(7), limits.conf(5)