Skip to main content
Version: Mosquitto 2.8

Migration Information

Adding new features can require to adapt the existing configuration of the Pro Mosquitto and MMC setups. This page documents possible configuration and setup changes. While updating your on-premise setups please refer to this document. Cloud customers are updated automatically.

2.8

Welcome to the migration guide for upgrading your system from version 2.7 to the new version 2.8. We are excited to introduce the enhancements and improvements in this latest release. To ensure a smooth transition, please follow the steps outlined below.

For the upgrade to version 2.8:

  • No Additional Environment Variables: We have not introduced any new environment variables, nor have we made changes to the setup process itself. Your existing configurations can remain as is.
  • Image Update Required: The primary change involves updating the image for our Cedalo Registry. Please update your systems to use the new images:
    • For Mosquitto: registry.cedalo.com/mosquitto/mosquitto:2.8
    • For Management Center Premium: registry.cedalo.com/development/management-center-premium:2.8
  • Alternative Download Option: If you prefer, you can also download the new .rpm package from our repository for a manual update.

Version 2.8 comes with exciting new features designed to enhance your experience and capabilities. To make the most of these new features:

  • Documentation: Visit the respective docs to learn how to configure and utilize the new features available in version 2.8. The documentation provides detailed instructions and insights to help you seamlessly integrate these features into your existing setup.
  • License Update: If your current license does not cover the version 2.8 features, it is essential to update your license to access the full capabilities of the new release. The old license will still work for all existing features.

Cluster updates: If you are updating a cluster, make sure to update each Mosquitto node one by one, with the leader being the last node to be updated.

Should you encounter any issues during the migration process or if you have any questions regarding the new features or license updates, please do not hesitate to reach out to us. Our support team is ready to assist you:

We are committed to ensuring a smooth and efficient upgrade process for all our users. Thank you for choosing our solutions, and we look forward to supporting you through this transition to version 2.8.

2.7

Single Node​

This is the Docker Migration guide to upgrade from version 2.6 to 2.7.

Docker Compose​

  1. Add the following environment variable to the management center:
CEDALO_MC_PROXY_HOST: 0.0.0.0
  1. You may remove the following variable from the docker-compose as it's no longer being used:
CEDALO_MC_PLUGIN_DIR: /management-center/plugins
  1. Optionally: A new way of loading MMC plugins was added. The file "plugins.json" can now be used to manually configure the plugins. The config.json loads the content of the file on start if the environment variable "CEDALO_MC_PLUGIN_LIST_PATH: management-center/config/plugins.json" is set. If no file is found an error message is shown and the config.json file will be read. If the file is found, the config.json file plugin list will be overwritten on start.

Specify some specific set of plugins to load via the CEDALO_MC_PLUGIN_LIST_PATH environment variable:

CEDALO_MC_PLUGIN_LIST_PATH: management-center/config/plugins.json"

You should provide a path to plugins.json user data file with the list of plugins to load. It can look like the following:

{
    "plugins": [
        {
            "id": "audit-trail"
        },
        {
            "id": "user-management"
        },
        {
            "id": "cert-management"
        },
        {
            "id": "saml-sso"
        },
        {
            "id": "https"
        },
        {
            "id": "application-tokens"
        },
        {
            "id": "monitoring-rest-api"
        },
        {
            "id": "tls"
        },
        {
            "id": "user-profile-edit"
        },
        {
            "id": "cluster-management"
        },
        {
            "id": "connections-rest-api"
        },
        {
            "id": "custom-themes"
        },
        {
            "id": "multiple-connections"
        },
        {
            "id": "system-status-rest-api"
        },
        {
            "id": "topictree-rest-api"
        },
        {
            "id": "dynamic-security-rest-api"
        }
    ]
}
  1. Make sure that the command section is changed from the following:
command: >
    /bin/sh -c "
      while ! nc -z mosquitto 1883;
      do
        echo 'Waiting for mosquitto';
        sleep 1;
      done;
      cd /management-center; exec /bin/sh /management-center/docker-entrypoint.sh ./start
    "

to:

command: >
    /bin/sh -c "
      while ! nc -z mosquitto 1883;
      do
        echo 'Waiting for mosquitto';
        sleep 1;
      done;
      cd /management-center; exec ./mmc
    "

