LogoLogo
Contact Uscybus.io
Connectware 1.10.2
Connectware 1.10.2
  • Getting Started
    • Introduction
    • System Requirements
    • Connectware Admin UI
    • Basic Components of Connectware
    • Connecting your First Machine
      • Your First Service Commissioning File
  • Documentation
    • Installation and Upgrades
      • Installing Connectware
        • Installing Connectware (Kubernetes)
        • Installing Connectware (Docker)
      • Upgrading Connectware
        • Upgrading Connectware (Kubernetes)
          • Version-Specific Upgrades (Kubernetes)
        • Upgrading Connectware (Docker)
          • Version-Specific Upgrades (Docker)
      • Uninstalling Connectware
        • Uninstalling Connectware (Kubernetes)
        • Uninstalling Connectware (Docker)
      • Licensing
    • User Management
      • Users and Roles View
      • Users
      • Roles
      • Permissions
      • Password Policy Rules
      • Default Admin User
      • MQTT Users
      • Adding a MQTT Publish Prefix for Users
      • Multi-Factor Authentication
      • Single Sign-On (SS0)
        • Single Sign-On with Microsoft Entra ID
        • Single Sign-On with LDAP
      • JSON Web Tokens
      • Access Permissions for Admin-UI
        • UI Access
        • Minimum Access Role Pages
    • Services
      • Service Overview
      • Service Resources View
        • Service Links View
        • Servers View
        • Containers View
        • Volumes View
        • Connections View
        • Endpoints View
        • Mappings View
      • Service Details View
      • Service Commissioning Files
        • Version
        • Description
        • Metadata
        • Parameters
        • Definitions
        • Resources
          • Cybus::Connection
          • Cybus::Container
            • Docker Problem with Network Changes
          • Cybus::Endpoint
          • Cybus::File
          • Cybus::IngressRoute
          • Cybus::Link
          • Cybus:Mapping
          • Cybus::Node
          • Cybus::Role
          • Cybus::Server
          • Cybus::User
          • Cybus::Volume
      • Setting Up and Configuring Services
        • Installing Services
        • Enabling Services
        • Updating Services
        • Disabling Services
        • Deleting Services
      • FlowSync
        • Example 1 - Node with Transaction Mode (HTTP)
        • Example 2 - Node Responds (HTTP)
        • Example 3 - Node with Error (HTTP)
        • Example 4 - Node with Timeout Error Code and Error Message (HTTP)
        • Example 5 - Full Transactional Data Flow (HTTP)
        • Example 6 - Full Transactional Data Flow (OPC UA)
      • ServiceID
      • Inter-Service Referencing
      • Deviation
      • Service Logs
        • Logs of Individual Services
        • Logs of All Services
      • Rule Engine
        • Data Processing Rules
        • Rule Sandbox
      • Shared Subscriptions
        • Setting Up Shared Subscriptions
    • Agents
      • Agents View
      • Installing Agents
        • Installing Agents via Docker
        • Installing Agents via Docker Compose
        • Installing Agents via Kubernetes
        • Using Mutual TLS for Agents
      • Registering Agents in Connectware
      • Using Agents
      • Monitoring Agents
      • Agents in Kubernetes
        • Adding Agents Inside your Connectware Installation
        • Remote Agents with the connectware-agent Helm Chart
        • Kubernetes Cluster Requirements for the connectware-agent Helm Chart
        • Installing Connectware Agents using the connectware-agent Helm Chart
        • Installing Connectware Agents without a License Key Using the connectware-agent Helm Chart
        • Upgrading the connectware-agent Helm Chart
        • Uninstalling Connectware agents with the connectware-agent Helm chart
        • Configuration Principles for the connectware-agent Helm Chart
        • Configuring Agents with the connectware-agent Helm Chart
          • Configuring Target Connectware for the connectware-agent Helm Chart
          • Configuring Agent Persistence for the connectware-agent Helm Chart
          • Configuring Compute Resources for the connectware-agent Helm Chart
          • Using a Custom Image Registry for the connectware-agent Helm Chart
          • Configuring Image Pull Policy for the connectware-agent Helm Chart
          • Using Mutual Transport Layer Security (mTLS) for agents with the connectware-agent Helm chart
          • Configuring image name and version for the connectware-agent Helm chart
          • Configuring Environment Variables for the connectware-agent Helm Chart
          • Configuring Labels and Annotations for the connectware-agent Helm Chart
          • Configuring podAntiAffinity for the connectware-agent Helm Chart
          • Assigning Agents to Kubernetes Nodes for the connectware-agent Helm Chart
          • Configuring Security Context for the connectware-agent Helm Chart
          • Controlling the Name of Kubernetes Objects for the connectware-agent Helm Chart
      • Troubleshooting Agents
    • Client Registry
      • Implicit Flow
      • Explicit Flow
      • Granting Access
    • Certificates
    • Monitoring
      • Data Explorer
      • Live Data
    • Workbench
      • Flows in Git Repositories
    • System Status
      • Info
      • Metrics
      • Status
      • Retrieving More System Information
      • System Health
    • Backup and Restore
      • Volumes
      • User Database
    • Connectware on Kubernetes
      • Connectware Helm Chart
      • Resizing Broker Volumes in Kubernetes
      • Configuring Core Services
      • LDAP Authentication
        • Configuring LDAP Authentication
        • Enabling TLS for LDAP Authentication
        • Manual Kubernetes Secret for LDAP Authentication Bind User
        • Customizing the Search Filter for LDAP Authentication
        • Customizing the User RDN for LDAP Authentication
      • Troubleshooting Connectware on Kubernetes
    • Environment Variables
    • Industry Protocol Details
      • ADS
        • ADS Connection Properties
        • ADS Endpoint Properties
      • BACnet
        • BACnet Connection Properties
        • BACnet Endpoint Properties
      • Custom Connectors
        • Developing Custom Connectors
        • Deploying Custom Connectors
        • Using Custom Connectors
      • EtherNet/IP
        • EtherNet/Ip Connection Properties
        • EtherNet/Ip Endpoint Properties
      • FOCAS
        • FOCAS Connection Properties
        • FOCAS Endpoint Properties
      • Hottinger Baldwin Messtechnik (HBM)
        • HBM Connection Properties
        • HBM Endpoint Properties
      • Heidenhain DNC
        • Heidenhain DNC Connection Properties
        • Heidenhain DNC Endpoint Properties
      • HTTP/REST
        • HTTP/REST Connection Properties
        • HTTP/REST Endpoint Properties
      • HTTP Server/Node
        • HTTP Server Properties
        • HTTP Node Properties
      • InfluxDB
        • InfluxDB Connection Properties
        • InfluxDB Endpoint Properties
      • Kafka
        • Kafka Connection Properties
        • Kafka Endpoint Properties
      • Modbus/TCP
        • Modbus/TCP Connection Properties
        • Modbus/TCP Endpoint Properties
      • MQTT
        • MQTT Connection Properties
        • MQTT Endpoint Properties
      • MSSQL
        • Mssql Connection Properties
        • Mssql Endpoint Properties
      • OPC DA
        • OPC DA Connection Properties
        • OPC DA Endpoint Properties
      • OPC UA
        • OPC UA Client
          • OPC UA Client Connection Properties
          • OPC UA Client Endpoint Properties
        • OPC UA Server
          • OPC UA Server Properties
          • OPC UA Node Properties
        • OPC UA Object Types
        • OPC UA Server References
          • OPC UA Reference Node
          • OPC UA Object Node
      • Siemens SIMATIC S7
        • Siemens S7 Connection Properties
        • Siemens S7 Endpoint Properties
      • Shdr
        • Shdr Connection Properties
        • Shdr Endpoint Properties
      • SINUMERIK
        • SINUMERIK Connection Properties
        • SINUMERIK Endpoint Properties
      • SOPAS
        • SOPAS Connection Properties
        • SOPAS Endpoint Properties
      • SQL
        • SQL Connection Properties
        • SQL Endpoint Properties
      • Werma WIN Ethernet
        • Werma WIN Ethernet Connection Properties
        • Werma WIN Ethernet Endpoint Properties
      • Systemstate
        • Systemstate Connection Properties
        • Systemstate Endpoint Properties
    • API Reference
      • User Management (API)
      • Client Registry (API)
      • Services (API)
      • Resources (API)
      • System Status (API)
      • Industry Protocol Details (API)
    • Changelog
      • General changes from 0.x to 1.0
        • Upgrading from 0.x to 1.0
