Assurance Sensor Agent Installation Guidelines

Installation and Deployment Guidelines

This guide covers the requirements, configuration, and deployment of Cisco® Provider Connectivity Assurance Sensor Agents. The agents are containerized measurement functions delivered as Docker container images.

Agent types: actuate, throughput, trace, transfer

Prerequisites and Host Requirements

Container Runtime

The Cisco® Provider Connectivity Assurance Sensor Agents require a container runtime on a Linux host.

Standard daemon configuration (/etc/docker/daemon.json) is sufficient. No special kernel modules or sysctl tuning is required — standard Linux distributions include all necessary kernel networking subsystems (netfilter, bridge interfaces, IP routing) by default. Both bridge networking (Docker default) and host networking are supported. IPv6 is detected automatically.

Linux Capabilities

Grant the following Linux capabilities to Sensor Agents containers:

In Docker Compose, set capabilities with cap_add. In Docker CLI, use --cap-add. For Kubernetes, use securityContext.capabilities.add.

Network Services

The following host services are not strictly required but are recommended for reliable operation:

DNS resolver — Required if Sensor Collector endpoints are configured using FQDNs. If only IP addresses are used, DNS is not needed. Ensure /etc/resolv.conf on the host points to a functional DNS server. Docker passes this configuration into containers automatically.

NTP client — Sensor Agents read the host system clock for timestamping performance measurements. Clock accuracy directly affects the validity of one-way delay, jitter, and latency measurements. Use any standard NTP client (chrony recommended).

HTTP/HTTPS proxy — In environments without direct internet access, pass proxy settings to the container via environment variables: http_proxy, https_proxy, no_proxy. Both lowercase and uppercase variants are supported. See HTTP/HTTPS Proxy for details.

Firewall Rules

If a firewall is active on the host or in the network path, ensure the following traffic is permitted:

Agent Resource Consumption

For containers, the amount of RAM, CPU, and disk is rarely provisioned strictly by the container environment. Instead, the usage is typically monitored and the environment can be configured to alert on overutilization.

As a guideline, the Sensor Agents under typical usage will consume up to:

A vCPU is considered as a thread on standard x86 CPU, running typically at 2.2 to 2.4 GHz.
CPU usage for actuate is shown as a range depending on load. Highest load is 5000 pps (for example 500 sessions of 10 pps each).

Agent logging is through the standard container stdout mechanism. It is up to the container environment to apply restrictions on log volume and retention. Keeping large amounts of logs will increase disk space usage. See Logging Configuration for recommended settings.

Agent Connectivity Requirements

The agent establishes two connections to the Sensor Collector:

• Management proxy (TCP port 55777, default) — used for agent management and configuration. Authenticated using a secret provided to the agent upon start.
• Data gateway (TCP port 55888, default) — used to send measurement data and metrics.

Both connections are directed to the same Sensor Collector instance.

If you don't have a Sensor Collector instance up and running for agents, you must set it up. For information, see Sensor Collector.

Lastly, the agent needs connectivity to the test destination. This may be a reflector, responder, service, or another agent — all depending on the test type and configuration. Each agent type has different connectivity requirements for their test traffic. The port table in Firewall Rules summarizes all connections that must be permitted.

Downloading Agent Images

The Sensor Agents are provided as Docker container images. To load an agent into your Docker environment, use the docker pull command for the appropriate agent.

Container registry (docker pull)

x86/AMD versions (amd64):

docker pull gcr.io/sky-agents/agent-actuate-amd64:r25.07.1
docker pull gcr.io/sky-agents/agent-throughput-amd64:r25.07.1
docker pull gcr.io/sky-agents/agent-trace-amd64:r25.07.1
docker pull gcr.io/sky-agents/agent-transfer-amd64:r25.07.1

ARM 64-bit versions (arm64):

docker pull gcr.io/sky-agents/agent-actuate-arm64:r25.07.1
docker pull gcr.io/sky-agents/agent-throughput-arm64:r25.07.1
docker pull gcr.io/sky-agents/agent-trace-arm64:r25.07.1
docker pull gcr.io/sky-agents/agent-transfer-arm64:r25.07.1

Offline installation (docker save / load)

If an Sensor Agent needs to be installed on a host that has no internet access, all agents can be downloaded from software.cisco.com under the Provider Connectivity Assurance category.

Alternatively, an image fetched with docker pull can be exported using docker save to a tar.gz file:

docker save gcr.io/sky-agents/agent-actuate-amd64:r25.07.1 | gzip > agent-actuate-amd64.r25.07.1.tar.gz

This file can then be loaded on the target host using docker load:

docker load -i agent-actuate-amd64.r25.07.1.tar.gz

Once loaded, verify the image is present:

docker images

The output should show the loaded image:

REPOSITORY                                        TAG        IMAGE ID       CREATED        SIZE
gcr.io/sky-agents/agent-actuate-amd64   r25.07.1     4fab523db717   1 week ago     24MB

Agent Configuration

For an agent to be started and ready to perform tests, it needs several configuration elements:

• An authentication secret (secrets file or environment variable)
• The IP address or FQDN of a Sensor Collector management service
• The NET_ADMIN capability enabled
• Port mappings for the TWAMP reflector (actuate agent only, if reflection is required)
• Port mappings for incoming throughput test requests (throughput agent only)
• ca.pem file if using a self-signed CA on the Sensor Collector host (see Custom CA Certificates)

These parameters can be supplied in a Docker Compose file or specified as environment variables on the command line when starting the container with docker run.

Define agent in orchestration API

Each agent needs a definition in the orchestration system to be accepted and controllable. To add a new agent, four configuration attributes need to be set:

• agentId — a unique UUID identifying this agent
• agentName — a descriptive name string
• data gateway server — IP address or FQDN of the Sensor Collector (same host as the management proxy)
• data gateway port — port used for metrics data streaming (default 55888)

To generate a UUID for your agent, use the built-in generator in Linux:

uuidgen

Example output: ae311d23-5ca7-fake-8317-25example54a

Create a configuration object like the one below:

{
  "data": {
    "type": "agentConfigs",
    "attributes": {
      "agentId": "ae311d23-5ca7-fake-8317-25example54a",
      "dataGateway": {
        "server": "192.168.0.4",
        "port": 55888
      },
      "identification": {
        "agentName": "demo-agent-12345"
      }
    }
  }
}

Then, POST it to the orchestration service to register this new agent:

POST {{your-tenant-name}}/api/orchestrate/v3/agents/configuration

Secrets and authentication

Each agent needs an authentication token to register with the orchestration system. There are multiple ways to provide this secret to the agent.

##### Retrieve the secret

Use the agent control UI or the orchestration API to generate the initial authentication secret. The API call requires only the agent UUID:

POST {{your-tenant-name}}/api/orchestrate/v3/agents/ae311d23-5ca7-fake-8317-25example54a/secrets

The output contains the initial secret for this agent in YAML format:

agentConfig:
    identification:
        agentId: ae311d23-5ca7-fake-8317-25example54a
        authenticationToken: eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY2NlZGlhbi5jb20i...

##### Method 1: Secrets file (file on host)

Save the secret output to a YAML file on the host. It is good practice to use the agent UUID as part of the file name when deploying multiple agents on the same host:

/home/agentuser/secrets/ae311d23-5ca7-fake-8317-25example54a.yaml

Mount this file into the container at /run/secrets/secrets.yaml (the default path):

--mount type=bind,source=/home/agentuser/secrets/ae311d23-5ca7-fake-8317-25example54a.yaml,target=/run/secrets/secrets.yaml

In Docker Compose:

volumes:
  - type: bind
    source: /home/agentuser/secrets/ae311d23-5ca7-fake-8317-25example54a.yaml
    target: /run/secrets/secrets.yaml

##### Method 2: Named volumes (Docker)

Named volumes let Docker manage the storage. This is useful when the host filesystem layout should not be exposed to containers.

Create the volume and populate it:

docker volume create agent-secrets
docker container create --name temp-init -v agent-secrets:/run/secrets busybox
docker cp /home/agentuser/secrets/ae311d23-5ca7-fake-8317-25example54a.yaml temp-init:/run/secrets/secrets.yaml
docker rm temp-init

Then reference the volume in your Docker Compose file:

volumes:
  - agent-secrets:/run/secrets

Or on the command line:

--mount source=agent-secrets,target=/run/secrets

##### Method 3: Environment variables

In some cases it may be more suitable to provide the initial token as environment variables when launching the agent. Set both AGENT_ID and AGENT_AUTHENTICATION_TOKEN:

Docker CLI:

docker run -d \
  --env AGENT_ID=ae311d23-5ca7-fake-8317-25example54a \
  --env AGENT_AUTHENTICATION_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY2NlZGlhbi5jb20i... \
  --mount source=agent-secrets,target=/run/secrets \
  --env AGENT_MANAGEMENT_PROXY="10.11.12.13" \
  --cap-add=NET_ADMIN \
  gcr.io/sky-agents/agent-actuate-amd64:r25.07.1

Docker Compose:

services:
  actuate-agent:
    image: gcr.io/sky-agents/agent-actuate-amd64:r25.07.1
    cap_add:
      - NET_ADMIN
    environment:
      AGENT_ID: "ae311d23-5ca7-fake-8317-25example54a"
      AGENT_AUTHENTICATION_TOKEN: "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY2NlZGlhbi5jb20i..."
      AGENT_MANAGEMENT_PROXY: "10.11.12.13"
    volumes:
      - agent-secrets:/run/secrets

volumes:
  agent-secrets:

##### Token lifecycle and renewal

The default path where the agent looks for its secrets file inside the container is /run/secrets/secrets.yaml. To use a different path, set the AGENT_SECRETS_PATH environment variable.

See Agent secrets file options for additional methods of providing authentication secrets to the agent.

CA trust bundle selection

At startup the agent selects a CA trust bundle based on the AGENT_CA_TRUST_BUNDLE environment variable:

If no option is provided, the default mode is intersect.

Custom CA certificates (TLS)

When the Sensor Collector uses a TLS certificate signed by a private Certificate Authority (CA), the CA certificate must be added to the agent's trusted certificate store. This allows the agent to validate the Sensor Collector's TLS certificate.

There are two common approaches to TLS certificates:

• Self-signed TLS certificate — The certificate signs itself. Simpler to generate (single command). Best for testing and development.
• CA-signed TLS certificate — A separate CA certificate signs the TLS certificate. A single CA certificate can sign multiple TLS certificates for different servers. Best for production environments.

For instructions on generating certificates, see Generate a Self-Signed Certificate.

head -1 myCA.crt

openssl x509 -in myCA.crt -inform DER -out myCA.pem -outform PEM

##### Loading CA certificates into agents

Create a directory on the host with the CA certificate(s) in PEM format:

mkdir myCaCertsToImport
cp myCA.pem myCaCertsToImport/

Mount this directory into the container at /usr/local/share/ca-certificates/:

Docker CLI:

docker run -d \
  --env AGENT_MANAGEMENT_PROXY=192.168.1.1 \
  --log-driver json-file --log-opt max-size=10m --log-opt max-file=3 \
  --mount type=bind,source=./secrets.yaml,target=/run/secrets/secrets.yaml \
  --mount type=bind,source=./myCaCertsToImport,target=/usr/local/share/ca-certificates/myCaCertsToImport \
  --cap-add=NET_ADMIN \
  gcr.io/sky-agents/agent-actuate-amd64:r25.07.1

Docker Compose:

services:
  sensor-agent:
    image: gcr.io/sky-agents/agent-actuate-amd64:r25.07.1
    cap_add:
      - NET_ADMIN
    environment:
      AGENT_MANAGEMENT_PROXY: "192.168.1.1"
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    volumes:
      - type: bind
        source: ./secrets.yaml
        target: /run/secrets/secrets.yaml
      - type: bind
        source: ./myCaCertsToImport
        target: /usr/local/share/ca-certificates/myCaCertsToImport

The agent automatically detects and imports PEM certificates placed in subdirectories of /usr/local/share/ca-certificates/ at startup.

Deploying Agents with Docker

Docker Compose

To use Docker Compose, place the configuration parameters in a YAML file.

Example — actuate agent:

services:
  actuate-agent:
    container_name: "my-actuate-agent"
    image: "gcr.io/sky-agents/agent-actuate-amd64:r25.07.1"
    cap_add:
      - NET_ADMIN
      - NET_RAW
    ports:
      - "4000:862/udp"
    restart: always
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      AGENT_MANAGEMENT_PROXY: "10.11.12.13"
      AGENT_MANAGEMENT_PROXY_PORT: "55777"
    volumes:
      - type: bind
        source: /home/agentuser/secrets/ae311d23-5ca7-fake-8317-25example54a.yaml
        target: /run/secrets/secrets.yaml
# Optional: mount CA certificate if using a self-signed CA on the Sensor Collector
    # - type: bind
    #   source: ./secrets/ca.pem
    #   target: /usr/local/share/ca-certificates/ca.pem

Example — throughput agent:

services:
  throughput-agent:
    container_name: "my-throughput-agent"
    image: "gcr.io/sky-agents/agent-throughput-amd64:r25.07.1"
    cap_add:
      - NET_ADMIN
      - NET_RAW
    restart: always
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      AGENT_MANAGEMENT_PROXY: "10.11.12.13"
      AGENT_MANAGEMENT_PROXY_PORT: "55777"
    volumes:
      - type: bind
        source: /home/agentuser/secrets/ae311d23-5ca7-fake-8317-25example54a.yaml
        target: /run/secrets/secrets.yaml
# Optional: mount CA certificate if using a self-signed CA on the Sensor Collector
    # - type: bind
    #   source: ./secrets/ca.pem
    #   target: /usr/local/share/ca-certificates/ca.pem

Launch the agent:

docker compose up -d

