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.
- Documentation: Visit the respective docs to learn how to configure and utilize the new features available in version 2.9. 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 features you are upgrading to, 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 at support@cedalo.com.
2.9
Migration steps for Cedalos Pro Edition of Mosquitto and MMC from version 2.8 to the new version 2.9. We are excited to introduce the enhancements and improvements in this latest release. To ensure a smooth transition, please follow the steps outlined below.
Upgrading the existing installation:
- 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.
- Docker Image Update Required: The primary change involves updating the Docker image for our Cedalo Registry.
- Please update your systems to use the new images:
- For Mosquitto:
registry.cedalo.com/mosquitto/mosquitto:2.9
- For Management Center Premium:
registry.cedalo.com/development/management-center-premium:2.9
- For Mosquitto:
- Alternative Download Option: If you prefer, you can also download the new
.rpm
package from our repository for a manual update.
2.8
Migration steps for upgrading your system from version 2.7 to version 2.8. To ensure a smooth transition, please follow the steps outlined below:
- 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
- For Mosquitto:
- 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:
- Email: support@cedalo.com
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
- Add the following environment variable to the management center:
CEDALO_MC_PROXY_HOST: 0.0.0.0
- 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.
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"
}
]
}
- 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
- 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
- Place your license to where
/management-center/config
or a different location whereCEDALO_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:
Splitting single docker-compose into 3 files for each node and having haproxy before each node (recommended approach)
- 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/
- Move the contents of your old setup's
haproxy
folder into:
setup_directory/server1/haproxy/
setup_directory/server2/haproxy/
setup_directory/server3/haproxy/
- Move the contents of your old setups's
mosquitto1
,mosquitto2
, andmosquitto3
folders into:
setup_directory/server1/mosquitto/
setup_directory/server2/mosquitto/
setup_directory/server3/mosquitto/
respectively.
Move the contents of your old setup's
management-center/config
folder intosetup_directory/management-center/config/
.Add your license or move an old one from
management-center/config
(ormosquitto1/license
/mosquitto2/license
/mosquitto3/license
) to:
setup_directory/server1/license/
setup_directory/server2/license/
setup_directory/server3/license/
All three locations should contain the same license.
- Add the following
docker-compose.yml
tosetup_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 onlymosquitto1
andhaproxy
, andmanagement-center
remain.
Now, rename mosquitto1
service into mosquitto
.
Change mosquitto image to
registry.cedalo.com/mosquitto/mosquitto:2.7
and MMC toregistry.cedalo.com/mosquitto/management-center:2.7
Make sure
mosquitto
service has the followinghostname
section:
hostname: mosquitto1
Update
management-center/networks/mosquitto/ipv4_address
value and set it to172.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"
}
]
}
Adapt other environment variables according to what you had in your old setup.
- Add the following
docker-compose.yml
tosetup_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.
- Add the following
docker-compose.yml
tosetup_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
.
- 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.
Change mosquitto images to
registry.cedalo.com/mosquitto/mosquitto:2.7
. Change MMC image toregistry.cedalo.com/mosquitto/management-center:2.7
Update your licenses in
management-center/config
,mosquitto1/license
,mosquitto2/license
, andmosquitto3/license
.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 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"
}
]
}
Adapt other environment variables according to what you had in your old setup.
- 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.