Installing Agents
Last updated
Was this helpful?
Connectware 1.8.0
Last updated
Was this helpful?
To install an agent, you must start a Docker container. The container image that is used is the same as the Connectware protocol mapper image. The version (or image tag) of the container must match the Connectware version exactly, otherwise the agent will not be able to communicate with Connectware.
You can deploy agents using various orchestration tools:
Docker CLI: Run a docker run command.
Docker Compose: Use docker compose with a docker-compose.yml configuration file.
Kubernetes: Deploy to a Kubernetes cluster using appropriate manifests.
In all cases, you must configure the agent using environment variables that are passed to the container. This ensures consistent configuration across different deployment methods, allowing you to customize the agent's behavior regardless of the orchestration tool.
Select the orchestration tool that best suits your infrastructure and operational requirements.
Docker
Use the docker run command for simple, single-container deployments. See
Docker Compose
Create a docker-compose.yml file for multi-container applications or more complex configurations. See
Kubernetes
Deploy agents to a Kubernetes cluster for advanced orchestration and scaling capabilities. See
Choose the method that best suits your infrastructure and operational requirements.
You can configure agent containers using environment variables that allow you to customize agent behavior and connection settings. How to set these variables depends on your deployment method:
For a Docker Compose setup, we recommend specifying the environment variable values in an .env file, placed in the same directory as the docker-compose.yml file. These files are located in your Connectware installation directory, which is /opt/connectware if the default installation values were used.
For Kubernetes, we provide a Helm Chart that includes a values.yaml file to configure environment variables.
Here are the environment variables that are used for agent configuration:
CYBUS_AGENT_MODE=distributed
Configures the protocol-mapper to operate in agent mode.
CYBUS_AGENT_NAME=<agentName>
Defines a unique identifier for the current agent instance.
CYBUS_MQTT_HOST=<connectwareHost>
Specifies the IP address or hostname of the Connectware server.
CYBUS_MQTT_USERNAME=<userName>
Authentication username for Connectware. Default value: <agentName>
CYBUS_MQTT_SCHEME=<scheme>
MQTT connection scheme (mqtts or mqtt). Default value: mqtt
CYBUS_MQTT_PORT=<port>
Port number for MQTT connection. Default values: MQTT 1883, MQTTS 8883
To ensure your agent's credentials persist across container restarts and system reboots, we recommend implementing credential persistence.
Create a Docker volume and mount it to the agent container.
Configure the volume to be mounted at the /data path within the container.
Once completed, the agent will automatically:
Store its credentials on the mounted volume.
Retrieve and reuse these credentials during subsequent startups.
If multiple agents are running on the same machine, each agent must use its own volume mount. Otherwise, the agents will overwrite each other's data, including username and password credentials.
As an alternative to generating credentials locally, you can set a password for the protocol-mapper agent using the CYBUS_PROTOCOL_MAPPER_PASSWORD environment variable. This is useful if the agent deployment is managed by the same orchestration tool as the central Connectware instance.
To display a custom hostname, set the hostname property of your Docker container to match the hostname of the local host.
Depending on your operating system, the appropriate value for the hostname may be available as a ${HOSTNAME} environment variable, or it can be specified manually, as shown in the example below.
By default, agents run as an unprivileged user. However, certain protocols or features, such as USB access or promiscuous network mode, require root privileges.
To use a feature that requires root access, run the agent as the root user.
If you want to use mutual TLS, you must enable it for the broker and for the protocol-mapper:
Environment variable for the broker: CYBUS_BROKER_USE_MUTUAL_TLS="yes" (Default value: no)
Environment variable for the protocol-mapper: USE_MUTUAL_TLS="true" (Default value: false)
You should mount your certificates as regular volumes. By default, Connectware will look for your certificates in specific locations, which you can configure using these environment variables:
AGENT_KEY=<key>
Specifies the path to your key file. Default value: /connectware/certs/client/tls.key
AGENT_CERT=<cert>
Specifies the path to your certificate file. Default value: /connectware/certs/client/tls.crt
CA=<caChain>
Specifies the path to your CA chain file. Default value: /connectware/certs/ca/ca-chain.pem
If you do not set these environment variables, Connectware will use the default paths listed above. Ensure your certificates are mounted at these locations or update the environment variables to match your specific certificate paths.
Unidirectional communication from the agent to the Connectware server simplifies firewall rules and increases security by not requiring inbound ports to be opened on the agent side.
The agent container does not require any incoming TCP/IP ports to be opened. Instead, it initiates all necessary connections outbound to the Connectware server.
For the agent to communicate with the central Connectware instance, ensure that the following outbound TCP/IP connections are allowed from the agent's network:
443/tcp (HTTPS): For secure web communication
One of the following:
1883/tcp (MQTT): If using unencrypted MQTT
8883/tcp (MQTTS): If using encrypted MQTT
The choice between MQTT and MQTTS depends on your CYBUS_MQTT_SCHEME setting in the Connectware configuration.
No special inbound firewall rules are required on the Connectware server for agent communication, as the agent initiates all connections.
For more information on setting up environment variables, see
In most other cases, we recommend to allow the agent to generate local credentials that are stored in a volume and authorized through the process.
The hostname of the local host is displayed in the . By default, the Docker container ID (e.g. d172c8c3667b) is displayed.
For more information on setting up environment variables, see