Quick Guide to The Mosquitto.conf File With Examples

mosquitto-conf-iconYou 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.

Broker Mosquitto.conf Settings

The default mosquitto.conf file has all of the settings commented out and the broker doesn’t require a configuration file to run.

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.

Important- An extra  listener is effectively an additional port, and not an additional broker!

The diagram below is my understanding of how the settings apply.


Configurations Examples

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.

You cannot, for example, configure a broker to listen on port 1884, and to allow anonymous access, and also to listen on port 1885 and not allow anonymous access.

Because they are part of the same broker instance they share the allow_anonymous setting.

However you can configure a broker to listen on a port and require SSL and also to listen on another port and not use SSL.

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 8883 (SSL)

Section Default listener

port 1883

Section Extra listeners

listener 8883

Certificate based SSL/TLS support

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


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

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

Section Default listener

port 1883

Section Extra listeners

listener 9001
protocol websockets

See Also MQTT and Mosquitto WebSockets Working Notes

Starting Mosquitto – Notes

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

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- Tips

You can use a normal text editor to edit the file. Although it is tempting to edit the particular section of the file it can be very difficult finding what settings you have changed.

Therefore 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


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 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.


Running Multiple Mosquitto Brokers

You can configure a broker to listen on several ports, but to create multiple brokers with their own configurations then you will need to start multiple instances of mosquitto.


Start mosquitto and listen on port 1883

mosquitto -p 1883

Start mosquitto as a daemon and listen on port 1884

mosquitto -p 1884 -d

Start mosquitto as a daemon and use the mosquitti-2.conf file. – Not Supported on Windows


mosquitto -c /etc/mosquitto/mosquitto-2.conf  -d

Here is a video that shows you how

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)



Mosquitto.conf Manual Page

Related Tutorials



Please rate? And use Comments to let me know more
[Total: 18   Average: 3.1/5]


  1. 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

  2. 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.

    1. 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

    2. 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

  3. 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.

    1. 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]
      listener 1884

      For the default listener use
      bind_address ip-address/host name


  4. 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.

  5. 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

  6. 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!

  7. Hi, i configuring MQTT in windows server. How do i change my port number in windows and make MQTT available to public address?

    1. 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

  8. 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?

    1. 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.

  9. 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?

    1. 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

      1. Yes my config file had error in fields and it solved successfully
        I use moquitto -c /etc/mosquitto/mosquitto.conf
        Thank you again

  10. Hi
    I want to use kill -hub pid for reload config file after add new user to list
    Is it right way?

  11. 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.

    1. These are the only lines you need
      port 1883 #normal listener
      #extra listener
      listener 9001
      protocol websockets

      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

      1. I use this command “kill -HUB 26832”
        But have error here
        bash: kill: HUB: invalid signal specification
        What is problem?
        PID is correct

Leave a Reply

Your email address will not be published. Required fields are marked *