Agent Installation Guidelines
  • 07 May 2024
  • 12 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Agent Installation Guidelines

  • Dark
    Light
  • PDF

Article summary

Installation and Deployment Guidelines

Note

By default Docker logs have no log rotations. If sensor agents run for long periods of time please change the default log driver to not risk file system filling up. Please see the Docker documentation on logging:
Configure logging drivers

Requirements on Runtime Environment


The sensor: agents are containerized test functions that require a container environment in order to run.

Currently, we recommend Docker 20.10.0 or later on AMD64/x86-64 or ARM64 linux systems, and management of containers using Kubernetes, Docker CLI commands or Docker-Compose. Kubernetes control of container lifecycle is supported with helm charts for all agents.

Agent Typical 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 overutlization of a certain resource.

As a guideline, the sensor: agents will under typical usage consume up to:

AgentvCPU*RAMDisk
actuate0.05 - 10.2-0.5GB200MB
throughput10.1GB200MB
transfer0.10.1GB200MB
trace0.10.1GB200MB

A vCPU is considered as a thread on standard x86 CPU, running typically at 2.2 to 2.4GHz
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).

The logging from agents is through standard stdout mechanism, and it is up to the container environment to apply restrictions on how much data should be logged, and for how long. Keeping large amounts of logs will certainly increase the disk space used for the agents.

Agent Connectivity Requirements


In order to operate, the agent must be able to connect to a roadrunner instance using TCP on port 55777 (default port). This connection is referred to as the MANAGEMENT_PROXY and is used for management of the agent, and is authenticated using a secret provided in a YAML file to the agent upon start.

Secondly, the agent will communicate with a roadrunner on TCP port 55888 (default) to sent measurement data and metrics. This is refered to as the DATA_GATEWAY.

agentComms.png

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

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.

Summary of connections required to be opened through any firewalls in between

PathDirectionprotocolport
Agent managementAgent to roadrunnertcp55777
Agent metrics data reportingAgent to roadrunnertcp55888
RoadrunnerRoadrunner to Analyticstcp443
Agent test trafficAgent to reflector or other agenttcp/udpconfigurable

Note that all connections agent-roadrunner-analytics are "outbound", which means that it is supported to use NAT/PAT firewalls between each of these components, as all connections are initiated from the edge towards the central location. (Agent->Roadrunner and Roadrunner->Analytics cloud)

Agent Installation


The sensor: agents are provided as packages directly loadable into the Docker environment. To load an agent into your Docker environment, use the docker pull command for the appropriate agent:

x86/AMD versions

actuate x86_64 or amd64:

sudo docker pull gcr.io/sky-agents/agent-actuate-amd64:r24.05

throughput x86_64 or amd64:

sudo docker pull gcr.io/sky-agents/agent-throughput-amd64:r24.05

trace x86_64 or amd64:

sudo docker pull gcr.io/sky-agents/agent-trace-amd64:r24.05

transfer x86_64 or amd64:

sudo docker pull gcr.io/sky-agents/agent-transfer-amd64:r24.05

ARM 64-bit versions

actuate arm64:

sudo docker pull gcr.io/sky-agents/agent-actuate-arm64:r24.05

throughput arm64:

sudo docker pull gcr.io/sky-agents/agent-throughput-arm64:r24.05

trace arm64:

sudo docker pull gcr.io/sky-agents/agent-trace-arm64:r24.05

transfer arm64:

sudo docker pull gcr.io/sky-agents/agent-transfer-arm64:r24.05

Downloading and exporting agent container as a file

If the agent needs to be installed on a host that has no internet access, the pulled image can be exported using docker save to a tar.gz file:

sudo docker save gcr.io/sky-agents/agent-actuate-amd64:r24.05 | gzip > agent-actuate-amd64.r24.05.tar.gz

This Docker image tar.gz file can then be loaded on the target plaform using docker load command:

sudo docker load -i agent-actuate-amd64.r24.05.tar.gz

