Installing Device Agent on Raspberry Pi (RPi)

You can install the ThousandEyes Device Agent on a Raspberry Pi by following the instructions mentioned below.

Supported Platforms

Pre-requisites

  • A client ID and an auth secret (which will be shared separately) is required for installation and must be linked to the appropriate account group in your organization. This directs the agent to the correct account group upon registration. Please contact your account manager to set this up.

Base System Requirements

  • Supported Chipset: ARMv7, ARMv8

  • CPU: Quad-core ARM Cortex-A53 or newer (recommended)

  • RAM: 1 GB minimum (2 GB or more recommended)

  • Storage (micro-SD card): 8 GB minimum (16 GB or more recommended)

  • Networking: Fast Ethernet or Gigabit Ethernet (Gigabit preferred)

  • Power Supply: 5 V DC - Official Raspberry Pi power adapter (recommended)

It’s recommended that you use a Raspberry Pi 4 or later. The Raspberry Pi 3 has an Ethernet connection limited to 300 Mbps, which might not be enough to test the maximum speeds of many internet connections.

Supported Hardware Models

Model
System on Chip (SoC)
Memory

Raspberry Pi 3 (Model B)

BCM2837

1 GB

Raspberry Pi 3 (Model B+)

BCM2837b0

1 GB

Raspberry Pi 3 (Model A+)

BCM2837b0

512 MB

Raspberry Pi 4 (Model B)

BCM2711

1 GB, 2 GB, 4 GB, 8 GB

Raspberry Pi 400

BCM2711

4 GB

Raspberry Pi 5

BCM2712

2 GB, 4 GB, 8 GB

For more details refer to the official Raspberry Pi documentation here

Supported Software Versions

Operating System Distribution
Operating System Codename
Architecture

Raspberry Pi OS

Raspberry Pi OS Bookworm

32-bit / 64 bit

Raspberry Pi OS Lite

Bookworm

32-bit / 64 bit

Raspberry Pi OS Full

Bookworm

32-bit / 64 bit

Raspberry Pi OS Legacy

Bullseye

32-bit / 64 bit

Raspberry Pi OS Legacy Lite

Bullseye

32-bit / 64 bit

Raspberry Pi OS Legacy Full

Bullseye

32-bit / 64 bit

Ubuntu 22.04 LTS

Jammy Jellyfish

32-bit / 64 bit

Installation Steps

Setting up the Raspberry Pi

  1. Download and install Raspberry Pi Imager on your workstation from the official Raspberry Pi software source

  2. Connect your storage medium (micro-SD card, SSD, or USB drive) to your workstation.

    • For a micro-SD card, you may need a USB card reader if your laptop doesn’t have a built-in slot.

  3. Open the Raspberry Pi Imager application on your workstation.

    • Raspberry Pi Device: In the Raspberry Pi menu, select your Raspberry Pi model (e.g., Raspberry Pi 4).

    • Operating System: In the Operating System menu, select a supported OS. We recommend Raspberry Pi OS Lite (32-bit); this is a lightweight, headless version (no desktop environment) which provides faster performance and uses fewer resources. Alternatively, you may choose the 64-bit version, but you’ll need to follow the multi-arch workaround later to enable the agent.

    • Storage: In the Storage menu, select the connected storage device (micro-SD, SSD, etc.).

  1. Click Next to start the flashing process. After you click Next, the Raspberry Pi Imager will ask: Would you like to apply OS customisation settings?

  1. Click Edit Settings to customise your setup. This is strongly recommended so your Pi is ready to use after flashing.

    Key settings to configure:

    • Hostname

      • Change the default raspberrypi to something easy to remember, e.g., rpi-agent or rpi-lab.

    • Username & Password

      • Set a new username (default is pi, but you can choose your own).

      • Enter a secure password you’ll use for SSH login.

    • Wi-Fi (optional)

      • If you plan to use Wi-Fi instead of Ethernet, set your SSID and** Wi-Fi** password here.

    • Navigate to the Services tab to configure remote access.

      • Enable SSH:

        • Tick the Enable SSH checkbox.

      • Authentication Options:

        • Password Authentication

          • Use the username/password you defined earlier.

        • Allow Public-Key Authentication Only

          • Select the radio button to enforce key-based login only.

          • If you don’t already have an SSH key, generate one on your workstation:

            ssh-keygen -t rsa -b 4096

          • Copy the contents of your public key (usually in ~/.ssh/id_rsa.pub). For existing keys copy the contents the key from the below location:

            cat ~/.ssh/id_rsa.pub

          • Paste it into the Set authorised key for user input field in the Imager. This ensures your Pi accepts only SSH keys, which is more secure than password logins.

