table of contents
MOSQUITTO.CONF(5) | File formats and conventions | MOSQUITTO.CONF(5) |
NAME¶
mosquitto.conf - the configuration file for mosquittoSYNOPSIS¶
mosquitto.conf
DESCRIPTION¶
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. 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 pathIf 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] <topic>
The access type is controlled using "read", "write" or "readwrite". This parameter is optional (unless <topic> includes a space character) - if not given then the access is read/write. <topic> 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 <username>
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] <topic>
The patterns available for substition are:
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 ]
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 ]
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 ]
See also the auto_id_prefix option.
Reloaded on reload signal.
auth_opt_* value
auth_plugin file path
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 ]
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
Reloaded on reload signal.
autosave_interval seconds
Reloaded on reload signal.
autosave_on_changes [ true | false ]
Reloaded on reload signal.
check_retain_source [ true | false ]
This option applies globally, regardless of the per_listener_settings option.
clientid_prefixes prefix
Reloaded on reload signal. Note that currently connected clients will be unaffected by any changes.
connection_messages [ true | false ]
Reloaded on reload signal.
include_dir dir
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
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/<severity>', 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
log_timestamp [ true | false ]
Reloaded on reload signal.
log_type types
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
Reloaded on reload signal.
max_inflight_messages count
Reloaded on reload signal.
max_queued_bytes count
Reloaded on reload signal.
max_queued_messages count
Reloaded on reload signal.
message_size_limit limit
password_file file path
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 ]
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 ]
Reloaded on reload signal.
persistence_file file name
Reloaded on reload signal.
persistence_location path
Reloaded on reload signal.
persistent_client_expiration duration
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:
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
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
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 ]
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 ]
Reloaded on reload signal.
set_tcp_nodelay [ true | false ]
Reloaded on reload signal.
store_clean_interval seconds
Reloaded on reload signal.
sys_interval seconds
Set to 0 to disable publishing the $SYS hierarchy completely.
Reloaded on reload signal.
upgrade_outgoing_qos [ true | false ]
Reloaded on reload signal.
user username
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 addressNot reloaded on reload signal.
http_dir directory
Not reloaded on reload signal.
listener port [bind address/host]
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
Not reloaded on reload signal.
mount_point topic prefix
Not reloaded on reload signal.
port port number
Not reloaded on reload signal.
protocol value
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 ]
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 ]
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
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
cafile is used to define the path to a file containing the PEM encoded CA certificates that are trusted.
capath directory path
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 <path to capath>" each time you add/remove a certificate.
certfile file path
ciphers cipher:list
crlfile file path
keyfile file path
require_certificate [ true | false ]
tls_version version
use_identity_as_username [ true | false ]
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 ]
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
psk_hint hint
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
use_identity_as_username [ true | false ]
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]]
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 ]
bridge_protocol_version version
cleansession [ true | false ]
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
keepalive_interval seconds
idle_timeout seconds
local_clientid id
local_password password
local_username username
notifications [ true | false ]
notifications_local_only [ true | false ]
notification_topic topic
remote_clientid id
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
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
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
round_robin [ true | false ]
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 ]
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
topic pattern [[[ out | in | both ] qos-level] local-prefix remote-prefix]
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 remapping) | pattern | pattern |
"" | local | remote | valid (remap single local topic to remote) | local | 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 ]
Defaults to true.
SSL/TLS Support¶
The following options are available for all bridges to configure SSL/TLS support.bridge_cafile file path
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
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 <path to bridge_capath>" each time you add/remove a certificate.
bridge_certfile file path
bridge_identity identity
bridge_insecure [ true | false ]
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
bridge_psk key
bridge_tls_version version
FILES¶
mosquitto.confBUGS¶
mosquitto bug information can be found at https://github.com/eclipse/mosquitto/issuesSEE ALSO¶
mosquitto(8), mosquitto_passwd(1), mosquitto-tls(7), mqtt(7), limits.conf(5)AUTHOR¶
Roger Light <roger@atchoo.org>02/14/2019 | Mosquitto Project |