Installing Agents
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.
Orchestration
You can deploy agents using various orchestration tools:
Docker CLI: Run a
docker run
command.Docker Compose: Use
docker compose
with adocker-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 Installing Agents via Docker
Docker Compose
Create a
docker-compose.yml
file for multi-container applications or more complex configurations. See Installing Agents via Docker Compose
Kubernetes
Deploy agents to a Kubernetes cluster for advanced orchestration and scaling capabilities. See Installing Agents on Kubernetes
Choose the method that best suits your infrastructure and operational requirements.
Environment Variables
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 thedocker-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.
For more information on setting up environment variables, see Environment Variables
Here are the environment variables that are used for agent configuration:
Required Environment Variables
Environment Variable | Description |
---|---|
| Configures the protocol-mapper to operate in agent mode. |
| Defines a unique identifier for the current agent instance. |
| Specifies the IP address or hostname of the Connectware server. |
Optional Environment Variables
Environment Variable | Description |
---|---|
| Authentication username for Connectware. Default value: |
| MQTT connection scheme ( |
| Port number for MQTT connection. Default values: MQTT |
Persisting Agent Data
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.
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 to allow the agent to generate local credentials that 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
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.
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)
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
)
For more information on setting up environment variables, see Environment Variables
Mounting Certificates for Agents
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:
Environment Variable | Description |
---|---|
| Specifies the path to your key file. Default value: |
| Specifies the path to your certificate file. Default value: |
| Specifies the path to your CA chain file. Default value: |
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.
Network Requirements
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.
Agent Container
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.
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:
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.
Connectware Server
No special inbound firewall rules are required on the Connectware server for agent communication, as the agent initiates all connections.
Last updated