Install the Mosquitto Ubuntu Appliance for Raspberry Pi

Download the Mosquitto image


Installation instructions

What you’ll need

  • A microSD card (4GB minimum, 8GB recommended)
  • A Raspberry Pi 3 or 4
  • A computer with a microSD card drive
  • A micro-USB power cable (USB-C cable for the Pi 4)
  • A monitor with an HDMI interface
  • AHDMI cable for the Pi 3 and a MicroHDMI cable for the Pi 4
  • A USB keyboard

These steps will flash your Mosquitto Ubuntu Appliance to your Raspberry Pi with a Ubuntu machine, and get you logged in.

  1. Install the Raspberry Pi Imaging Tool

    Download the Imaging Tool for Ubuntu

  2. Prepare the microSD card

    Warning
    This will completely erase the microSD card.

    • Insert the microSD card into your computer
    • Run the imager and click CHOOSE OS
    • Next, choose Use Custom. Select the image you downloaded.
    • Select your microSD card and click WRITE.

    While it is preparing the disk you can go on to the next step and create your SSH keys for secure access to the appliance.

  3. Generate Secure Shell (SSH) keys

    The ‘Secure Shell’ protocol provides access to your Ubuntu Appliance and uses cryptographic keys to authenticate you to the device. You need SSH software and keys.

    Run the following command:

    ssh-keygen -t rsa
    1. This starts the key generation process. When you execute this command, the ssh-keygen utility prompts you to indicate where to store the key
    2. Press the ENTER key to accept the default location. The ssh-keygen utility prompts you for a passphrase
    3. Type in a passphrase

    You now have a public and private key that you can use to authenticate.

  4. Create an Ubuntu SSO account

    Your Ubuntu Appliance will be added to your Ubuntu cloud account and use your SSH keys to identify you. Add your keys to your account at https://login.ubuntu.com/ssh-keys.

    To do so, run the following command in your terminal.

    cat ~/.ssh/id_rsa.pub

    Copy the result into the text field on the website. Click import and will have the key set up.

  5. Boot your Raspberry Pi from the microSD card

    Wait for the Raspberry Pi images to complete. Remove the microSD card from your computer and insert it into the Raspberry Pi. Attach your monitor and keyboard to the Pi, you will use them for the initial device configuration.

    If you want to use a wired network, connect your ethernet cable to the Pi before booting.

    Power up the Pi by connecting it to your USB power supply.

    Your Pi will boot, and present you with a series of configuration choices. You need to ensure that the Pi has internet access so that it can get updates and verify your SSH keys. If you need more help there is a tutorial that goes through these steps in more detail.

    Next, you will need to enter your Ubuntu cloud account email address. Your Pi will connect to your cloud account and retrieve your SSH keys.

  6. SSH in

    Your Pi will show an ssh command like:

    ssh <Ubuntu SSO user name>@<device IP address>

    Your user name is your Ubuntu SSO user name.

    Your terminal will welcome you to Ubuntu Core.

  7. That’s it

    Now that you’re in your Pi you will be able to use your Mosquitto Ubuntu Appliance image.

What you’ll need

  • A microSD card (4GB minimum, 8GB recommended)
  • A Raspberry Pi 3 or 4
  • A computer with a microSD card drive
  • A micro-USB power cable (USB-C cable for the Pi 4)
  • A monitor with an HDMI interface
  • AHDMI cable for the Pi 3 and a MicroHDMI cable for the Pi 4
  • A USB keyboard