So the line which changes is cd /management-center; exec /bin/sh /management-center/docker-entrypoint.sh ./start to cd /management-center; exec ./mmc

  1. Change MMC image to:
image: registry.cedalo.com/mosquitto/management-center:2.7

and Mosquitto image to:

image: registry.cedalo.com/mosquitto/mosquitto:2.7
  1. Place your license to where /management-center/config or a different location where CEDALO_MC_LICENSE_PATH environment variable is pointing to. For a new license which also covers 2.7 features please contact our team.

Example:​

Here is a sample docker-compose file for 2.7 MMC:

version: '3.7'
services:
    mosquitto:
        image: registry.cedalo.com/development/mosquitto:2.7.0-rc1
        ports:
            - 1883:1883
            - 8883:8883
            - 8090:8090
        networks:
            - cedalo-platform
        environment:
            CEDALO_LICENSE_FILE: /mosquitto/license/license.lic
        volumes:
            - ./mosquitto/config:/mosquitto/config
            - ./mosquitto/data:/mosquitto/data
            - ./management-center/config/:/mosquitto/license/
    management-center:
        image: registry.cedalo.com/development/management-center-premium:2.7.0-rc1
        ports:
            - 8088:8088
        expose:
            - 8088
        depends_on:
            - mosquitto
        networks:
            - cedalo-platform
        environment:
            CEDALO_HOST_NAME: ${CEDALO_HOST_NAME}
            CEDALO_IP_ADDRESS: ${CEDALO_IP_ADDRESS}
            CEDALO_MC_PROXY_HOST: 0.0.0.0
            CEDALO_MC_USERNAME: cedalo
            CEDALO_MC_PASSWORD: mmcisawesome
            CEDALO_MC_PROXY_SRT_BASE: /management-center/config
            CEDALO_MC_LICENSE_PATH: /management-center/config/license.lic
            # CEDALO_MC_PLUGIN_LIST_PATH: /management-center/config/plugins.json
            CEDALO_MC_PROXY_CONFIG: /management-center/config/config.json
            CEDALO_MC_PROXY_CONFIG_CERTS: /management-center/config/certs.db
            CEDALO_MC_PROXY_CONFIG_TOKENS: /management-center/config/tokens.json
            CEDALO_MC_PROXY_CONFIG_USERS: /management-center/config/users.json
            CEDALO_MC_PROXY_CONFIG_AUDIT_TRAIL: /management-center/config/audit.json
            CEDALO_MC_BROKER_CONNECTION_MQTT_EXISTS_MAPPING: mosquitto:true
            CEDALO_MC_BROKER_CONNECTION_MQTTS_EXISTS_MAPPING: mosquitto:false
            CEDALO_MC_BROKER_CONNECTION_WS_EXISTS_MAPPING: mosquitto:false
            CEDALO_MC_BROKER_CONNECTION_HOST_MAPPING: mosquitto:localhost
            CEDALO_MC_DATA_DIRECTORY_PATH: /management-center/config
            CEDALO_MC_MODE: offline
        volumes:
            - ./management-center/config:/management-center/config
            # map unix socket for audit trail:
            - /dev/log:/dev/log
        command: >
            /bin/sh -c "
              while ! nc -z mosquitto 1883;
              do
                echo 'Waiting for mosquitto';
                sleep 1;
              done;
              cd /management-center; exec ./mmc
            "
networks:
    cedalo-platform:
        name: cedalo-platform
        driver: bridge

Cluster setup​

This is the Docker Migration guide to upgrade your cluster setup from version 2.6 to 2.7.

There are currently two variants of migrating the setup:

  1. Create the following directory structure:
