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

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	Default Value	Description
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_CONTROLPLANE_URI=wss://<connectwareHost>:4223		Defines the connection URI that agents must use to access the Connectware control plane

Optional Environment Variables

Environment Variable	Default Value	Description
CYBUS_MQTT_USERNAME=<userName>	<agentName>	Authentication username for Connectware.
CYBUS_MQTT_SCHEME=<scheme>	mqtt	MQTT connection scheme (mqtts or mqtt).
CYBUS_MQTT_PORT=<port>	MQTT 1883, MQTTS 8883	Port number for MQTT connection.

Persisting Agent Data

To ensure your agent's credentials persist across container restarts and system reboots, we recommend implementing credential persistence.

1. Create a Docker volume and mount it to the agent container.

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

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

• 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_MQTT_SCHEME setting in the Connectware configuration.

If using mTLS authentication you will need to use MQTTS as well as port 4222 for the control plane connection by specifying CYBUS_CONTROLPLANE_URI=nats://<connectwareHost>:4222.

Connectware Server

No special inbound firewall rules are required on the Connectware server for agent communication, as the agent initiates all connections.