These steps will flash your Mosquitto Ubuntu Appliance to your Raspberry Pi with a Windows machine, and get you logged in.

  1. Install the Raspberry Pi Imaging Tool

    Download the Imaging Tool for Windows

  2. Prepare the microSD card

    Warning
    This will completely erase the microSD card.

    • Insert the microSD card into your computer
    • Run the imager and click CHOOSE OS
    • Next, choose Use Custom. Select the image you downloaded.
    • Select your microSD card and click WRITE.

    While it is preparing the disk you can go on to the next step and create your SSH keys for secure access to the appliance.

  3. Install OpenSSH

    The ‘Secure Shell’ protocol provides access to your Ubuntu Appliance and uses cryptographic keys to authenticate you to the device. You will need SSH software and keys.

    Some versions of Windows 10 include an SSH client already, but if yours does not or you’re unsure, follow these steps to install one.

    1. OpenSSH client is an installable feature of Windows 10.

      To install OpenSSH, start Settings then go to Apps > Apps and Features > Manage Optional Features.

    2. Scan this list to see if OpenSSH client is already installed. If not, at the top of the page select Add a feature, then, to install the OpenSSH client, locate OpenSSH Client and click Install

      Once the installation completes, return to Apps > Apps and Features > Manage Optional Features and you should see the OpenSSH component(s) listed.

    To install OpenSSH using PowerShell, first launch PowerShell as an Administrator. To make sure that the OpenSSH features are available for install type the command:

    Get-WindowsCapability -Online | ? Name -like 'OpenSSH*'

    This should return:

    Name  : OpenSSH.Client~~~~0.0.1.0
    State : NotPresent

    Then, install the client features:

    Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

    Both commands should return:

    Path          :
    Online        : True
    RestartNeeded : False
    
  4. Generate Secure Shell (SSH) keys

    After you have installed OpenSSH client you will need to generate user SSH keys to secure the connection to your Raspberry Pi.

    Launch ‘Windows PowerShell’ as an Administrator, and type:

    ssh-keygen

  5. Create an Ubuntu SSO account

    Your Ubuntu Appliance will be added to your Ubuntu cloud account and use your SSH keys to identify you. Add your keys to your account at https://login.ubuntu.com/ssh-keys.

    To do so, run the following command in your terminal, which will copy your public key to your keyboard.

    type ~\.ssh\id_rsa.pub | clip.exe

    You can then paste your key result into the text field on your Ubuntu One account. Click import and will have the key set up.

  6. Boot your Raspberry Pi from the microSD card

    Wait for the Raspberry Pi images to complete. Remove the microSD card from your computer and insert it into the Raspberry Pi. Attach your monitor and keyboard to the Pi, you will use them for the initial device configuration.

    If you want to use a wired network, connect your ethernet cable to the Pi before booting.

    Power up the Pi by connecting it to your USB power supply.

    Your Pi will boot, and present you with a series of configuration choices. You need to ensure that the Pi has internet access so that it can get updates and verify your SSH keys. If you need more help there is a tutorial that goes through these steps in more detail.

    Next, you will need to enter your Ubuntu cloud account email address. Your Pi will connect to your cloud account and retrieve your SSH keys.

  7. SSH in

    Your Pi will show an ssh command like:

    ssh <Ubuntu SSO user name>@<device IP address>

    Your user name is your Ubuntu SSO user name.

    Your terminal will welcome you to Ubuntu Core.

  8. That’s it

    Now that you’re in your Pi you will be able to use your Mosquitto Ubuntu Appliance image.

What you’ll need

  • A microSD card (4GB minimum, 8GB recommended)
  • A Raspberry Pi 3 or 4
  • A computer with a microSD card drive
  • A micro-USB power cable (USB-C cable for the Pi 4)
  • A monitor with an HDMI interface
  • AHDMI cable for the Pi 3 and a MicroHDMI cable for the Pi 4
  • A USB keyboard