setup_directory/
|
|---->server1/
|        |
|        |---->haproxy/
|        |
|        |---->license
|        |
|        |---->management-center/config
|        |
|        |---->mosquitto
|               |
|               |---->config/
|               |
|               |---->data/ha/
|
|---->server2/
|        |
|        |---->haproxy/
|        |
|        |---->license
|        |
|        |---->mosquitto
|               |
|               |---->config/
|               |
|               |---->data/ha/
|
|---->server3/
|        |
|        |---->haproxy/
|        |
|        |---->license
|        |
|        |---->mosquitto
|               |
|               |---->config/
|               |
|               |---->data/ha/
  1. Move the contents of your old setup's haproxy folder into:

  • setup_directory/server1/haproxy/

  • setup_directory/server2/haproxy/

  • setup_directory/server3/haproxy/

  1. Move the contents of your old setups's mosquitto1, mosquitto2, and mosquitto3 folders into:

  • setup_directory/server1/mosquitto/

  • setup_directory/server2/mosquitto/

  • setup_directory/server3/mosquitto/

respectively.

  1. Move the contents of your old setup's management-center/config folder into setup_directory/management-center/config/.

  2. Add your license or move an old one from management-center/config (or mosquitto1/license/mosquitto2/license/mosquitto3/license) to:

  • setup_directory/server1/license/

  • setup_directory/server2/license/

  • setup_directory/server3/license/

info

All three locations should contain the same license.

  1. Add the following docker-compose.yml to setup_directory/server1:
version: '3.7'

services:
    mosquitto:
        image: registry.cedalo.com/mosquitto/mosquitto:2.7
        volumes:
            - ./mosquitto/config:/mosquitto/config
            - ./mosquitto/data:/mosquitto/data
            - ./license:/mosquitto/license:ro
        hostname: mosquitto1
        networks:
            mosquitto:
                ipv4_address: 172.20.1.1
        environment:
            CEDALO_LICENSE_FILE: /mosquitto/license/license.lic
            MOSQUITTO_DYNSEC_PASSWORD: 1LD1RGNgFu1u4tfasOh1j7vOrCLhMVq0
        restart: unless-stopped
    haproxy:
        image: haproxy:2.7
        ports:
            - 127.0.0.1:1883:1883 # change binding 127.0.0.1:1883 to public IPv4 X.Y.Z:1883
        volumes:
            - ./haproxy:/usr/local/etc/haproxy:ro
        restart: unless-stopped
        networks:
            mosquitto:
                ipv4_address: 172.20.2.1
    management-center:
        image: registry.cedalo.com/mosquitto/management-center:2.7
        environment:
            CEDALO_HOST_NAME: ${CEDALO_HOST_NAME}
            CEDALO_IP_ADDRESS: ${CEDALO_IP_ADDRESS}
            CEDALO_MC_PROXY_HOST: 0.0.0.0

            CEDALO_MC_USERNAME: cedalo
            CEDALO_MC_PASSWORD: mmcisawesome

            CEDALO_MC_PROXY_SRT_BASE: /management-center/config
            CEDALO_MC_LICENSE_PATH: /management-center/license/license.lic

            CEDALO_MC_PLUGIN_LIST_PATH: /management-center/config/plugins.json
            CEDALO_MC_PROXY_CONFIG: /management-center/config/config.json
            CEDALO_MC_PROXY_CONFIG_CERTS: /management-center/config/certs.db
            CEDALO_MC_PROXY_CONFIG_TOKENS: /management-center/config/tokens.json
            CEDALO_MC_PROXY_CONFIG_USERS: /management-center/config/users.json
            CEDALO_MC_PROXY_CONFIG_AUDIT_TRAIL: /management-center/config/audit.json
            CEDALO_MC_PROXY_CONFIG_CLUSTERS: /management-center/config/clusters.json
            CEDALO_MC_BROKER_CONNECTION_MQTT_EXISTS_MAPPING: mosquitto:true
            CEDALO_MC_BROKER_CONNECTION_MQTTS_EXISTS_MAPPING: mosquitto:false
            CEDALO_MC_BROKER_CONNECTION_WS_EXISTS_MAPPING: mosquitto:false
            CEDALO_MC_BROKER_CONNECTION_HOST_MAPPING: mosquitto:localhost

            CEDALO_MC_DATA_DIRECTORY_PATH: /management-center/config

            CEDALO_MC_MODE: offline
        ports:
            - 127.0.0.1:8088:8088
        volumes:
            - ./management-center/config:/management-center/config
            - ./license:/management-center/license
            # map unix socket for audit trail:
            - /dev/log:/dev/log
        networks:
            mosquitto:
                ipv4_address: 172.20.3.1
        restart: unless-stopped
