> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/1-11-0/documentation/installation-and-upgrades/upgrading-connectware/upgrading-connectware-docker/version-specific-upgrades-docker.md). # Version-Specific Upgrades (Docker) Some Connectware upgrades require you to follow a few additional steps when upgrading Connectware to a newer version. {% hint style="info" %} When upgrading your Connectware instance, follow the required upgrade path based on your current version: * If you are running Connectware version **1.0.0 to below 1.5.0**: 1. First upgrade to version 1.5.0 2. Then upgrade to version 1.7.0 3. Finally upgrade to version 1.11.0 or later * If you are running Connectware version **1.5.0 to below 1.7.0**: 1. First upgrade to version 1.7.0 2. Then upgrade to version 1.11.0 or later * If you are running Connectware version **1.7.0 to below 1.11.0**: * You can directly upgrade to version 1.11.0 or later For detailed instructions on each upgrade step, refer to: * [Upgrading Connectware to 1.11.0](#upgrading-connectware-to-1.11.0) * [Upgrading Connectware to 1.7.0](#upgrading-connectware-to-1.7.0) * [Upgrading from Connectware 1.x to 1.5.0](#upgrading-connectware-from-1.x-to-1.5.0) {% endhint %} ## Upgrading Connectware to 1.11.0 {% hint style="danger" %} We have identified a critical bug in this release. Please do not upgrade to 1.11.0. We are working on a fix that will be released soon. {% endhint %} {% hint style="info" %} Please consider that this release includes breaking changes and requires manual upgrade steps. If the current changes aren't immediately necessary for your implementation, we recommend waiting for the upcoming 1.12.0 release, which will also require manual upgrade steps. In case of questions, our Customer Success team is able to advise you. {% endhint %} Connectware 1.11.0 introduces NATS as its new Control Plane message bus and distributed state storage. As a result, you’ll need to follow a few additional steps when updating to Connectware 1.11.0 or later. Here is an overview of the required steps to upgrade your Connectware installation to version 1.11.0. For complete step-by-step instructions, see [Upgrading Procedure](#upgrading-procedure). 1. **Network Port Requirements**: Make ports TCP/4222 and TCP/4223 accessible both within Connectware and by agents. 2. **Prepare Certificate Changes**: Configure the new `cybus_nats_server.crt` certificate to include the hostname nats and any external DNS names for Connectware when using external agents. 3. **Configure DNS Names**: Define the hostnames and IPs that will be included in the NATS Server certificate. 4. **Configure mTLS Agents**: Set up agents to connect via NATS port 4222 using mTLS authentication. 5. **Configure non-mTLS Agents**: Set up agents to connect via WebSocket Secure port 4223 without mTLS. 6. **Upgrade Connectware**: Download and install Connectware 1.11.0. ### Prerequisites * **Connectware version**: Your Connectware version is 1.7.3 or above. If your Connectware installation is below 1.7.3, make sure that you have followed [Upgrading Connectware from 1.x to 1.5.0](#upgrading-connectware-from-1.x-to-1.5.0) and [Upgrading Connectware to 1.7.0](#upgrading-connectware-to-1.7.0) before upgrading to 1.11.0. * **Hardware resources**: Connectware 1.11.0 introduces two new microservices (`resource-status-tracking` and `nats`) to its architecture. This upgrade requires additional computing power. We recommend to add 3 CPU cores and 3 GB of memory to your current setup. However, these are general guidelines - check what your specific system needs and make adjustments accordingly. ### Upgrading Procedure {% stepper %} {% step %} #### Network Port Requirements Connectware 1.11.0 introduces new network port requirements. Configure your network so that the following ports are accessible both within Connectware and by agents: * **TCP/4222** * **TCP/4223** **Minimal requirements**: For installations requiring minimal firewall openings, you can configure the following: * Port TCP/4222 must be accessible within the Connectware network * For agents using mTLS authentication, port TCP/4222 must be accessible * For agents using username/password authentication, port TCP/4223 must be accessible Verify both internal and external port accessibility to ensure proper communication between Connectware and its agents. {% endstep %} {% step %} #### Preparing Certificate Breaking Changes Connectware 1.11.0 introduces a new `cybus_nats_server.crt` certificate which must contain the hostname `nats`, as well as the external DNS name of Connectware if you are using any external agents. The configuration depends on whether you are using the built-in certificate infrastructure or a custom infrastructure. **2.1 When Using the Built-in Certificate Infrastructure** If you're using the built-in certificate infrastructure: 1. Do NOT proceed with the upgrade until you've completed [Configuring DNS Names for Agent Connections](#configuring-dns-names-for-agent-connections). 2. When updating DNS names, you must add the DNS name used by external agents to connect to Connectware. 3. Be aware that the upgrade will regenerate the certificate. * This may affect systems using certificate pinning. * Update any certificate pinning configurations after the upgrade. **2.2 When Using Custom Certificates** If you have modified the certificate infrastructure or use a custom `cybus_server.crt`: 1. Prepare a new `cybus_nats_server.crt` certificate that meets these requirements: * Must be signed by your existing Certificate Authority (CA). * Must include `nats` as a Subject Alternative Name (SAN). * Must include your external Connectware DNS name as a SAN. 2. Installation steps: * Install the new certificate before starting the upgrade. * Update your .env file to include the same external DNS name used in your certificate (See [Configuring DNS Names for Agent Connections](#configuring-dns-names-for-agent-connections)). 3. Certificate protection (optional): To prevent your custom certificate from being replaced during the upgrade, set the environment variable `CYBUS_DISABLE_NATS_CERTIFICATE_CHECKS` to `true` on the system-control-server in your docker-compose.override.yaml file. {% endstep %} {% step %} #### Configuring DNS Names for Agent Connections The `CYBUS_INGRESS_DNS_NAMES` environment variable specifies the hostnames and IP addresses that will be included in the Subject Alternative Names (SAN) section of the NATS server certificate. This certificate is automatically generated by Connectware. {% hint style="info" %} This certificate configuration only affects the `cybus_nats_server.crt` file. Any hostnames that you specify in the `CYBUS_INGRESS_DNS_NAMES` variable will not be included in the `cybus_server.crt` certificate that is used by other services such as the Admin UI. {% endhint %} * To enable agent connections to the Control Plane, you must configure the DNS names in the `.env` file located in the main Connectware installation directory. **Example** For a basic setup where Connectware runs on a host named `company.io`, set: {% code lineNumbers="true" %} ```yaml CYBUS_INGRESS_DNS_NAMES=company.io ``` {% endcode %} * You can specify multiple values by separating them with commas. This allows you to define any hostnames, wildcard domains, and IP addresses that agents use to connect to the Control Plane. All values are added to the certificate's SAN field, enabling secure agent connections through any of the configured access points. **Example** {% code lineNumbers="true" %} ```yaml CYBUS_INGRESS_DNS_NAMES=company.io,localhost,*.company.io,connectware.company.io,192.168.100.42 ``` {% endcode %} {% endstep %} {% step %} #### Configuring Agents using mTLS For agents using mTLS authentication, configure the Control Plane connection using NATS and the port `4222`. Each agent requires a Control Plane URI environment variable that references one of the `CYBUS_INGRESS_DNS_NAMES` hostnames that you have defined in [Configuring DNS Names for Agent Connections](#configuring-dns-names-for-agent-connections). Configure this variable in the agent's docker-compose.yml file or via command line. * For agents running with Docker Compose, set the `CYBUS_CONTROLPLANE_URI` environment variable in their docker-compose.yml file: **Example** {% code lineNumbers="true" %} ```yaml CYBUS_CONTROLPLANE_URI: 'nats://company.io:4222' ``` {% endcode %} * For agents running without Docker Compose, set the `CYBUS_CONTROLPLANE_URI` environment variable according to your deployment method. #### Certificate Configuration Agents will use their existing mTLS certificates as configured during the initial agent installation. No additional certificate configuration is required during the upgrade process, provided the agents were previously set up with valid mTLS certificates according to [Installing Agents - Enabling Mutual TLS (mTLS)](https://docs.cybus.io/documentation/agents/installing-agents#enabling-mutual-tls-mtls). {% endstep %} {% step %} #### Configuring Agents not using mTLS For agents **not** using mTLS authentication, configure the Control Plane connection using WebSocket Secure (WSS) and the port `4223`. Each agent requires a Control Plane URI environment variable that references one of the `CYBUS_INGRESS_DNS_NAMES` hostnames that you have defined in [Configuring DNS Names for Agent Connections](#configuring-dns-names-for-agent-connections). Configure this variable in the agent's docker-compose.yml file or via command line. * For agents running with Docker Compose, set the `CYBUS_CONTROLPLANE_URI` environment variable in their docker-compose.yml file: **Example** {% code lineNumbers="true" %} ```yaml CYBUS_CONTROLPLANE_URI: 'wss://company.io:4223' ``` {% endcode %} * For agents running without Docker Compose, set the `CYBUS_CONTROLPLANE_URI` environment variable according to your deployment method. #### Certificate Configuration When using agents with username and password, you can configure the authentication of the agents to the Connectware server during Control Plane connections. You have two options: * Set the `TRUST_ALL_CERTS` environment variable on the agent to bypass certificate verification entirely * Authenticate using certificates. For certificate authentication, ensure that the agent trusts the CA certificate that signed Connectware's cybus\_nats\_server.crt. This is only done automatically if you are using a globally trusted certificate for Connectware - otherwise, you need to provide the agent with the appropriate CA certificate. The following table shows the result of configuring `TRUST_ALL_CERTS` and providing the CA certificate. {% hint style="info" %} `TRUST_ALL_CERTS` affects all certificate validations, not just Connectware connections. Always test any changes to this setting in a staging environment before deploying to production. {% endhint %} | CA certificate | Value of `TRUST_ALL_CERTS` | Behavior | Log shown during connection | | -------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | Not Configured | true | **Default**: The connection to Control Plane (NATS) will not validate certs and will trust all certs. | CA certificate not found, trusting all certificates for NATS connection. | | Not Configured | false | The connection to Control Plane (NATS) will try to use the system trust store to do certificate validation. This will only work when the CAs being used in Connectware are signed by a well known CA authority or when self-signed CAs were added to the system trust store. | CA certificate not found, using system trusted CAs for NATS connection. | | Configured | true | The connection to Control Plane (NATS) will not validate server certs and will trust any cert. | CA certificate found, but trusting all certificates for NATS connection. | | Configured | false | The connection to Control Plane (NATS) will validate server certs and will not trust any cert. | CA certificate found, using it for NATS connection with CA verification. | | {% endstep %} | | | | {% step %} #### Upgrading Connectware to 1.11.0 * To upgrade Connectware to 1.11.0, see [Upgrading Connectware (Docker)](/1-11-0/documentation/installation-and-upgrades/upgrading-connectware/upgrading-connectware-docker.md). {% endstep %} {% endstepper %} ## Upgrading Connectware to 1.7.0 Connectware 1.7.0 affects the backward compatibility of the Connectware broker. Older broker data volumes are not compatible with brokers of Connectware 1.7.0 and newer. Upgrading to Connectware 1.7.0 requires additional upgrade procedures. Additionally, multi-factor authentication (MFA) is now controlled via a dedicated configuration switch. ### Important Notes This upgrade will delete all persisted data of the Connectware broker. This includes client sessions, subscriptions, and retained data. If your configuration relies on any type of data persisted by the broker, make sure to properly initialize your applications after the upgrade. If you rely on persisted data, create a backup or snapshot of the broker data volumes. This allows you to roll back in case of complications. ### Upgrading Procedure 1. **Important:** If your Connectware installation is below 1.5.0, make sure that you have followed [Upgrading from 1.x to 1.5.0](#upgrading-from-1x-to-150) before upgrading to 1.7.0. 2. To stop Connectware, go to the Connectware installation directory (default: `/opt/connectware`) and run `docker compose down`. 3. Delete the broker data volume of Connectware. Find the broker data volume in the list of volumes with `docker volume ls` and delete it with `docker volume rm `. 4. If you are using multi-factor authentication (MFA), set the environment variable `CYBUS_MFA_ENABLED` to `true` inside your .env file. 5. Download and install the new Connectware version. For more information, see [Upgrading Connectware (Docker)](/1-11-0/documentation/installation-and-upgrades/upgrading-connectware/upgrading-connectware-docker.md). ## Upgrading Connectware from 1.x to 1.5.0 This section 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)](/1-11-0/documentation/industry-protocol-details/hottinger-baldwin-messtechnik-hbm.md) * [OPC DA](/1-11-0/documentation/industry-protocol-details/opc-da.md) 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](/1-11-0/documentation/agents/registering-agents-in-connectware.md). ### Upgrading Connectware 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 {% stepper %} {% step %} #### 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. {% endstep %} {% step %} #### 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="/files/Tc3nwS1myzEt5pLTIO85" %} 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`. {% endstep %} {% step %} #### 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 %} {% endstep %} {% step %} #### 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. {% endstep %} {% step %} ### 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. {% endstep %} {% endstepper %} ### Upgrading Connectware agents Connectware agents are ideally orchestrated using Docker Compose as described in [agent orchestration](/1-11-0/documentation/agents/registering-agents-in-connectware.md). 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) *OR* * Adjust your docker composition to continue running with higher 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 {% stepper %} {% step %} #### 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. {% endstep %} {% step %} #### 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="/files/pGkzije6szrE8XibeNXq" %} 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`. {% endstep %} {% step %} #### 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 %} {% endstep %} {% step %} #### 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. {% endstep %} {% step %} #### 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. {% endstep %} {% endstepper %} #### 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: {% 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 simply add `--user=root` to the command. In case of any questions or trouble, feel free to contact Cybus Support. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cybus.io/1-11-0/documentation/installation-and-upgrades/upgrading-connectware/upgrading-connectware-docker/version-specific-upgrades-docker.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.