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.

• Certain performance optimisations require system administrator privileges, so for current versions only "rootful" docker runtimes are 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-Requisites

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 - as mentioned above, to support all tests this must be able to run containers with root privileges.

Getting Started

1. Pull the latest image from DockerHub:

   docker pull thousandeyes/device-agent

   a. You can also define a specific version published on Docker Hub. The differences between versions of the agent are documented in the release notes.

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

2. Start the agent container detached from your terminal (-d).

   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 uuid
   UUID
   
   4C4C4544-0034-5310-8054-B8C04F334D32

   Copy the UUID output above (in this case 4C4C4544-0034-5310-8054-B8C04F334D32) and use it in the next command:

   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

3. If successful, the agent will start in the background and a container ID will be printed to your terminal. To get the agent's unit 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.

4. 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 container ID of the running agent:

   docker ps -a | grep agent

2. Stop the container:

   docker stop CONTAINER_ID_FROM_STEP_1

3. Remove the container:

   docker rm CONTAINER_ID_FROM_STEP_1

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

   docker pull thousandeyes/device-agent:<version>

5. 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 Notes

As mentioned above, some tests will not work in a rootful container runtime, such as podman when run as a regular user: in particular, setting certain capabilities will silently fail, causing some tests to fail to run.

Known issues with Rootless containers at present:

• UDP Speed Tests are not currently supported.

• Traceroute Tests may fail because of the lack of ability to create raw IP frames.

• ICMP Ping Tests may fail for the same reason.