networks:
    mosquitto:
        name: mosquitto
        ipam:
            driver: default
            config:
                - subnet: 172.20.0.0/16

Or adapt your existing docker-compose.yml from the old setup to be similar to the above.

In this case, make sure that:

  • In services section make sure that only mosquitto1 and haproxy, and management-center remain.

Now, rename mosquitto1 service into mosquitto.

  • Change mosquitto image to registry.cedalo.com/mosquitto/mosquitto:2.7 and MMC to registry.cedalo.com/mosquitto/management-center:2.7

  • Make sure mosquitto service has the following hostname section:

hostname: mosquitto1

  • Update management-center/networks/mosquitto/ipv4_address value and set it to 172.20.3.1.

  • Make sure that mosquitto volumes have correct paths. For instance:

volumes:
    - ./mosquitto/config:/mosquitto/config
    - ./mosquitto/data:/mosquitto/data
    - ./license:/mosquitto/license:ro
  • Add the following environment variable:
CEDALO_MC_PROXY_HOST: 0.0.0.0
  • Make sure you have CEDALO_MC_PROXY_CONFIG_CLUSTERS from your old setup.
CEDALO_MC_PROXY_CONFIG_CLUSTERS: /management-center/config/clusters.json

Technically, you don't need to explicitly define it as long as you set CEDALO_MC_DATA_DIRECTORY_PATH (because in this case clusters.json will be looked up in $CEDALO_MC_PROXY_CONFIG_CLUSTERS/clusters.json), but it's still a good idea to mention it explicitly, especially if you had clusters.json stored in a non-default location.

  • If you are going to use Audit Trail, add the following variables:
CEDALO_HOST_NAME: ${CEDALO_HOST_NAME}
CEDALO_IP_ADDRESS: ${CEDALO_IP_ADDRESS}

CEDALO_MC_PROXY_CONFIG_AUDIT_TRAIL: /management-center/config/audit.json

Note that if you have CEDALO_MC_DATA_DIRECTORY_PATH specified, you don't have to set CEDALO_MC_PROXY_CONFIG_AUDIT_TRAIL as well, but specifying it explicitely is a good idea.

CEDALO_HOST_NAME and CEDALO_IP_ADDRESS should be provided before running docker-compose (they will be automatically set when running with start.sh or start.bat). These variables will display hostname and ip address of the mmc application in the syslog entries.

  • If you want to use audit-trail and you should additionally specify the following mount if you want your container to direct the syslogs into the hostmachine's /dev/log unix socket:
volumes:
    # other volumes here...
    - /dev/log:/dev/log
  • You may remove the following variable from the docker-compose as it's no longer being used:
CEDALO_MC_PLUGIN_DIR: /management-center/plugins
  • Optionally: A new way of loading MMC plugins was added. The file "plugins.json" can now be used to manually configure the plugins. The config.json loads the content of the file on start if the environment variable "CEDALO_MC_PLUGIN_LIST_PATH: management-center/config/plugins.json" is set. If no file is found an error message is shown and the config.json file will be read. If the file is found, the config.json file plugin list will be overwritten on start.
CEDALO_MC_PLUGIN_LIST_PATH: management-center/config/plugins.json"

You should provide a path to plugins.json user data file with the list of plugins to load. It can look like the following:

{
    "plugins": [
        {
            "id": "audit-trail"
        },
        {
            "id": "user-management"
        },
        {
            "id": "cert-management"
        },
        {
            "id": "saml-sso"
        },
        {
            "id": "https"
        },
        {
            "id": "application-tokens"
        },
        {
            "id": "monitoring-rest-api"
        },
        {
            "id": "tls"
        },
        {
            "id": "user-profile-edit"
        },
        {
            "id": "cluster-management"
        },
        {
            "id": "connections-rest-api"
        },
        {
            "id": "custom-themes"
        },
        {
            "id": "multiple-connections"
        },
        {
            "id": "system-status-rest-api"
        },
        {
            "id": "topictree-rest-api"
        },
        {
            "id": "dynamic-security-rest-api"
        }
    ]
}
info