Once loaded, the agent image should be present in the output from docker images:

sudo docker images

The output should show that the image has been loaded:

REPOSITORY                             TAG                 IMAGE ID            CREATED             SIZE
agent-actuate-docker          yy.mm_nnnn           4fab523db717        1 week ago        24MB

Agent Startup


For an agent to be started and ready to perform tests, it needs a couple of configuration parameters to be defined:

  • An external port mapping for the built-in RFC5357 TWAMP-light reflector (actuate agent only, and is not needed if no reflection is required)
  • A secrets YAML file containing an agent UUID and initial key for authentication
    OR
    A token provided to the agent via environment variable
  • IP address or FQDN, and port where it can find a roadrunner agent management service

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

Additional configuration parameters

Optionally, additional parameters can be defined like an agent name, an interface binding or additional logging options. These additional parameters are described in the documentation for each individual sensor: agent.

Define a new agent in the orchestration API

Important

When quering and changing configuration through the orchestration API it is highly recommended to use a dedicated service account for this task and not an individual user account. Agents use JWT tokens for authentication and these will expire if the user account is deleted.

Each agent needs to have a definition, or configuration, in the orchestration system to be accepted and controllable.
To add a new agent to the orchestration use the API calls as outlined below. Four configuration attributes need to be set:

  • agentId - a unique UUID identifying this agent
  • agentName - a string of unicode characters
  • gateway server - IP address or FQDN to roadrunner
  • gateway port - port used for metrics data streaming (default 55888)

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

$ uuidgen
ae311d23-5ca7-fake-8317-25example54a

or an online service like UUID Generator.

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

Step 2 - Grab secret from orchestration API and create the secrets file

As described in the previous sections, each agent needs an authentication token to be able to register to the orchestration and get managed. To retrieve the initial token, use the agent control UI or the API towards the orchestration service to define this agent and get the secret.

The API call requires only a unique agent ID to register this agent and return the secrets token.

Registering the agent with the orchestration, and generating the secret for authentication is then done by POST:ing the UUID to the orchestration API:

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

The output from the POST will be the initial secret for this agent, and should be placed in a file for use by the agent when launching. An example secret is shown below:

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

For the examples below, this secret is saved in a file called
/home/agentuser/ae311d23-5ca7-fake-8317-25example54a.yaml

Alternative Step 2 - token as environment variable instead of secrets file

In some cases it may be more suitable to provide the security token as an environment variable when launching the agent. If using this method, define the environment variable AGENT_AUTHENTICATION_TOKEN set to the token generated in step 1, example:

AGENT_AUTHENTICATION_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY2NlZGlhbi5jb20iLCJzdWIiOiJhcGl1c2VyQG55ZGVsbC5zZSIsImV4cCI6MTYyAksIOwKNywiYXVkIjoiIiwidG9rZW5JRCI6MTM0OCwidGVuYW50SUQiOiJjODRhZWUzNC04ODhjLTRmMDYtYmFmMy00NGZkMmNhM2JkM2UifQ.mUu5ZrsfjIWipzf5zqOpA4PUqWbu_CSWaSEmPC3wygv4

If using this method, note that the AGENT_ID also needs to be set through environment variable, since it cannot be fetched from the secrets file when not using a secrets file.

Step 3 - Launch an agent

Below are examples of two different methods to launch an actuate agent. The throughput agent is launched in the exact same way, with the exception of the TWAMP reflection port which is not needed for the throughput agent.

Both launch methods described below will open UDP for TWAMP reflection on port 4000 (internal is always 862), connect towards a roadrunner on 10.11.12.13:55777/tcp and define the secrets file as /home/agentuser/3dfe3705-42f3-fake-80bb-59a218a0900e.yaml

It is considered good practice to use the agent UUID as part of the file name for the secret so that if you deploy several agents on the same host they get their own secrets file.

See Agent secrets file options for other metods of providing the authentication secret to the agent

Step 3.a Launch agent using Docker-Compose

