# Upgrading Connectware from 1.x to 1.5.0 (Docker) This guide describes the upgrade of a Cybus Connectware installation from a previous 1.x version to 1.5.0 and later. {% hint style="danger" %} 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. {% endhint %} 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: * [Hottinger Baldwin Messtechnik (HBM)](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/hottinger-baldwin-messtechnik-hbm) * [OPC DA](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/opc-da) 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](https://docs.cybus.io/2-0-6/documentation/agents/registering-agents-in-connectware). ## 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: 1. Shut down Connectware 2. Save the provided file as `docker-compose.override.yml` in the same folder as your Connectware `docker-compose.yml` 3. Start the the Docker composition to adjust volume permissions 4. Remove the `docker-compose.override.yml` file 5. Upgrade Connectware using the `connectware-online-installer.sh` script ### Step-by-Step Procedure
1. Shut Down Connectware Within your installation folder, execute `docker compose down`. Run the command as you would usually do, be that as a regular user, using `sudo` or as the user `root` directly.
2. Download & Save Override File Use this file as `docker-compose.override.yml`: {% code lineNumbers="true" %} ```yaml version: '2.0' services: connectware-fix-permissions: user: root image: registry.cybus.io/cybus/connectware-fix-permissions:1.5.0 volumes: - certs:/mnt/connectware_certs - brokerLog:/mnt/connectware_brokerLog - brokerData:/mnt/connectware_brokerData - postgresql:/mnt/connectware_postgresql - service-manager:/mnt/connectware_service-manager - systemControlServerData:/mnt/connectware_systemControlServerData - workbench:/mnt/connectware_workbench admin-web-app: profiles: - do-not-start auth-server: profiles: - do-not-start broker: profiles: - do-not-start connectware: profiles: - do-not-start container-manager: profiles: - do-not-start doc-server: profiles: - do-not-start ingress-controller: profiles: - do-not-start postgresql: profiles: - do-not-start protocol-mapper: profiles: - do-not-start service-manager: profiles: - do-not-start system-control-server: profiles: - do-not-start workbench: profiles: - do-not-start ``` {% endcode %} {% file src="" %} If you already have a `docker-compose.override.yml` file for your Connectware installation, make sure to rename it before storing this file as `docker-compose.override.yml`.
3. Adjust Volume Permissions Run `docker compose up`. Run the command as you would usually do, be that as a regular user, using `sudo` or as the user `root` directly. You should see output similar to this: {% code lineNumbers="true" %} ```yaml [+] Building 0.0s (0/0) [+] Running 1/0 ✔ Container connectware-connectware-fix-permissions-1 Created 0.0s Attaching to connectware-connectware-fix-permissions-1 connectware-connectware-fix-permissions-1 | Found directory: connectware_brokerData. Going to change permissions connectware-connectware-fix-permissions-1 | Found directory: connectware_brokerLog. Going to change permissions connectware-connectware-fix-permissions-1 | Found directory: connectware_certs. Going to change permissions connectware-connectware-fix-permissions-1 | Found directory: connectware_postgresql. Going to change permissions connectware-connectware-fix-permissions-1 | Postgresql volume identified, using postgresql specific permissions connectware-connectware-fix-permissions-1 | Found directory: connectware_service-manager. Going to change permissions connectware-connectware-fix-permissions-1 | Found directory: connectware_systemControlServerData. Going to change permissions connectware-connectware-fix-permissions-1 | Found directory: connectware_workbench. Going to change permissions connectware-connectware-fix-permissions-1 | All done. Found 7 volumes. connectware-connectware-fix-permissions-1 exited with code 0 ``` {% endcode %}
4. Remove Override File Run `docker compose down` to remove the temporary permissions fix container. Run the command as you would usually do, be that as a regular user, using `sudo` or as the user `root` directly. Next, delete the file `docker-compose.override.yml`. If you used a `docker-compose.override.yml` in your installation before this update, restore your original file.
5. Upgrade Connectware Download and run the Connectware online installer like for other updates: {% code lineNumbers="true" %} ```yaml wget https://download.cybus.io/1.5.0/connectware-online-installer.sh chmod +x connectware-online-installer.sh ./connectware-online-installer.sh ``` {% endcode %} Run the commands as you would usually do, be that as a regular user, using `sudo` or as the user `root` directly. After updating you can start Connectware as usual. If you wish to verify that Connectware services run with an unprivileged user, you can optionally run this command: {% code lineNumbers="true" %} ```yaml docker ps -qf="label=io.cybus.connectware=core" | xargs -I % docker exec % sh -c 'echo "$(hostname) runs with user ID $(id -u)"' ``` {% endcode %} Only the service `container-manager` should be using the user ID `0`. In case of any questions or trouble, feel free to contact Cybus Support.
## Upgrading Connectware Agents Connectware agents are ideally orchestrated using Docker Compose as described in [agent orchestration](https://docs.cybus.io/2-0-6/documentation/agents/registering-agents-in-connectware). 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](#upgrading-agents-by-adjusting-volumes). *OR* * Adjust your docker composition to continue running with higher privileges. [Upgrading by Using Root 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: 1. Shut down the agent 2. Save the provided file as `docker-compose.override.yml` in the same folder as your agent’s `docker-compose.yml` 3. Start the the Docker composition to adjust volume permissions 4. Remove the `docker-compose.override.yml` file 5. Upgrade the agent by adjusting the image tag in your `docker-compose.yml` file
1. Shut Down Agent Within your agent’s installation folder, execute `docker compose down`. Run the command as you would usually do, be that as a regular user, using `sudo` or as the user `root` directly.
2. Download & Save Override File Use this file as `docker-compose.override.yml`: {% code lineNumbers="true" %} ```yaml 1version: '2.0' 2services: 3 connectware-fix-permissions: 4 user: root 5 image: registry.cybus.io/cybus/connectware-fix-permissions:1.5.0 6 volumes: 7 - protocol-mapper-agent:/mnt/connectware_agent_data 8 protocol-mapper-agent: 9 profiles: 10 - do-not-start ``` {% endcode %} {% file src="" %} If you use a different name for your agent Docker service and volume than our example, you need to adjust the highlighted line to the name you use for your agent and its volume inside your `docker-compose.yml` file. If you already have a `docker-compose.override.yml` file for your agent’s installation directory, make sure to rename it before storing this file as `docker-compose.override.yml`.
3. Adjust Volume Permissions Run `docker compose up`. Run the command as you would usually do, be that as a regular user, using `sudo` or as the user `root` directly. You should see output similar to this: {% code lineNumbers="true" %} ```yaml [+] Building 0.0s (0/0) [+] Running 2/2 ✔ Network agent_default Created 0.1s ✔ Container agent-connectware-fix-permissions-1 Created 0.1s Attaching to agent-connectware-fix-permissions-1 agent-connectware-fix-permissions-1 | Found directory: connectware_agent_data. Going to change permissions. agent-connectware-fix-permissions-1 | All done. Found 1 volumes. agent-connectware-fix-permissions-1 exited with code 0 ``` {% endcode %}
4. Remove Override File Run `docker compose down` to remove the temporary permissions fix container. Run the command as you would usually do, be that as a regular user, using `sudo` or as the user `root` directly. Next, delete the file `docker-compose.override.yml`. If you used a `docker-compose.override.yml` for your agent before this update, restore your original file.
5. Upgrade the Agent Set the image tag used for the agent to the same tag that your current Connectware installation uses, but at least `1.5.0`. If you have not yet upgraded your Connectware to at least version `1.5.0`, please do so now. Example: {% code lineNumbers="true" %} ```yaml version: '2.0' services: protocol-mapper-agent: 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: ``` {% endcode %} 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. In case of any questions or trouble, feel free to contact Cybus Support.
### 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, 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: {% code lineNumbers="true" %} ```yaml 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: ``` {% endcode %} 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 add `--user=root` to the command. In case of any questions or trouble, feel free to contact Cybus Support.