Upgrading Connectware from 1.x to 1.5.0 (Docker)
This section describes the upgrade of a Cybus Connectware installation from a previous 1.x version to 1.5.0 and later.
The additional upgrade steps require you to use the docker-compose.override.yml
file. If you already use such a file in your Connectware installation directory make sure to create a backup of this file to later restore.
In Connectware 1.5.0, we’ve enhanced security by primarily using a system user with limited permissions, following the principle of using the least amount of privilege needed for our software components.
As a result, you’ll need to follow a few additional steps when updating to Connectware 1.5.0 or later.
The first part of this document covers updating Connectware, while the second part focuses on agents.
With the introduction of Connectware 1.5.0, which prefers to use a system user with limited privileges whenever possible, you’ll need to modify the permissions of your volumes. This ensures that the system user has the necessary write access to the existing volumes in your setup.
The following protocols may not operate as expected in some constellations:
If you experience problems with these protocols after upgrading to Connectware 1.5.0, these affected services may require root permissions and are no longer supported by the internal protocol-mapper or agents without root permissions.
In this case, you should transfer the service that uses these protocols to a separate agent. This agent can have higher permissions but in a controlled manner.
To learn how to configure an agent to operate with root permissions, check out the section on agent orchestration.
Disclaimer
Some Connectware upgrades require you to follow a few additional steps when upgrading Connectware to a newer version.
When upgrading your Connectware instance, follow the required upgrade path based on your current version:
If you are running Connectware version 1.4.1 or below:
First upgrade to version 1.5.0
Then upgrade to version 1.7.0
Finally upgrade to version 2.0.0
If you are running Connectware version between 1.5.0 and 1.6.2:
First upgrade to version 1.7.0
Then upgrade to version 2.0.0
If you are running Connectware version 1.7.0 or later:
You can directly upgrade to version 2.0.0
For detailed instructions on each upgrade step, refer to:
Upgrading Procedure
As an additional step for this upgrade, we offer a docker-compose.override.yml
file, which will help you adjusting volume permissions. The upgrade will consist of the following steps:
Shut down Connectware
Save the provided file as
docker-compose.override.yml
in the same folder as your Connectwaredocker-compose.yml
Start the the Docker composition to adjust volume permissions
Remove the
docker-compose.override.yml
fileUpgrade Connectware using the
connectware-online-installer.sh
script
Step-by-Step Procedure
Upgrading Connectware Agents
Connectware agents are ideally orchestrated using Docker Compose as described in agent orchestration.
In order to upgrade your agents, you need to decide between these two options:
Adjust volume permissions to allow the unprivileged system user to write data (recommended). See Upgrading Agents by Adjusting Volumes.
OR
Adjust your docker composition to continue running with higher privileges. Upgrading by Using Root Privileges.
To benefit from the improvements to security, we recommend to adjust volume permissions over continuing to run with higher privileges.
If you are using HBM DAQ or OPC DA, you may need to follow the second option of continuing with higher privileges.
Upgrading Agents by Adjusting Volumes
If you choose to adjust volume permissions, we offer a docker-compose.override.yml
which will help you adjusting volume permissions. The upgrade will consist of the following steps:
Shut down the agent
Save the provided file as
docker-compose.override.yml
in the same folder as your agent’sdocker-compose.yml
Start the the Docker composition to adjust volume permissions
Remove the
docker-compose.override.yml
fileUpgrade the agent by adjusting the image tag in your
docker-compose.yml
file
Upgrading by Using Root Privileges
If you have not yet upgraded your Connectware to at least version 1.5.0
, please do so first.
As an alternative to modifying volume permissions, or if you use a protocol that requires elevated permissions, you can modify your agent’s docker-compose.yml
file to specify the system user which is used for the container.
To do so, simply add user: root
to the docker compose service of your agent, while adjusting the image tag to the same tag that your current Connectware installation uses, but at least 1.5.0
, as highlighted in this example:
version: '2.0'
services:
protocol-mapper-agent:
user: root
image: registry.cybus.io/cybus/protocol-mapper:1.5.0
environment:
CYBUS_AGENT_MODE: distributed
CYBUS_AGENT_NAME: myAgent
CYBUS_MQTT_HOST: 172.17.0.1
volumes:
- protocol-mapper-agent:/data
restart: unless-stopped
network_mode: host
hostname: myAgent
volumes:
protocol-mapper-agent:
You can now start your agent as usual, for example by running docker compose up -d
. Run the command as you would usually do, be that as a regular user, using sudo
or as the user root
directly.
If you use a docker run
command, you can simply add --user=root
to the command.
In case of any questions or trouble, feel free to contact Cybus Support.
Last updated
Was this helpful?