Enabling SSH here means you can immediately connect to the Raspberry Pi after first boot, without needing to attach a keyboard or monitor.

  1. After setting your hostname, username, password, Wi-Fi (if needed), and SSH options, click Save to return to the Raspberry Pi Imager main screen, then click Yes to flash the OS with your customised settings onto the selected storage device. Wait for the write and verification to complete before removing the card.

Deploying and Installing the Device Agent

1. Connect to your Raspberry Pi

From your workstation, use SSH:

ssh <username>@<pi-hostname-or-IP>

Log in with the username/password you set in Raspberry Pi Imager. Or, if you enabled public-key authentication, your key will be used automatically.

If SSH is not enabled, use the raspberry pie GUI options to enable SSH:

sudo raspi-config

Navigate to Interface Options and enable SSH for future remote access.

2. Obtain the Device Agent software

There are 32 bit and 64 bit packages available for the device agent. The uname -m command will give you the architecture of the device.

For 32 bit, run the following command:

pi@raspberrypi:~ $ uname -m
armv7l
pi@raspberrypi:~ $

For 64 bit, run the following command:

root@rpi4:/tmp# uname -m
aarch64
root@rpi4:/tmp#

Contact your Cisco Connected Devices Account Team to obtain the latest Raspberry Pi agent package (cdev_agent_package-*rpi*.tar.gz).

3. Copy the software image to the Pi

From your workstation, transfer the agent file via scp:

scp cdev_agent_package_*rpi*.tar.gz <username>@<pi-hostname-or-IP>:~///

In case, you are not aware of the version, you can run the following command:

scp cdev_agent_package-*-rpi.tar.gz <username>@<pi-hostname-or-IP>:~

4. Connect to the Raspberry Pi via SSH

  • When using password authentication:

ssh <username>@<pi-hostname-or-IP>

  • When using public key authentication: If your private key is located at ~/.ssh/my_raspberry_pi_key and you want to connect to a Raspberry Pi with the IP address 192.168.1.100 as the user pi, the command would be:

ssh -i ~/.ssh/my_raspberry_pi_key <username>@<pi-hostname-or-IP>

5. Create a working directory and extract the tarball

On the Raspberry Pi, run:

mkdir ~/sk-agent && cd ~/sk-agent
mv ~/cdev_agent_package-*rpi*.tar.gz .
tar -xvzf cdev_agent_package-*rpi*.tar.gz

6. Install the agent package

Run the .deb installer:

sudo apt install ~/sk-agent/cdev-agent-updater_*rpi*.deb

If you’re running a 64-bit OS (arm64), first enable 32-bit libraries:

sudo dpkg --add-architecture armhf
sudo apt update
sudo apt install -y libc6:armhf libstdc++6:armhf libgcc-s1:armhf

Then rerun the dpkg -i command.

7. Register the agent with your Base Model, Client String, and Authentication Secret

Base Model

A base model is a string to identify the type of platform the agent is running on. It is used to determine the type of agent package to be used in the device.

For a 32 bit device, you can set the model as rpi.

For a 64 bit device, you can set the model as rpi-64.

Remove the default "unknown" string and add the string as mentioned above.

Client String

A client string is a unique identifier that connects the Device Agent to your ThousandEyes account and test configuration. It defines default testing parameters and enables features such as hourly speed and jitter tests, or RealSpeed.

After the agent installs, enter the provided client string when prompted. If you enter the client string correctly, your device automatically registers with your ThousandEyes account. If the device does not appear, contact your account manager and provide the Unit ID.

Remove the default "unknown" string before copying your client string. Contact your Cisco Connected Devices Account Team to obtain your client string.

Authentication Secret

Authentication Secret is used by the agent to authenticate with the backend. It is unique, Contact your Cisco Connected Devices Account Team to obtain the string.

Remove the default "unknown" string before copying your authentication secret.

Verify the Installation

  • Check the service status:

systemctl status thousandeyes_cdev

It should show as active (running).

Uninstall the Agent

To uninstall the agent, run the following command:

sudo dpkg --purge cdev-agent-updater

For example:

root@raspberrypi:~# sudo dpkg --purge cdev-agent-updater
(Reading database ... 120706 files and directories currently installed.)
Removing cdev-agent-updater (7.6) ...
Purging configuration files for cdev-agent-updater (7.6) ...
root@raspberrypi:~#
PreviousInstalling Device Agent with DockerNextConnected Devices Agent Release Versions

Last updated