# Installing Agents

This guide explains how to install and configure a Connectware agent. An agent is a protocol-mapper instance that connects remote devices or services to your central Connectware installation. Agents are always run as containers, using Docker, Docker Compose, or Kubernetes.

The agent uses the same container image as the Connectware protocol-mapper. The image version (tag) must exactly match your Connectware version. Otherwise, the agent cannot communicate with Connectware.

## Deployment Methods

You can deploy agents using the following orchestration tools:

* **Docker CLI**: For simple, single-container deployments. See [Installing Agents via Docker](https://docs.cybus.io/2-0-6/documentation/agents/installing-agents/installing-agents-via-docker).
* **Docker Compose**: For multi-container applications or more complex configurations. See [Installing Agents via Docker Compose](https://docs.cybus.io/2-0-6/documentation/agents/installing-agents/installing-agents-via-docker-compose).
* **Kubernetes**: For advanced orchestration and scaling. See [Installing Agents on Kubernetes](https://docs.cybus.io/2-0-6/documentation/agents/installing-agents/installing-agents-via-kubernetes).

In all cases, configure the agent using environment variables passed to the container. This ensures consistent configuration and allows you to customize agent behavior regardless of the orchestration tool.

### Environment Variables

You can configure agent containers using environment variables to customize agent behavior and connection settings. How to set these variables depends on your deployment method:

* **Docker Compose**: Specify environment variable values in an `.env` file, placed in the same directory as your `docker-compose.yml`. By default, these files are located in `/opt/connectware`.
* **Kubernetes**: Use the provided Helm chart and configure environment variables in the `values.yaml` file.

For more details, see [Environment Variables](https://docs.cybus.io/2-0-6/documentation/environment-variables).

Here are the environment variables that are used for agent configuration:

#### Required Environment Variables

| Environment Variable     | Description                                        |
| ------------------------ | -------------------------------------------------- |
| `CYBUS_AGENT_MODE`       | Must be set to `distributed` to run in agent mode. |
| `CYBUS_AGENT_NAME`       | Unique identifier for this agent instance.         |
| `CYBUS_HOSTNAME_INGRESS` | IP address or hostname of the Connectware server.  |

#### Optional Environment Variables

| Environment Variable     | Default Value             | Description                                 |
| ------------------------ | ------------------------- | ------------------------------------------- |
| `CYBUS_MQTT_USERNAME`    | `<agentName>`             | Authentication username for Connectware.    |
| `CYBUS_DATAPLANE_SCHEME` | `mqtt`                    | MQTT connection scheme (`mqtts` or `mqtt`). |
| `CYBUS_DATAPLANE_PORT`   | MQTT `1883`, MQTTS `8883` | Port number for MQTT connection.            |

### Persisting Agent Credentials

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. Mount the volume at the `/data` path within the container.

**Example (Docker CLI)**

```sh
docker volume create agent-data
docker run -v agent-data:/data ...
```

Once completed, the agent will automatically:

* Store its credentials on the mounted volume.
* Retrieve and reuse these credentials during subsequent startups.

{% hint style="warning" %}
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.
{% endhint %}

### 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 allowing the agent to generate local credentials, which are stored in a volume and authorized through the [client registration](https://docs.cybus.io/2-0-6/documentation/client-registry) process.

### Setting the Hostname

The hostname of the local host is displayed in the [Connectware UI](https://docs.cybus.io/2-0-6/documentation/agents/monitoring-agents). 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 hostname may be available as a `${HOSTNAME}` environment variable, or you can specify it manually.

### 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)

To use mutual TLS (mTLS), enable it for the protocol-mapper:

* Set the environment variable `CYBUS_USE_MUTUAL_TLS` to `true` (default: `false`).

For more information, see [Environment Variables](https://docs.cybus.io/2-0-6/documentation/environment-variables).

### Mounting Certificates for Agents

Mount your certificates as volumes. By default, the agent looks for certificates in the following locations (configurable via environment variables):

| Environment Variable | Description                                                                 |
| -------------------- | --------------------------------------------------------------------------- |
| `AGENT_KEY`          | Path to your key file. Default: `/connectware/certs/client/tls.key`         |
| `AGENT_CERT`         | Path to your certificate file. Default: `/connectware/certs/client/tls.crt` |
| `CA`                 | Path to your CA chain file. Default: `/connectware/certs/ca/ca-chain.pem`   |

If you do not set these environment variables, the agent uses the default paths above. Ensure your certificates are mounted at these locations, or update the environment variables to match your certificate paths.

## Network Requirements

Communication from the agent to the Connectware server is unidirectional, simplifying firewall rules and increasing security (no inbound ports required on the agent side).

### Agent Container

The agent container does not require any incoming TCP/IP ports. It initiates all necessary outbound connections 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. They are require

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