Powered by GitBook
LogoLogo

Cybus

  • Terms and Condition
  • Imprint
  • Data Privacy

© Copyright 2025, Cybus GmbH

On this page
  • Upgrading from 1.x to 1.7.0
  • Important Notes
  • Upgrading Procedure
  • Upgrading from 1.x to 1.5.0
  • Upgrading Connectware
  • Upgrading Connectware agents

Was this helpful?

  1. Documentation
  2. Installation and Upgrades
  3. Upgrading Connectware
  4. Upgrading Connectware (Docker)

Version-Specific Upgrades (Docker)

PreviousUpgrading Connectware (Docker)NextUninstalling Connectware

Last updated 23 days ago

Was this helpful?

The following Connectware upgrades require you to follow a few additional steps when upgrading Connectware to a newer version:

  • Upgrading from 1.x to 1.7.0

  • Upgrading from 1.x to 1.5.0

Upgrading from 1.x 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 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 <connectware_brokerData>.

  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 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.

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.

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

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:

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

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:

[+] 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
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:

wget https://download.cybus.io/1.5.0/connectware-online-installer.sh
chmod +x connectware-online-installer.sh
./connectware-online-installer.sh

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:

docker ps -qf="label=io.cybus.connectware=core" | xargs -I % docker exec % sh -c 'echo "$(hostname) runs with user ID $(id -u)"'

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

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

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:

 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

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:

[+] 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
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:

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:

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, 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.

To learn how to configure an agent to operate with root permissions, check out the section on .

Connectware agents are ideally orchestrated using Docker Compose as described in .

Hottinger Baldwin Messtechnik (HBM)
OPC DA
agent orchestration
agent orchestration
Connectware installation guide
Upgrading from 1.x to 1.5
1KB
upgrade-1-5-docker-compose.override.yml
303B
upgrade-1-5-agent-docker-compose.override.yml