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 or mqtt, 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 to mqtts

• CYBUS_MQTT_PORT should target the appropriate port of the Broker, which listens for mqtts messages on 8883 by default

• USE_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 \
--docker-email=[e-mail]

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:

2KB

agent-deployment.yaml

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