These steps will flash your Mosquitto Ubuntu Appliance to your Raspberry Pi with a macOS machine, and get you logged in.

  1. Install the Raspberry Pi Imaging Tool

    Download the Imaging Tool for macOS

  2. Prepare the microSD card

    Warning
    This will completely erase the microSD card.

    • Insert the microSD card into your computer
    • Run the imager and click CHOOSE OS
    • Next, choose Use Custom. Select the image you downloaded.
    • Select your microSD card and click WRITE.

    While it is preparing the disk you can go on to the next step and create your SSH keys for secure access to the appliance.

  3. Generate Secure Shell (SSH) keys

    The ‘Secure Shell’ protocol provides access to your Ubuntu Appliance and uses cryptographic keys to authenticate you to the device. You will need SSH software and keys.

    Terminal is the terminal emulator which provides a text-based command-line interface (CLI) to the Unix shell of macOS.

    To open the macOS Terminal:

    1. In Finder, select Utilities from the Applications folder.
    2. Find Terminal in the utilities list.
    3. Enter the following command:

      ssh-keygen -t rsa

      This starts the key generation process. When you execute this command, the ssh-keygen utility prompts you to indicate where to store the key

    4. Press the ENTER key to accept the default location. The ssh-keygen utility prompts you for a passphrase
    5. Type in a passphrase

    You now have a public and private key that you can use to authenticate.

    Your private key is saved to the id_rsa file in the .ssh directory and is used to verify the public key you use belongs to the same account.

  4. Create an Ubuntu SSO account

    Your Ubuntu Appliance will be added to your Ubuntu cloud account and use your SSH keys to identify you. Add your keys to your account at https://login.ubuntu.com/ssh-keys.

    To do so, run the following command in your terminal.

    cat ~/.ssh/id_rsa.pub

    Copy the result into the text field on the website. Click import and will have the key set up.

  5. Boot your Raspberry Pi from the microSD card

    Wait for the Raspberry Pi images to complete. Remove the microSD card from your computer and insert it into the Raspberry Pi. Attach your monitor and keyboard to the Pi, you will use them for the initial device configuration.

    If you want to use a wired network, connect your ethernet cable to the Pi before booting.

    Power up the Pi by connecting it to your USB power supply.

    Your Pi will boot, and present you with a series of configuration choices. You need to ensure that the Pi has internet access so that it can get updates and verify your SSH keys. If you need more help there is a tutorial that goes through these steps in more detail.

    Next, you will need to enter your Ubuntu cloud account email address. Your Pi will connect to your cloud account and retrieve your SSH keys.

  6. SSH in

    Your Pi will show an ssh command like:

    ssh <Ubuntu SSO user name>@<device IP address>

    Your user name is your Ubuntu SSO user name.

    Your terminal will welcome you to Ubuntu Core.

  7. That’s it

    Now that you’re in your Pi you will be able to use your Mosquitto Ubuntu Appliance image.

Start using your Mosquitto Ubuntu Appliance

After installing the Mosquitto image, the Mosquitto broker will be running with the default configuration, listening for connections on port 1883. To test the broker, you can use the mosquitto-pub and mosquitto-sub command-line utilities. This is a basic test example to start using your appliance. If you want more information about Mosquitto and what to do next the best place to go is the Mosquitto website.

mosquitto_pub allows you to publish messages to an MQTT broker, and mosquitto_sub allows you to subscribe to messages from an MQTT broker. Both tools have options to control how they are used so they are useful for a wide variety of tasks. In this case, we will use them for some simple testing.

To subscribe to all messages being published to the MQTT broker on the snap/example topic, run this command in your appliance:

mosquitto_sub -h localhost -t 'snap/example' -v

If your MQTT broker is not running on the same machine as mosquitto_sub, you will need to change the localhost argument to match your MQTT broker host or IP address.

The -t snap/example option sets the topic to subscribe and can be provided multiple times. The -v option means to print both the topic of the message as well as its payload. Now to publish a message to the same topic you use mosquitto_pub:

mosquitto_pub -h localhost -t 'snap/example' -m 'Hello from mosquitto_pub'

In this case, the -m option provides the message payload to be published. If everything works as planned, you should see mosquitto_sub print

snap/example Hello from mosquitto_pub

This is a very simple example but allows testing of the broker operation. Other things you may wish to try are subscribing to wildcard topics that include # or , or subscribing to the $SYS/# topic to see the information the broker is publishing about itself.

Note:

The command line treats # as a special character, and SSYS will be expanded as an environment variable if you do not surround them with single quotes.

Once you have finished your testing, you will want to configure your broker to have encrypted connections and use authentication, or possibly configuring bridges, which allow different brokers to share topics. or many other options. To do this, you need to provide a new configuration file. The snap provides an example configuration file at /var/snap/mosquitto/common/mosquitto_example.conf.

This file contains all of the broker configurations, in a similar manner to the man page. To create your own configuration, copy the example file to /var/snap/mosquitto/common/mosquitto.conf and edit according to your needs. Any additional files required by the configuration, such as TLS certificates and keys, must also be placed in /var/snap/mosquitto/common/ and have their full path provided in the configuration file.