To use Docker-Compose, the configuration parameters should be put in a YAML file. AGENT_ID and access token is fetched from the secrets file defined.

Example for actuate agent:

version: '3'
services:
  twamp-sender-service:
    container_name: "my-actuate-container"
    image: "gcr.io/sky-agents/agent-actuate-amd64:r24.05"
    ports:
      - "4000:862/udp"
    hostname: "my-agent"
    restart: "always"
    environment:
            AGENT_MANAGEMENT_PROXY: "10.11.12.13"
            AGENT_MANAGEMENT_PROXY_PORT: "55777"
    volumes:
      - /home/agentuser/ae311d23-5ca7-fake-8317-25example54a.yaml:/run/secrets/secrets.yaml

Example for throughput agent:

version: '3'
services:
  tcp-agent-service:
    container_name: "my-throughput-container"
    image: "gcr.io/sky-agents/agent-throughput-amd64:r24.05"
    hostname: "my-agent"
    restart: "always"
    environment:
            AGENT_MANAGEMENT_PROXY: "10.11.12.13"
            AGENT_MANAGEMENT_PROXY_PORT: "55777"
    volumes:
      - /home/agentuser/ae311d23-5ca7-9921-fake-25example54a.yaml:/run/secrets/secrets.yaml

The agent can now be launched using the docker-compose up command:

sudo docker-compose up

If the agent configuration was placed in a file named something other than docker-compose.yml, then this needs to be specified on the command line:

sudo docker-compose -f mycomposefile.yml up

IMPORTANT:

Depending on your specific version of docker-compose, you might need to run:

sudo docker compose up

So if you have cut and paste the code using the hyphen and it doesn't work, try without the hyphen.

Step 3.b Launch agent on command line

Same setup, but using command line with environment variable options (--env) and port maps (-p)

Example for actuate agent:

sudo docker run -d -p 4000:862/udp \
--env AGENT_MANAGEMENT_PROXY="10.11.12.13" \
--env AGENT_MANAGEMENT_PROXY_PORT="55777" \
-v /home/agentuser/ae311d23-5ca7-fake-8317-25example54a.yaml:/run/secrets/secrets.yaml \
gcr.io/sky-agents/agent-actuate-amd64:r24.05

The -d option makes Docker launch the container in the background, in "detached" mode.

Step 3.c Launch agent without secrets file

Same setup, but using command line with environment variable options (--env) and port maps (-p)

Example for actuate agent:

sudo docker run -d -p 4000:862/udp \
--env AGENT_ID="ae311d23-5ca7-fake-8317-25example54a"
--env AGENT_AUTHENTICATION_TOKEN="eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhY2NlZGlhbi5jb20iLCJzdWIiOiJhcGl1c2VyQG55ZGVsbC5zZSIsImV4cCI6MTYyAksIOwKNywiYXVkIjoiIiwidG9rZW5JRCI6MTM0OCwidGVuYW50SUQiOiJjODRhZWUzNC04ODhjLTRmMDYtYmFmMy00NGZkMmNhM2JkM2UifQ.mUu5ZrsfjIWipzf5zqOpA4PUqWbu_CSWaSEmPC3wygv4"
--env AGENT_MANAGEMENT_PROXY="10.11.12.13" \
--env AGENT_MANAGEMENT_PROXY_PORT="55777" \
-v /home/agentuser/ae311d23-5ca7-fake-8317-25example54a.yaml:/run/secrets/secrets.yaml \
gcr.io/sky-agents/agent-actuate-amd64:r24.05

The -d option makes Docker launch the container in the background, in "detached" mode.


Note: Tokens expire after 14 days, so if using this method you need to generate a new token after that period of time if you need to restart or set up a new agent. Started and running agents re-negotiate token well before the expiry happens, so as long as you dont destroy the container you will still be able to stop and start agents. docker-compose down destroys the container so use graceful stop instead.

Step 4 - Check that the agent is running

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

