Quick Guide to The Mosquitto.conf File With Examples

You can configure the mosquitto broker using a configuration file.

The default configuration file is called mosquitto.conf and it is used by the mosquitto broker when started as a Linux daemon or Windows service.

You will find the mosquitto.conf file in the /etc/mosquitto directory on Linux, and in the c:\mosquitto\ directory on Windows.

Note: the Windows install lets you choose the directory.

Important: In order for changes in the mosquitto.conf file to become effective you must restart the mosquitto broker.

However many changes can become effective without restarting the broker and are marked with the comment- Reloaded on reload signal in the manual.

MQTTv5 and MQTT v3.1.1

The mosquitto broker supports both client types and so some of the settings in the configuration file will only affect MQTTv5 clients.

Listeners

It is possible to configure a mosquitto broker to listen on several ports at the same time.

This is very useful if you want your broker to support multiple protocol configurations. The most common are:

1. MQTT
2. MQTT +SSL
3. MQTT +Websockets
4. MQTT + Websockets +SSL

The default configuration uses a default listener which listens on port 1883.

To configure the broker to listen on additional ports you need to create extra listeners.

If you look at the settings you will find that they are divided into sections and some of the settings affect the entire broker instance, whereas others affect a particular listener.

A major change introduced in version 1.5 allowed many configuration settings that were previously global to be made on a per listener basis.

However to maintain backward compatibility this option must first be enabled.

per_listener_settings [ true | false ]

Setting to true will affect the following configuration options.

password_file, acl_file, psk_file, allow_anonymous, allow_zero_length_clientid, auth_plugin, auth_opt_*, auto_id_prefix.

The most important is the ability to configure authentication and access control options on a per listener basis and not globally as was the case pre version 1.5.

Default Settings

All settings have a default setting that is not set in the configuration file but is internal to mosquitto. Settings in the configuration file override these default settings.

Settings Notes

When consulting the Mosquitto.conf manual you will come across two important setting properties. They are:

• Global – This means that they apply to all listeners
• Reloaded on reload signal. – Changes can be implemented while mosquitto is running by using a reload.

Global Settings

These settings are global and generally reloaded on reload signal.

These include logging and file locations. Logging is covered in more detail in the Logging tutorial.

They also cover persistence settings which enable mosquitto to keep messages and status information, like retained messages, across restarts.

per_listener_settings [ true | false ]
allow_anonymous [ true | false ]
persistence [ true | false ]
persistence_file file name
persistence_location path
autosave_interval seconds
retain_available [ true | false ]
user username

The user option allows you to run Mosquitto as a different user (Linux) by default it runs as the use Mosquitto.

Message Restriction Settings

There are a number of messages restriction settings available.

These settings are global settings and affect all listeners. Important ones are:

max_packet_size value
message_size_limit limit -MQTT v5 clients
max_inflight_bytes count
max_inflight_messages count
max_queued_bytes count
max_queued_messages count

Authentication Settings

Allows users to connect without a password or enforces username/password authentication.

This can be configured on a per listener basis if per_listener_settings is true. The default is true provided no other security options are present. If for example a password_file or psk_file is set then it defaults to false.

allow_anonymous — [ true | false ]

Associated with the allow anonymous setting is the password file settings.

password_file file path

If allow anonymous is false then you need to create a password file and set the path to the file. This is covered in the using username/password authentication tutorial.

This can be set on a per listener basis and is reloaded on reload signal.

This means that you do not need to restart Mosquitto when you add new users to the password file.

TLS /SSL Support

Provided through certificates or pre shared keys (PSK) and is configurable on a per listener basis and doesn’t require the per_listener_settings to be configured.

This is covered in more detail in configuring SSL on Mosquitto

Access Control Restrictions

You can configure mosquitto to restrict access to clients using ACL (access control lists).

Access control list restrictions are set using the setting:

acl_file file path

and can be configured on a per listener basis if per_listener_settings is true.. They are reloaded on reload signal.

This means changes made to the access control lists can be applied without restarting the broker.

See Using and testing ACL restrictions in mosquitto for more details

Per Listener Settings

There are many settings that apply to listeners regardless of the if per_listener_settings setting.

Default Listener

This listens on port 1883 by default and doesn’t usually require configuration. However you can set the address the listener listens on using the bind_address setting and interface using the bind_interface setting (Linux only) and also the port number using the port setting.

If you configure the listener to use websockets using the protocol setting then you can also configure the broker to act as a simple http server and set the directory where the files are located using the http_dir setting.

Note: The manual doesn’t recommend using the default listener if you are configuring additional listeners.

The following is a list of other settings taken from the manual that should give you an idea of what can be configured.

