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/mosquito 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:
- MQTT
- MQTT +SSL
- MQTT +Websockets
- 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 true 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 onlymount_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
Check Configuration File
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
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
Hello
on the client side i have to start
rtl_433 -F json -M utc | mosquitto_pub -h 10.18.42.175 -p 1883 -d -t iot12-rpi3b-gw-433 -l
as soon i do close the Terminal, the Server with Node Red don’t get any message.
how/where to add the information to be called when the client restart or the terminal is closed?
and how to change the QoS setting to 1 or 2 on the client side?
have a nice day
vinc
Not quite sure what you are doing. Use the ask steve page and let me know in more detail
Hi,
I am a newbie to MQTT concept and am trying to use RaspberryPi as publisher for communication. I am using my Linux Machine with IP address 10.60.62.125 to run the mosquitto broker. And publisher code runs on RaspberryPi and subscriber code runs on my Linux Machine. In the publisher code, I am trying to connect the client to “10.60.62.125” which is not working and giving me connection timed out error after some time. So what should be the IP address I have to specify in publisher code? Any help?
Hi
You are using the correct address. However I notice that you are using the 10.x.x.x range for you network which is unusual. Can the machine you are trying to connect from (the client) ping the address 10.60.62.125?
Rgds
Steve
Hi Steve,
I’m biginner in this, now i created my certifcate with my local domain name, but when i run my client, which is created in javascript , it’s returning error like WebSocket connection to ‘wss://innocube:9001/mqtt’ failed: Error in connection establishment: net::ERR_NAME_NOT_RESOLVED
Hi
That looks like a name resolution error and not mqtt
My apologies for a simple question. I am a raw beginner trying to get home assistant working. Very frustrating process.
I flashed tasmota on a Sonoff basic and am trying to get HA to recognize it. I have installed Mosquito on HA but when I try to set up MQTT, i get an “unable to connect to the broker” error.
I have tried every up address I can find and really have no idea what or how to find the broker address.
On the machine that is running mosquitto open a command prompt ant type
ipconfig (windows) or ifconfig(Linux) it will show you the ip address
rgds
steve
I set up Sonoff PWRR2 with HA today. Just check that you have done these steps:
– set up mosquito to use passwords:
allow_anonymous false
password_file /etc/mosquitto/passwd
in mosquito.conf or any other config file in the conf.d subfolder
– create a user with password
sudo mosquitto_passwd -c /etc/mosquitto/passwd my_username
– test your config by publishing while you have a subscription running (assuming you are executing on same machine where mosquito is running)
mosquitto_sub -h localhost -t test -u my_username -P my_password
mosquitto_pub -h localhost -t test -m “hello World!” t -u my_username -P my_password
– configure tasmota to use Mqtt, set ip, port (1883), …, account:my_username, my_password, topic=my_topicname. (my_topicname must be unique for each device if you have several tasmotas)
– activate automatic discovery on your tasmota:
mosquitto_pub -h localhost -t cmnd/my_topicname/SetOption19 -m “1” -u my_username -P my_password
– add mqtt integration to HA, fill in ip, port (1883), my_username,my_password
The tasmota entities will appear on the MQTT tile of the integrations page
Hi Steve,
I am working on SCADA and it contains inbuilt MQTT drivers, and I am connecting with AWS server by using MQTT, So here mosquitto broker is running fine in services but I am little doubt on config file, the config file is commented but where I have to enter the broker details and port details exactly in the config file, can you please send me some example config file for my understanding purpose.
Hi
You don’t normally need to enter the IP address of the broker in the conf file as it listens on all ip addresses assigned to the machine the broker runs on by default.
When you add extras listeners you add them normally just using the port number.But you can add the ip address using
# listener port-number [ip address/host name]
e.g
listener 1884 192.168.1.68
For the default listener use
bind_address ip-address/host name
e.g
bind_address 192.168.1.68
rgds
Steve
Hi Steve,
I’ve updated config file for tls and still mosquitto is not listening on port 8883 when I give command “mosquitto -c mosquitto.conf”. Its not executing anything.
Can you use the ask steve page and send me a copy of the file
rgds
steve
hi steve,
thanks for this post. can please share tutorial or guide to make our own mqtt broker via python.thankyou
Hi
There is one used for testing here
https://github.com/eclipse/paho.mqtt.testing
rgds
steve
trying to run your script on Raspi:
import paho.mqtt.client as paho
ImportError: No module named ‘paho’
this is after I successfully installed it:
pip install paho-mqtt
If you have installed it it may be installed under a different python version but this is not usual on PI.
Take alook here
http://www.steves-internet-guide.com/python-notes/
Hi,
I got some data missing when connected IoT devices to the mosquitto I installed on Linux. But if I connect the devices to “m2m.eclipse.org” or “test.mosquitto.org”, no data was missing.
Do you have any idea what’s going on here? All the setting for mosquitto are default on my Linux.
Thanks a lot!
I would suspect a local nwtwork issue. Did you start mosquitto in verbose mode so that you could be the messages.
rgds
steve
Hi, i configuring MQTT in windows server. How do i change my port number in windows and make MQTT available to public address?
You need to edit the mosquitto.conf file or start mosquitto from the command line using
mosquitto -p 1884
to start mosquitto in port 1884
I am on windows 10. I was able to run mosquitto broker successfully to listen on 1883 following your tutorial. I tested the connection using mosquitto_pub and mosquitto_sub as well. When I tried to test for TLS. I changed the mosquitto cfg file for listening on 8883 and the server certs. Then tried restarting the mosquitto in the services (Local) but it posts the error as “The Mosquitto Broker service on Local Computer started and then stopped. Some services stop automatically if they are not in use by other services or programs.”. On windows command line too, i tried
sc start “mosquitto” followed by sc query “mosquitto”. The sc queries show the STATE as 2 START_PENDING and followed by STATE as 1 STOPPED. Any reason why mosquitto broker couldn’t be started?
I would suspect an error in the config file or it can’t find it.Have you tried staring from the command line as mosquitto -c configfile as it may give you more info.
Hi
I put mosquitto.conf file in /etc/mosquitto/ and run mosquitto
mosquitto -c /etc/mosquitto/mosquitto.confif
In this file my default port is 8890
But when i try run it,it occurred error not found config file while it is exist in this directory
Also when i use only mosquttio,it start listen with 1883 port
It is default port
Where is it default config file?
Thanks
The default mosquitto.conf file is in the /etc/mosquitto folder.
However mosquitto doesn’t need a conf file to start.
When you start mosquitto using mosquitto -v it isn’t using a conf file.
Check your conf file for typos as that also results in not found errors.
You can start mosquitto using a different port using
mosquitto -p 8890
if you are still having problems send me your conf file
Yes my config file had error in fields and it solved successfully
I use moquitto -c /etc/mosquitto/mosquitto.conf
Thank you again
Hi
I want to use kill -hub pid for reload config file after add new user to list
Is it right way?
Hi,
How to make mosquitto broker running on PC to listen to 1883 and also 9001, because i have a mosqutto cpp client which publishes on one topic which needs to listen by mqtt web app.
when i set mosquitto.conf to 9001, the mosqitto cpp client is not connecting to local broker, but webapp is getting connected to broker running on my PC.
These are the only lines you need
port 1883 #normal listener
#extra listener
listener 9001
protocol websockets
##useful
log_type all
If you are still having problem use the ask steve page and send me your conf file and I’ll edit it for you
rgds
steve
How to edit this config file through code and restart this broker?
Please help with suggestions.
Thanks in Advance
By edit by code do you mean using a web type interface to create the file?
What is the difference between kill -SIGHUP and kill -HUP?
Mosquitto official documents use kill -SIGHUP.
They are the same. HUP is the shortname for SIGHUP. Take a look here
https://www.cyberciti.biz/faq/unix-kill-command-examples/
rgds
steve
I use this command “kill -HUB 26832”
But have error here
bash: kill: HUB: invalid signal specification
What is problem?
PID is correct
Hi
Typo
It’s HUP
not
HUB
Thank you
Thanks A Lot <3