Agent Integration
In the following section we describe in detail how to setup and link an Tributech Agent with an existing Tributech Node. We will show how to gain access to the Tributech Docker Registry and startup an Tributech Agent with a Tributech Simulated Source.
Deployments
First we need to setup an environment for the execution of the Tributech Software components. We will use Docker Compose to run a Tributech Agent and Tributech Simulated Source in the Docker Containers. If you want to use any other container runtime (e.g. containerd) please create a support ticket or talk to your contact person at Tributech.
Requirements
The environment must meet the following hardware and software requirements:
Hardware Requirements
The following table shows the recommended minimum hardware requirements for the overall system.
Type | Minimum Requirement | Additional Information |
---|---|---|
CPU | 1 Core (x86-64 / ARM 32/64) or more | The minimum requirements for small and medium workloads. |
RAM | 1 GB | The minimum requirements for small and medium workloads. |
Storage | 221 MB | A typical setup requires around 500MB consisting of the Tributech Agent = 221 MB, the Tributech Source = 227 MB and the Mosquitto broker = 11,6 MB. |
The following table shows an example of a performance test with a typical IoT gateway or low-end servers. The results include the consumed CPU and RAM resources of the Tributech Agent, in addition you also need to consider the resource consumption of your selected source and your own services.
Value per second | CPU load(1 core 2.2GHz) | RAM |
---|---|---|
1 | 0,54% | 103,1MB |
10 | 2,45% | 112,2MB |
100 | 13,55% | 129MB |
If you have any questions regarding infrastructure requirements, please talk to your contact person at Tributech or create a support ticket.
Software Requirements
Type | Requirement | Additional Information |
---|---|---|
OS | Any current Linux Distribution | We recommend to select a managed solution from an IoT device or infrastructure provider which also takes care of operating system updates for example a vendor like Welotec. |
Runtime | Any current Docker environment | We recommend a managed solution for docker container orchestration e.g.: Azure IoT Edge Runtime |
File System | any suppoerted docker file system | The user/instance which runs the docker containers must have read and write permission for the volume where the docker containers are situated. |
Network requirements
Type | Requirement | Additional Information |
---|---|---|
Communication protocol | MQTTS | Communication protocol used between Tributech Agent and Node. MQTTS is the secure version of the MQTT protocol using TLS. |
Port | 1883 | Communication port used between Tributech Agent and Node. |
Endpoint URL | <name>.tributech-node.com | MQTT endpoint on server (platform) side. |
Firewall rules | allow outbound traffic for endpoint URL for port 1883 | Tributech Agent needs to be allowed to communicate with the platform, typically required for restricted enterprise networks. |
Docker-Compose Setup
The Tributech Agent Services can be run using Docker Engine as a container runtime. We use Docker Compose for management/orchestration of the Docker services.
sudo apt-get update
sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg \
lsb-release
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo \
"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
sudo apt-get install docker-compose
If you want to enable non-root users
to execute docker commands visit Post-install.
Configurations
After completing the installation process for our environment we now need to retrieve the Tributech Docker Images and configure the Docker-Compose environment as follows:
Authentication
In order to gain access to the Tributech Agent docker image we need to provide docker with the credentials to access the private Tributech Docker Registry. The authentication information can be found in the Secrets
section of the Tributech Node.
The following command provides docker with the required permissions to access the private Tributech Docker Registry. For more information on docker authentication visit docker login.
echo <Client Secret> | docker login --username <Client ID> --password-stdin <Endpoint>
Docker-Compose environment
We have a docker-compose.yml
prepared for an quick and easy setup with a Tributech Simulated Source:
version: "3.6"
services:
source-simulated:
image: ${DOCKER_REGISTRY-tributech.azurecr.io/}tributech-source-simulated:${SOURCE_TAG:-latest}
depends_on:
- mosquitto-server-simulated
- tributech-agent-simulated
environment:
- MqttOptions__MQTTHost=mosquitto-server-simulated
- Logging__LogLevel__Default=Debug
networks:
- simulated-net
restart: unless-stopped
logging:
driver: "json-file"
options:
max-size: "2m"
max-file: "5"
tributech-agent-simulated:
image: ${DOCKER_REGISTRY-tributech.azurecr.io/}tributech-agent:${AGENT_TAG:-latest}
depends_on:
- mosquitto-server-simulated
environment:
- Logging__LogLevel__Default=Debug
- Logging__Console__FormatterName=simple
- MqttOptions__MQTTHost=mosquitto-server-simulated
- EdgeDeviceOptions__AgentID=${AGENT_ID:?"The variable AGENT_ID needs to be configured in the .env file."}
ports:
- "5000:80"
networks:
- simulated-net
volumes:
- ./volumes/simulated/agent/:/app/data # volume mapping for permanent storage of keys and datatwin file
restart: unless-stopped
logging:
driver: "json-file"
options:
max-size: "2m"
max-file: "5"
mosquitto-server-simulated:
image: eclipse-mosquitto:${MQTT_TAG:-1.6}
networks:
- simulated-net
# ports:
# - '1883:1883' # MQTT
# - "127.0.0.1:9001:9001" # web-socket
restart: unless-stopped
networks:
simulated-net:
The docker-compose.yml can be used without any changes. However, we also need to create a .env
file which contains the configuration details, for our docker-compose environment. The content of the file contains all relevant information about the docker image tags and the AGENT_ID. The AGENT_ID
is a GUID that can be freely chosen, for easy recognition we use 00000000-0000-0000-0000-000000000007
. We will use the AGENT_ID
later on in the linking process to validate that we link the correct Tributech Agent with our Tributech Node. In our example the .env
file looks as follows:
AGENT_TAG=3.6.0
AGENT_ID=00000000-0000-0000-0000-000000000007
SOURCE_TAG=3.6.0
We can now Startup the environment by running the following command:
docker-compose up -d
Validate that all containers are running. The output should return that every container is in the state Up
docker-compose ps
If you encounter problems with starting the containers please consult the official docker documentation docker login and docker compose CLI.
Link Agent
After successfully starting the docker compose setup, in the previous step, we can now link the agent with the Tributech Node. Without completing the linking process the Tributech Node will not be able to receive any data from the Tributech Agent. In the agent overview we can click LINK NEW AGENT
to initialize this process.
Our prepared docker-compose.yml from the previous step exposes the port 5000
of the Agent to interact with the Tributech Node. The port of you environment must be reachable from the Tributech Node. If you are running the Tributech Node on a virtual machine you can use the following command to forward the port to your local machine:
ssh <vm-user>@<vm-ip> -L <local-port>:localhost:5000
# e.g.
ssh root@100.101.102.103 -L 5000:localhost:5000
After the port forwarding is established we can start the linking process by clicking Connect
:
After pressing connect, we can see the AGENT_ID 00000000-0000-0000-0000-000000000007
we previously defined in our .env
file for the docker environment. If the AGENT_ID is correct we can click Link/Relink Agent
to continue the linking process:
Now we can finish the linking process by clicking Link/Relink Agent
:
After the successfully completed linking process, we can configure our desired Tributech Agent Source for the Agent.
Verify
In order to detect data tampering we provide the possibility to audit each stream individually and quickly find failed validations. We can either use graph a to visually find problems or a table to filter proofs with predefined filters. We will describe both options in the following sections.
Validation Graph
The Validation Graph can be displayed by clicking Display Audit Result and contains three different colors:
- gray - validation is pending
- green - validation was successful
- red - validation was not successful
Validation Table
In Order to view every created proof with its validation history in table format we can use the AUDIT RESULTS
button from the stream overview:
The audit results table view provides the possibility to filter the audit results based on the validation result. We can use the filter to quickly find failed validations and inspect the validation history for a given proof. We want to highlight some features to quickly get started with the audit:
Overview - Display all created proofs in timespan sorted by Proof Timestamp
Filter - Limit the displayed audit results based on the validation result
Retrigger - Validation can be triggered manually and the table view will always display the latest validation result for any proof.
History - By selecting a proof row we can inspect the validation history for each proof.