Adapt other environment variables according to what you had in your old setup.

  1. Add the following docker-compose.yml to setup_directory/server2:
version: '3.7'

services:
    mosquitto:
        image: registry.cedalo.com/mosquitto/mosquitto:2.7
        volumes:
            - ./mosquitto/config:/mosquitto/config
            - ./mosquitto/data:/mosquitto/data
            - ./license:/mosquitto/license:ro
        hostname: mosquitto2
        networks:
            mosquitto:
                ipv4_address: 172.20.1.2
        environment:
            CEDALO_LICENSE_FILE: /mosquitto/license/license.lic
            MOSQUITTO_DYNSEC_PASSWORD: 1LD1RGNgFu1u4tfasOh1j7vOrCLhMVq0
        restart: unless-stopped
    haproxy:
        image: haproxy:2.7
        ports:
            - 127.0.0.1:1884:1883 # change binding 127.0.0.1:1884 to public IPv4 X.Y.Z:1883
        volumes:
            - ./haproxy:/usr/local/etc/haproxy:ro
        restart: unless-stopped
        networks:
            mosquitto:
                ipv4_address: 172.20.2.2
networks:
    mosquitto:
        name: mosquitto
        ipam:
            driver: default
            config:
                - subnet: 172.20.0.0/16

Or adapt your existing docker-compose.yml from the old setup such that it contains only mosquitto2 service renamed to mosquitto and haproxy.

Make sure that haproxy/networks/mosquitto/ipv4_address is set to 172.20.2.2 and mosquitto/networks/mosquitto/ipv4_address to 172.20.1.2.

Also make sure that the image is set to registry.cedalo.com/mosquitto/mosquitto:2.7.

mosquitto/hostname should equal mosquitto2.

Additionally, don't forget to doublecheck that paths in volumes section are correct.

  1. Add the following docker-compose.yml to setup_directory/server3:
version: '3.7'

services:
    mosquitto:
        image: registry.cedalo.com/mosquitto/mosquitto:2.7
        volumes:
            - ./mosquitto/config:/mosquitto/config
            - ./mosquitto/data:/mosquitto/data
            - ./license:/mosquitto/license:ro
        hostname: mosquitto3
        networks:
            mosquitto:
                ipv4_address: 172.20.1.3
        environment:
            CEDALO_LICENSE_FILE: /mosquitto/license/license.lic
            MOSQUITTO_DYNSEC_PASSWORD: 1LD1RGNgFu1u4tfasOh1j7vOrCLhMVq0
        restart: unless-stopped
    haproxy:
        image: haproxy:2.7
        ports:
            - 127.0.0.1:1885:1883 # change binding 127.0.0.1:1885 to public IPv4 X.Y.Z:1883
        volumes:
            - ./haproxy:/usr/local/etc/haproxy:ro
        restart: unless-stopped
        networks:
            mosquitto:
                ipv4_address: 172.20.2.3
networks:
    mosquitto:
        name: mosquitto
        ipam:
            driver: default
            config:
                - subnet: 172.20.0.0/16

It's basically the same as the docker-compose for setup_directory/server3 but has mosquitto/hostname set to mosquitto3, mosquitto/networks/mosquitto/ipv4_address set to 172.20.1.3 and haproxy/networks/mosquitto/ipv4_address equal to 172.20.2.3.

  1. You can start your setup now with the following sh script or similar by issuing path_to_script.sh up -d:
#!/usr/bin/env bash

DIR_PATH="$(cd "$(dirname "$0")"; pwd)"

CMD="${@:-up}"

docker-compose -f "$DIR_PATH/server1/docker-compose.yml" $CMD
docker-compose -f "$DIR_PATH/server2/docker-compose.yml" $CMD
docker-compose -f "$DIR_PATH/server3/docker-compose.yml" $CMD

for Windows (path_to_script.bat up -d):

@echo off

SET CMD=%*
IF ["%CMD%"] == [""] set CMD=up

docker-compose -f "%~dp0server1\docker-compose.yml" %CMD%
docker-compose -f "%~dp0server2\docker-compose.yml" %CMD%
docker-compose -f "%~dp0server3\docker-compose.yml" %CMD%