If the compose file is not named docker-compose.yml, specify it:

docker compose -f mycomposefile.yml up -d

Docker CLI

The same configuration can be provided on the command line using docker run.

Example — actuate agent with secrets file:

docker run -d \
  --name my-actuate-agent \
  -p 4000:862/udp \
  --env AGENT_MANAGEMENT_PROXY="10.11.12.13" \
  --env AGENT_MANAGEMENT_PROXY_PORT="55777" \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  --restart=always \
  --log-driver json-file --log-opt max-size=10m --log-opt max-file=3 \
  --mount type=bind,source=/home/agentuser/secrets/ae311d23-5ca7-fake-8317-25example54a.yaml,target=/run/secrets/secrets.yaml \
  gcr.io/sky-agents/agent-actuate-amd64:r25.07.1

Example — actuate agent without secrets file (environment variables):

docker run -d \
  --name my-actuate-agent \
  -p 4000:862/udp \
  --env AGENT_ID="ae311d23-5ca7-fake-8317-25example54a" \
  --env AGENT_AUTHENTICATION_TOKEN="eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY2NlZGlhbi5jb20i..." \
  --env AGENT_MANAGEMENT_PROXY="10.11.12.13" \
  --env AGENT_MANAGEMENT_PROXY_PORT="55777" \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  --restart=always \
  --log-driver json-file --log-opt max-size=10m --log-opt max-file=3 \
  gcr.io/sky-agents/agent-actuate-amd64:r25.07.1

The -d option launches the container in the background (detached mode).

Verifying agent status

To check that the agent has started, use docker ps:

docker ps

Expected output:

CONTAINER ID   IMAGE                                             COMMAND          CREATED       STATUS                 PORTS                   NAMES
437d53381d83   gcr.io/sky-agents/agent-actuate-amd64:r25.07.1   "/sbin/monitor"  5 weeks ago   Up 5 weeks (healthy)   0.0.0.0:4000->862/udp   my-actuate-agent

The output shows how long the agent has been running, the health status, and the port mappings. A status of (healthy) confirms the agent is operating correctly.

Logging Configuration

Docker log rotation

Configure the json-file log driver with size limits. This can be done per-container or globally.

Per-container (Docker Compose):

services:
  sensor-agent:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Per-container (Docker CLI):

--log-driver json-file --log-opt max-size=10m --log-opt max-file=3

Global default (in /etc/docker/daemon.json):

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

For more details, see the Docker documentation: Configure logging drivers

Centralized logging

Sensor Agents emit structured RFC 5424 syslog to stdout, which the Docker logging driver captures. For centralized log management, configure Docker to forward logs using the syslog, fluentd, or other supported log drivers. Logs are always available locally via docker logs <container-name>.

Advanced Configuration

Multiple interfaces / VRF / namespaces

All agents support attaching to multiple interfaces by configuration in the Docker Compose file or via Docker command line options. The agent can either be provided with a specific mount point for a VRF / namespace or be given access to the full set of namespaces available in the /var/run/netns directory.

To switch namespaces, the agent must be started with the SYS_ADMIN capability enabled.

Interfaces vs namespaces:
Linux systems natively support multiple physical and virtual (VLAN) interfaces. On a standard Linux system, these interfaces cannot have overlapping IP addressing subnets and routes — each interface has its own IP subnet and there is only one default route.

With namespaces / VRF, the Linux kernel provides separate routing domains. Each namespace can have its own interfaces, IP addresses, and default routes, even if they overlap with other namespaces.

When an interface is reassigned to a different namespace, it disappears from the default interface list (ip addr).

Example commands to add a namespace and associate an interface:

ip netns add mynamespace
ip link set eth3.123 netns mynamespace

Docker Compose example with namespace access:

services:
  actuate-agent:
    container_name: "my-actuate-agent"
    image: "gcr.io/sky-agents/agent-actuate-amd64:r25.07.1"
    cap_add:
      - NET_ADMIN
      - NET_RAW
      - SYS_ADMIN
    restart: always
    network_mode: host
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      AGENT_MANAGEMENT_PROXY: "12.13.14.15"
    volumes:
      - type: bind
        source: /home/agentuser/secrets/ae311d23-5ca7-fake-8317-25example54a.yaml
        target: /run/secrets/secrets.yaml
      - type: bind
        propagation: rslave
        source: /var/run/netns
        target: /var/run/netns

Environment Variable Reference

The following environment variables can be provided to Sensor Agents at container startup. All variables are set through -e / --env flags (Docker CLI) or the environment: section (Docker Compose).

General variables

The agent is now ready to be configured using the orchestration API. See Working with the agents control API for more information, or the agent orchestration API reference for full details.

Troubleshooting