• bind_address address
• bind_interface device
• http_dir directory
• listener port [bind address/host]
• max_connections count
• maximum_qos count
• max_topic_alias number -MQTTv5 only
• mount_point topic prefix
• port port number
• socket_domain [ ipv4 | ipv6 ]
• protocol value (MQTT or websockets)
• use_username_as_clientid [ true | false ]
• websockets_log_level level
• websockets_headers_size size

Bridge Settings

Mosquitto can be configured to act as a bridge so that it will rely messages to another broker there is an entire section that covers these settings.

Bridges can also be configured to use authentication and SSL.

You can find more details in configuring Mosquitto as a bridge tutorial

---

Starting Mosquitto – Notes

When starting mosquitto for the command line unless you specify a configuration file none is used. Therefore

mosquitto
mosquitto -v

and other similar commands start mosquitto without using a configuration file.

If you install mosquitto as a service on Windows then it starts using the mosquitto.conf.

The Linux install also configures the Mosquitto broker to start automatically using the mosquitto.conf file..

Important: When testing mosquitto you need to stop the mosquitto instance that has been started when the machine booted, and then start your own instance from the command line.

Editing The File Configuration File

When testing I would recommend you create a configuration file in your local folder and use that.

I don’t recommend that you copy the default mosquitto.conf file as it contains all possible settings which are commented out, and if you do make change to it it is difficult to locate them.

However It is very useful for documentation as it contains help for all of the settings.

You can use a normal text editor to edit the file.

If you do use it then put all of your settings at the top of the file, and use the commented out section as documentation.

If you do edit the individual sections then I have created a simple Python script that will display only the un-commented settings from the file.

When you run it you will see something like the screen shot below

File Structure

There is no imposed structure although certain settings mus appear before others e.g you must specify the per_listener_settings setting before you create listeners.

The structure I use is shown in the sketch below:

Restarting Mosquitto or Reloading Config Files

If you update mosquitto configuration files you can restart mosquitto to pick up the changes.

However on Linux you can also reload the configuration files without restarting the broker by sending the HUP signal as follows:

kill -HUP PID # where PID is the process ID as shown below:

If you look at the console it should show that the config files have been reloaded.

Important Note: Not all configuration file changes will be picked up on reload you will need to consult the manual

I have created a table showing the settings and what requires a restart that you can use as a quick reference.

Configurations Examples

The best way to understand how to use the configuration file is to see some examples. The following shows some typical configurations.

Note: I don’t include logging or persistence in these examples so as to keep them short and simple, but I do I my real files.

Mosquitto Broker Listening on Several Ports

The mosquitto broker can be configured to listen on several ports at the same time.

However this configuration doesn’t mean that you have virtual brokers. as most of the configuration is shared.

 

Example 1- Listen on ports 1883 and 1884

Section Default listener

port 1883

Section Extra listeners

listener 1884

Example 2- Listen on ports 1883 and 1884 without default listener

Section Default listener

Section Extra listeners

listener 1883
listener 1884

---

Example 3- Listen on ports 1883 and 8883 (SSL)

Section Default listener

port 1883

Section Extra listeners

listener 8883

Certificate based SSL/TLS support

(Windows)
cafile c:\mosquitto\certs\ca.crt
keyfile c:\mosquitto\certs\server.key
certfile c:\mosquitto\certs\server.crt

(Linux)

cafile /etc/mosquitto/certs/ca.crt
keyfile /etc/mosquitto/certs/server.key
certfile /etc/mosquitto/certs/server.crt

---

Example 4- Listen on ports 1883 and WebSockets (SSL)

Section Default listener

port 1883

Section Extra listeners

listener 9001
protocol websockets

Example 5- Listen on ports 1883 and 1884 with authentication

Notes:

Global

per_listener_settings true

Section Default listener
port 1883
Section Extra listeners
listener 1884
allow_anonymous false
password_file file path

Example 6- Restrict number of connections on default listener to 1000

Global
max_connections 1000

---

Useful Linux Commands

To stop Mosquitto when running as a daemon:

ps -aux | grep mosquitto

pgrep mosquitto

sudo kill -9 PID (that you get from above command)

Resources:

• Mosquitto.conf Manual Page
• Mosquitto Change log shows what was changed in what version

Related Tutorials

• Mosquitto MQTT Bridge-Usage and Configuration
• Understanding and Configuring Logging – Mosquitto Broker Configuration
• Mosquitto SSL Configuration -MQTT TLS Security
• Configuring and Testing MQTT Topic Restrictions
• Mosquitto Username and Password Authentication -Configuration and Testing
• How to Install The Mosquitto MQTT Broker- Windows and Linux