Installing Device Agent with Docker

You can install the ThousandEyes Device Agent in a Docker container on a 64-bit Linux distribution with kernel version 5.15 or later. It functions like the Router Agent and can be deployed on desktop computers or servers, managed like any other router. The only difference with Docker Device agent is there is no cross-traffic detection.

System Requirements

• Currently, only x86 computers are supported. The aarch64/ARM64 such as Mac M1 machines are not supported.

• The Device Agent occupies 15 MB of disk space and requires at least 50 MB of RAM for speed tests. For video streaming tests, it may need 250 MB of RAM or more, depending on the service and bandwidth.

Pre-requistes

1. A client ID is needed for installation and must be linked to the appropriate account group in your organization. This directs the Docker agent to the correct account group upon registration. Please contact your account manager to set this up.

2. You need to have Docker installed.

Getting Started

1. Pull the latest image from DockerHub:

   docker pull thousandeyes/device-agent

a. You can also define a specific version listed here.

For example, docker pull thousandeyes/device-agent:v6.3

1. Start the agent as a daemon (the NET_ADMIN and NET_RAW is needed for the UDP speed test).

a. On all platforms except Windows:

docker run -d --env=CLIENT_ID=<PASTE CLIENT ID HERE> --network=host --cap-add=NET_ADMIN --cap-add=NET_RAW --restart=on-failure thousandeyes/device-agent

b. On Windows, running Docker Desktop or Docker in a WSL2 machine:

C:\Windows\System32>wmic.exe csproduct get uuidUUID COPY THIS AND PASTE IT IN THE FOLLOWING LINE - 4C4C4544-0034-5310-8054-B8C04F334D32

C:\Windows\System32>docker run -d --env=CLIENT_ID=<PASTE CLIENT ID HERE> --env=UUID=<PASTE UUID HERE> --network=host --cap-add=NET_ADMIN --cap-add=NET_RAW --restart=on-failure thousandeyes/device-agent

1. If successful, the agent will start in the background and print a container ID to the terminal. To get the agent ID, check the logs by running:

   docker logs CONTAINER_ID_FROM_PREVIOUS_STEP

You will see the container’s logs, populated with entries from the agent. Search the logs for ‘Activation response’ to find the Unit ID for your docker agent - it will look similar to this:

[2022-06-01 16:39:38.221] [task_runner] [trace] Activation response: 75749573

In the above example, '75749573' is the unit ID.

1. You can now find the agent using the unit ID within app.thousandeyes.com. For any troubleshooting, your account manager may require this ID.

Update the Agent (including steps to stop, remove, and start the agent)

To update the agent, follow the instructions below (make sure to replace <version>by the version you intend to upgrade or latest if they want to use the latest release):

1. Find the current process ID:

docker ps -a | grep agent

1. Stop the container:

docker stop CONTAINER_ID_FROM_STEP_1

1. Remove the container:

docker rm CONTAINER_ID_FROM_STEP_1

1. Re-install the latest (or replace version with latest for the latest release):

docker pull thousandeyes/device-agent:<version>

1. Start the agent as per the regular instructions, using the new version string (or latest).

Upgrading from SamKnows dockerhub agent (legacy)

First, delete the existing container and install a new agent by following the instructions provided earlier. If the Docker agent keeps the same MAC address, both the agent and its data will remain intact.

If the agent is currently stopped, start with step 3. If it is running, please stop it first before by proceeding from step 2.

Rootless Container Runtimes

The above instructions assume you’re using a regular “rootful” installation of docker. When using a rootless runtime (such as podman) or running docker in rootless mode, you need to ensure that no seccomp confinement restricts the container by adding --security-opt=seccomp=unconfined to the run command.