Skip to main content

Install MQTT Broker (Mac)

Mosquitto is a popular open-source MQTT broker. Here’s a step-by-step guide to installing and running Mosquitto on a system running MacOS. This tutorial assumes that you use Brew as your package manager. Other package managers probably work, but the commands need to be changed accordingly to the used package manager.

Step 1: Install Mosquitto​

  1. Update the package list:

    brew upgrade

  2. Install Mosquitto and its clients:

    brew install mosquitto

Step 2: Set Up User and Password for MQTT Broker​

  1. Create a password file for Mosquitto. This is where you choose your username. Make sure the path to the password file path is the same as set in the previous step.

    mosquitto_passwd -c /opt/homebrew/etc/mosquitto/passwd yourusername

  2. Enter the password when prompted. After that you will have to confirm it by entering it a second time.

Expected credentials

This project expects you to use knightec as your username and password, read more here.

Step 3: Configure Mosquitto​

Any files with extension .conf that are placed in /opt/homebrew/etc/mosquitto/ will be used by the MQTT Broker.

  1. Add or open the configuration file in a text editor:

    nano /opt/homebrew/etc/mosquitto/mosquitto.conf

  2. Add these lines to configure the MQTT Broker to listen to port 1883 and require authentication.

    # If this is set to true then authentication is disabled.
    allow_anonymous false

    # Default is /opt/homebrew/etc/mosquitto/passwd, but any path could be used.
    password_file /opt/homebrew/etc/mosquitto/passwd

    # Another port can be used, but 1883 is default.
    listener 1883
    protocol mqtt

    listener 8080
    protocol websockets

    Press Ctrl + X to exit. It will ask you to save your changes.

    Press Y to save.

    It will ask you which file name to save to. It's already set to the current file, so just press Enter.

    Summary: The sequence of keystrokes to change your changes in nano text editor is Ctrl + X -> Y -> Enter.

Step 4: Start the Mosquitto Service​

These steps allow you to add Mosquitto as a user service. It is also possible to add it as a system-wide/root service, but it should not be necessary.

  1. Link the .plist to be able to use it as a service

    sudo ln -sfv /opt/homebrew/opt/mosquitto/homebrew.mxcl.mosquitto.plist /Library/LaunchAgents

  2. Enable the Mosquitto service:

    launchctl enable user/501/homebrew.mxcl.mosquitto

  3. Start Mosquitto to and allow it to start on boot:

    launchctl bootstrap user/501 /opt/homebrew/opt/mosquitto/homebrew.mxcl.mosquitto.plist

  4. Check the status of the Mosquitto service:

    launchctl print user/501/homebrew.mxcl.mosquitto

Step 5: Test the Mosquitto Broker​

  1. Open a terminal and subscribe to a topic (e.g., test/topic):

    mosquitto_sub -h localhost -t test/topic -u "yourusername" -P "yourpassword"

  2. Open another terminal and publish a message to the same topic:

    mosquitto_pub -h localhost -t test/topic -m "Hello, MQTT" -u "yourusername" -P "yourpassword"

You should see the message "Hello, MQTT" appear in the terminal where you subscribed to the topic.

Additional Tips​

  • Logging: To be able to more easily solve issues, logging can be enabled for the service. The 'syslog' option does not work for newer versions of MacOS. Instead, to enable logging to a specific logfile add the following to the configuration file (/opt/homebrew/etc/mosquitto/mosquitto.conf).

    log_dest file /Users/YourUser/Library/Logs/Homebrew/mosquitto/mosquitto.log

    Replace 'YourUser' with the username of your local account. You can then look at the logfile using any file editor of your choice, or by running tail -f /Users/YourUsername/Library/Logs/Homebrew/mosquitto/mosquitto.log to continuously output new content in the logfile to a chosen a terminal window.

  • Restarting a service: To restart the Mosquitto service after being enabled and started, use the following command:

    launchctl kickstart -k user/501/homebrew.mxcl.mosquitto

Congratulations! You have now installed, configured, and ran an MQTT broker using Mosquitto on your Mac.