$ docker ps
CONTAINER ID        IMAGE                                     COMMAND             CREATED             STATUS                 PORTS                                          NAMES
437d53381d83        agent-actuate-docker:yy.mm_nnn   "/sbin/monitor"     5 weeks ago         Up 5 weeks (healthy)   0.0.0.0:4000->862/udp,  my-agent

The output shows for how long the agent has been running, and the UDP port mapping informs that port 4000 is mapped on the host IP for TWAMP reflection.

Using agents with multiple interfaces / VRF / namespaces

All agents support attaching to multiple interfaces by configuration in the docker compose file or via docker command line startup options. The agent can either be provided with a specific -v mountpoint for a VRF / namespace or be provided with the full set of namespaces available in the /var/netns directory.

Difference between interfaces and namespaces

Linux systems natively support using multiple physical and virtual (VLAN) interfaces, typically named "eth0", "ens4" or something like "eth3.1111" for a VLAN residing on port eth3.
On a standard linux system these interfaces cannot have overlapping IP addressing subnets and routes, which means that usually each interface has its own IP subnet, and possibly a set of static routes pointing out destination networks that are reachable through a router on this subnet. There is also only one default route available on the system.
With the addition of namespaces / VRF the linux kernel provides the ability to separate the routing function from the system-global and apply a separate routing domain for each namespace / vrf. With this separation you can have several interfaces defined, with the same IP address, and with different default routes.

Note that when an interface is reassigned to a different namespace than the default one, it will typically disappear from the interface list seen with "ifconfig -a" command.

Example commands to add a namespace, and associate eth3.123 with this namespace

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

Example docker compose file that gives the agent access to the namespace directory on the system (last volume line)

version: '3'
services:
  agent_actuate:
    container_name: "mycontainername"
    image: "{{ actuate_image }}"
    restart: always
    network_mode: host
    ports:
      - "862:862/udp"
      - "7:7/udp"
    hostname: "myhostname"
    environment:
      AGENT_MANAGEMENT_PROXY: "12.13.14.15"
    privileged: true
    volumes:
          - /var/tmp/secrets/myagentsecret.yaml:/run/secrets/secrets.yaml 
          - /var/run/netns:/var/run/netns

Agent Launch Parameters

When launching an agent it accepts a number of parameters that define the instatiation of the container. The mandatory ones, like AGENT_MANAGEMENT_PROXY, have been described in the previous sections. Below is the full list of supported parameters, that can be provided as environment variables through the container instantiation when starting the agent.

ConfigurationComment
AGENT_IDOptional, UUID for the agent. Is fetched from secret file if not provided
AGENT_MANAGEMENT_PROXYMandatory, points to IP address or FQDN of the Agent Orchestration
AGENT_MANAGEMENT_PROXY_PORTOptional, defaults to 55777
AGENT_SOURCE_INTERFACEOptional
AGENT_MEASUREMENT_NETNSOptional, defines which namespace (VRF) to attach to for measurement
AGENT_REFLECTORS_DEFAULT_STATEagent: actuate only, set to "true" if an unmanaged agent should start up with TWAMP and UDP reflectors enabled - note that if the agent gets managed by the orchestration system, any reflector settings in the orchestration will override this environment variable setting
AGENT_AUTHENTICATION_TOKENOptional, set to value of your authenticationToken if not using a secrets file
AGENT_INNER_IPC_PORTOptional, auto-selected. Use this if there are namespace issues when launching more than one agent on the same host
AGENT_SECRETS_PATHDefines where the agent looks for its authentication secrets inside the container, the default path is “/run/secrets/secrets.yaml”

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

© 2024 Accedian Networks Inc. All rights reserved. Accedian®, Accedian Networks®,  the Accedian logo™, Skylight™, Skylight Interceptor™ and per-packet intel™, are trademarks or registered trademarks of Accedian Networks Inc. To view a list of Accedian trademarks visit: http://accedian.com/legal/trademarks/. 


Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.