Leaving everything in a single docker-compose file​

If you want to leave everything similar to the old setups and use a single docker-compose.yml file than make sure to make the following changes to this file to upgrade to 2.7.

Note that in the future we will not support this setup and will not provide migration guides for a single `docker-compose.yml`` file.

  1. Change mosquitto images to registry.cedalo.com/mosquitto/mosquitto:2.7. Change MMC image to registry.cedalo.com/mosquitto/management-center:2.7

  2. Update your licenses in management-center/config, mosquitto1/license, mosquitto2/license, and mosquitto3/license.

  3. Add the following environment variable:

CEDALO_MC_PROXY_HOST: 0.0.0.0
  1. Make sure you have CEDALO_MC_PROXY_CONFIG_CLUSTERS from your old setup.
CEDALO_MC_PROXY_CONFIG_CLUSTERS: /management-center/config/clusters.json

Technically, you don't need to explicitly define it as long as you set CEDALO_MC_DATA_DIRECTORY_PATH (because in this case clusters.json will be looked up in $CEDALO_MC_PROXY_CONFIG_CLUSTERS/clusters.json), but it's still a good idea to mention it explicitly, especially if you had clusters.json stored in a non-default location.

  1. If you are going to use Audit Trail, add the following variables:
CEDALO_HOST_NAME: ${CEDALO_HOST_NAME}
CEDALO_IP_ADDRESS: ${CEDALO_IP_ADDRESS}

CEDALO_MC_PROXY_CONFIG_AUDIT_TRAIL: /management-center/config/audit.json

Note that if you have CEDALO_MC_DATA_DIRECTORY_PATH specified, you don't have to set CEDALO_MC_PROXY_CONFIG_AUDIT_TRAIL as well, but specifying it explicitely is a good idea.

CEDALO_HOST_NAME and CEDALO_IP_ADDRESS should be provided before running docker-compose (they will be automatically set when running with start.sh or start.bat). These variables will display hostname and ip address of the mmc application in the syslog entries.

  1. If you want to use audit-trail you should additionally specify the following mount if you want your container to direct the syslogs into the hostmachine's /dev/log unix socket:
volumes:
    # other volumes here...
    - /dev/log:/dev/log
  1. You may remove the following variable from the docker-compose as it's no longer being used:
CEDALO_MC_PLUGIN_DIR: /management-center/plugins
  1. Optionally: A new way of loading MMC plugins was added. The file "plugins.json" can now be used to manually configure the plugins. The config.json loads the content of the file on start if the environment variable "CEDALO_MC_PLUGIN_LIST_PATH: management-center/config/plugins.json" is set. If no file is found an error message is shown and the config.json file will be read. If the file is found, the config.json file plugin list will be overwritten on start.
CEDALO_MC_PLUGIN_LIST_PATH: management-center/config/plugins.json"

You should provide a path to plugins.json user data file with the list of plugins to load. It can look like the following:

{
    "plugins": [
        {
            "id": "audit-trail"
        },
        {
            "id": "user-management"
        },
        {
            "id": "cert-management"
        },
        {
            "id": "saml-sso"
        },
        {
            "id": "https"
        },
        {
            "id": "application-tokens"
        },
        {
            "id": "monitoring-rest-api"
        },
        {
            "id": "tls"
        },
        {
            "id": "user-profile-edit"
        },
        {
            "id": "cluster-management"
        },
        {
            "id": "connections-rest-api"
        },
        {
            "id": "custom-themes"
        },
        {
            "id": "multiple-connections"
        },
        {
            "id": "system-status-rest-api"
        },
        {
            "id": "topictree-rest-api"
        },
        {
            "id": "dynamic-security-rest-api"
        }
    ]
}
info

Adapt other environment variables according to what you had in your old setup.

  1. Start your setup as before with start scripts or docker-compose up -d

Features​

The new version added new features, which are not active by default. As usual, features are implemented via plugins, which can be turned off and on in the configuration files of the Management Center and Mosquitto. Loading plugins, which are not used can increase resources needed. This is why certain plugins need activation. To active new 2.7 features please see their documentation.