Installing Agents
How to install and configure agents using Docker, Docker Compose, or Kubernetes.
This guide explains how to install and configure a Connectware agent. An agent is a protocol-mapper instance that connects remote devices or services to your central Connectware installation. Agents are always run as containers, using Docker, Docker Compose, or Kubernetes.
The agent uses the same container image as the Connectware protocol-mapper. The image version (tag) must exactly match your Connectware version. Otherwise, the agent cannot communicate with Connectware.
Deployment Methods
You can deploy agents using the following orchestration tools:
Docker CLI: For simple, single-container deployments. See Installing Agents via Docker.
Docker Compose: For multi-container applications or more complex configurations. See Installing Agents via Docker Compose.
Kubernetes: For advanced orchestration and scaling. See Installing Agents on Kubernetes.
In all cases, configure the agent using environment variables passed to the container. This ensures consistent configuration and allows you to customize agent behavior regardless of the orchestration tool.
Environment Variables
You can configure agent containers using environment variables to customize agent behavior and connection settings. How to set these variables depends on your deployment method:
Docker Compose: Specify environment variable values in an
.envfile, placed in the same directory as yourdocker-compose.yml. By default, these files are located in/opt/connectware.Kubernetes: Use the provided Helm chart and configure environment variables in the
values.yamlfile.
For more details, see Environment Variables.
Here are the environment variables that are used for agent configuration:
Required Environment Variables
CYBUS_AGENT_MODE
Must be set to distributed to run in agent mode.
CYBUS_AGENT_NAME
Unique identifier for this agent instance.
CYBUS_HOSTNAME_INGRESS
IP address or hostname of the Connectware server.
Optional Environment Variables
CYBUS_MQTT_USERNAME
<agentName>
Authentication username for Connectware.
CYBUS_DATAPLANE_SCHEME
mqtt
MQTT connection scheme (mqtts or mqtt).
CYBUS_DATAPLANE_PORT
MQTT 1883, MQTTS 8883
Port number for MQTT connection.
Persisting Agent Credentials
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.
Mount the volume at the
/datapath within the container.
Example (Docker CLI)
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.
Alternative to Local 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.
In most other cases, we recommend allowing the agent to generate local credentials, which are stored in a volume and authorized through the client registration process.
Setting the Hostname
The hostname of the local host is displayed in the Connectware UI. By default, the Docker container ID (e.g. d172c8c3667b) is displayed.
To display a custom hostname, set the
hostnameproperty of your Docker container to match the hostname of the local host.
Depending on your operating system, the hostname may be available as a ${HOSTNAME} environment variable, or you can specify it manually.
Running Agents with Root Permissions
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.
Enabling Mutual TLS (mTLS)
To use mutual TLS (mTLS), enable it for the protocol-mapper:
Set the environment variable
CYBUS_USE_MUTUAL_TLStotrue(default:false).
For more information, see Environment Variables.
Mounting Certificates for Agents
Mount your certificates as volumes. By default, the agent looks for certificates in the following locations (configurable via environment variables):
AGENT_KEY
Path to your key file. Default: /connectware/certs/client/tls.key
AGENT_CERT
Path to your certificate file. Default: /connectware/certs/client/tls.crt
CA
Path to your CA chain file. Default: /connectware/certs/ca/ca-chain.pem
If you do not set these environment variables, the agent uses the default paths above. Ensure your certificates are mounted at these locations, or update the environment variables to match your certificate paths.
Network Requirements
Communication from the agent to the Connectware server is unidirectional, simplifying firewall rules and increasing security (no inbound ports required on the agent side).
Agent Container
The agent container does not require any incoming TCP/IP ports. It initiates all necessary outbound connections to the Connectware server.
Outbound Connections from Agent to Connectware
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. They are require
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
One of the following:
4222/tcp: If using mTLS authentication
4223/tcp: If using username & password authentication
The choice between MQTT and MQTTS depends on your CYBUS_DATAPLANE_SCHEME setting in the Connectware configuration.
Connectware Server
No special inbound firewall rules are required on the Connectware server for agent communication, as the agent initiates all connections.
Last updated
Was this helpful?