Installation
To run an agent, one single Docker container has to be started. The container image to be used is identical to the Connectware’s protocol-mapper image. The image tag (i.e. the version) of that container must be the exact same version as the Connectware, otherwise the agent cannot start to communicate with the Connectware. In the examples below the image tag (version) is stored as IMAGE_TAG= 1.6.2
Orchestration
Starting the container is accomplished by the chosen orchestration tool. The container can be started either by executing a docker run
command, or by using docker-compose
with a corresponding docker-compose.yml
file, or by creating a deployment in a Kubernetes cluster, see examples below.
In either case the agent must be configured through environment variables made available to the container.
The following environment variables are required:
CYBUS_AGENT_MODE=distributed
(switches protocol-mapper to run in agent mode)CYBUS_AGENT_NAME=<agentName>
(unique name identifying this agent instance)CYBUS_MQTT_HOST=<connectwareHost>
(the IP/hostname of Connectware)
The following environment variables are optional:
CYBUS_MQTT_USERNAME=<userName>
Username for authentication in Connectware (default is<agentName>
)CYBUS_MQTT_SCHEME=<scheme>
(mqtts
ormqtt
, default:mqtt
)CYBUS_MQTT_PORT=<port>
(default:1883
)
Additionally, it is recommended to persist the data (credentials) of the agent, guaranteeing unsupervised and automatic availability, even after power cycles. To achieve this persistency, a docker volume mount must be added for the container. The volume must be mounted to /data in the container. The agent will automatically store the credentials on that volume and re-use them on subsequent start-up.
If multiple agents will be run on the same computer, each agent must use its own volume mount, as otherwise agents would overwrite each other’s data, including username and password credentials.
As an alternative to locally generated credentials, it is also possible to specify a password for this protocol-mapper agent directly by an additional environment variable CYBUS_PROTOCOL_MAPPER_PASSWORD
. This might be useful in scenarios where the agent deployment is controlled by the same orchestration tool as the central Connectware instance. In most other cases it is recommended to let the agent generate local credentials, stored in a volume, and authorized to Connectware through the client registration workflow.
It may also be useful to set the hostname
property of the docker container to the local host’s hostname, because this name will be displayed in the Admin-UI overview page. If it is not set, the local docker container ID will be displayed instead (e.g. d172c8c3667b
), which might look rather confusing in this overview page. Depending on the operating system, the suitable value for the hostname may be available as an environment variable ${HOSTNAME}
or it must be specified manually, as noted in the example below.
Agents use an unprivileged user by default. Some protocols or features need root permissions (for example USB access or promiscuous network mode). If you want to use a feature that requires root access, you simply need to execute the agent as user root.
In case of mutual TLS, first you need to enable it for the Broker:
CYBUS_BROKER_USE_MUTUAL_TLS="yes"
(default:no
)
Some additional configuration is necessary on the agent:
CYBUS_MQTT_SCHEME
should be set tomqtts
CYBUS_MQTT_PORT
should target the appropriate port of the Broker, which listens for mqtts messages on8883
by defaultUSE_MUTUAL_TLS=true
(default:false
)You should mount your certificates as regular volumes. By default Connectware will look for the certifcates specified in these environment variables:
AGENT_KEY=<key>
(default:/connectware/certs/client/tls.key
)AGENT_CERT=<cert>
(default:/connectware/certs/client/tls.crt
)CA=<caChain>
(default:/connectware/certs/ca/ca-chain.pem
)
Example 1: docker-compose
version: '2.0'
services:
protocol-mapper-agent:
image: registry.cybus.io/cybus/protocol-mapper:${IMAGE_TAG}
environment:
CYBUS_AGENT_MODE: distributed
CYBUS_AGENT_NAME: myAgent
CYBUS_MQTT_HOST: 10.11.12.13
volumes:
- protocol-mapper-agent:/data
restart: unless-stopped
network_mode: host
hostname: <some-suitable-hostname>
volumes:
protocol-mapper-agent:
To start, create a new directory (e.g. myAgent
). Inside, create a new file called docker-compose.yml
with the above content and finally run:
docker-compose up -d
Again it is noted that if multiple agents should run on the same computer, each agent must have defined its own docker volume, otherwise different agents would overwrite each other’s persisted data, including username and password credentials.
To execute the agent with root permission add user: root
to the docker compose service:
version: '2.0'
services:
protocol-mapper-agent:
user: root
image: registry.cybus.io/cybus/protocol-mapper:${IMAGE_TAG}
[...]
Example 2: docker run
Using the environment variable IMAGE_TAG= 1.6.2, the following command will run the agent directly (but with the comment lines removed):
# The docker run command
docker run \
# Make it run as an agent
-e CYBUS_AGENT_MODE=distributed \
# Set the name of the agent. This must match the agentName used in the commissioning file.
-e CYBUS_AGENT_NAME=myAgent \
# The IP address where Connectware is running.
-e CYBUS_MQTT_HOST=10.11.12.13 \
# Attach a volume so the agent can store data across restarts
-v /tmp/cybus:/data \
# Upon failures, restart the container
--restart unless-stopped \
# Run it in host mode networking
--net=host \
# Some suitable hostname of the container.
--hostname=${HOSTNAME} \
# The image to use
registry.cybus.io/cybus/protocol-mapper:${IMAGE_TAG}
This will start an agent named myAgent
that persists data to /tmp/cybus
on the host OS.
To execute the agent with root permission add --user=root
to the parameters of the docker run command.
Example 3: Kubernetes
To run Connectware agents on Kubernetes we recommend to use our connectware-agent
Helm chart. Learn how to use it in this Cybus Learn article.
If you prefer manual orchestration over using the Helm chart, you can use the following yaml manifest file, to run an agent on a Kubernetes cluster. You only need to configure the same parameters used by the others types of deployments.
This example only stores the agent data using an emptyDir
. Replace this with a persistent volume for production use.
Additionally you will need to create a Kubernetes secret to store the Cybus registry credentials needed to fetch the Connectware container images. To create a secret like this, use the secret name cybus-docker-registry
with the following command:
kubectl create secret docker-registry cybus-docker-registry \
--docker-server=registry.cybus.io \
--docker-username=john.doe \
--docker-password=abcd123 \
[email protected]
The username and password should be your Cybus Portal username and password. Alternatively, when using the Connectware license key, the username is license
and the password is your Connectware license key.
The manifest file can be created from this example:
apiVersion: apps/v1
kind: Deployment
metadata:
# The id for this kubernetes object
name: connectware-agent-deployment
labels:
# Attach labels for easy group selection
app: protocol-mapper-agent
spec:
replicas: 1
selector:
matchLabels:
app: protocol-mapper-agent
template:
metadata:
labels:
app: protocol-mapper-agent
spec:
# Configure volumes used by the agent to store data across restarts
volumes:
- name: agent-data-volume
emptyDir: {}
containers:
- name: protocol-mapper-agent
# Container image. Watch out: Must use identical version tag to current Connectware version!
image: registry.cybus.io/cybus/protocol-mapper:1.0.32
env:
# Make the protocol-mapper runs as an agent
- name: CYBUS_AGENT_MODE
value: 'distributed'
# Set the name of the agent. This must match the agentName used in the commissioning file.
- name: CYBUS_AGENT_NAME
value: 'myAgent'
# The IP address or hostname where the Connectware is running
- name: CYBUS_MQTT_HOST
value: '10.11.12.13'
ports:
# Expose the ports used by the agent.
- containerPort: 443
# Configure mount points
volumeMounts:
- mountPath: /data
name: agent-data-volume
# Configure resource limits
resources:
limits:
cpu: 4000m
memory: 4Gi
# Kubernetes secret used to pull the images from the Cybus registry
imagePullSecrets:
- name: cybus-docker-registry
Manifest file for download:
Example 4: Mutual TLS Agent
version: '2.0'
services:
protocol-mapper-agent:
image: registry.cybus.io/cybus/protocol-mapper:${IMAGE_TAG}
environment:
CYBUS_AGENT_MODE: distributed
CYBUS_AGENT_NAME: myAgent
CYBUS_MQTT_SCHEME: mqtts
CYBUS_MQTT_HOST: 10.11.12.13
CYBUS_MQTT_PORT: '8883'
USE_MUTUAL_TLS: true
volumes:
- protocol-mapper-agent:/data
- /mycerts:/connectware/certs/client
- /myca:/connectware/certs/ca
restart: unless-stopped
network_mode: host
hostname: <some-suitable-hostname>
volumes:
protocol-mapper-agent:
Network Requirements
For the configured agent container, no incoming TCP/IP port permissions are needed. All communication will be handled by outgoing connections.
In order for the agent container to reach the central Connectware, the following incoming TCP/IP ports are needed for the central Connectware. In other words, the agent must be able to initiate connections to the central Connectware via the following ports:
443/tcp (https), and
1883/tcp (mqtt) or 8883/tcp (mqtts), whichever is chosen in CYBUS_MQTT_SCHEME
Last updated
Was this helpful?