> For the complete documentation index, see [llms.txt](https://docs.thousandeyes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/getting-started/raspberry-pi.md).

# Raspberry Pi

Use a supported Raspberry Pi to demonstrate the agent, validate activation in the expected organization, and run assigned tests.

This guide installs the Agent Updater from a Debian package.

## Before You Start

Use a supported Raspberry Pi model and operating system:

| Model                   | Processor | 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, 2, 4 or 8 GB |
| Raspberry Pi 400        | BCM2711   | 4 GB            |
| Raspberry Pi 5          | BCM2712   | 2, 4 or 8 GB    |

Raspberry Pi 4 or later is recommended. Raspberry Pi 3 remains supported, but its Ethernet path limits the speed it can measure.

Supported Raspberry Pi operating systems are:

* Raspberry Pi OS Bookworm: standard, Lite, or Full, 32-bit or 64-bit.
* Raspberry Pi OS Legacy Bullseye: standard, Lite, or Full, 32-bit or 64-bit.
* Ubuntu 22.04 LTS, 32-bit or 64-bit.

Use wired Ethernet, the official power supply, and at least 8 GB of storage; 16 GB is recommended. Wi-Fi and desktop activity can distort measurements.

Ask your ThousandEyes contact for the signed `cdev_agent_package-*.tar.gz` matching the host. Have the Org Client ID for lab testing or the agreed production label and the corresponding authentication secret ready.

## 1. Prepare a Raspberry Pi

{% hint style="info" %}
Skip this step when the supported operating system is already installed.
{% endhint %}

1. Use [Raspberry Pi Imager](https://www.raspberrypi.com/software/) to select the Raspberry Pi model, operating system, and storage card.

   ![Select the Raspberry Pi model, operating system and storage](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-6c68faf7b4c76bbbd3b5691776bbd772e60b6047%2Finstall_rpi_1.png?alt=media)

   Select **Edit settings** before writing the card.

   ![Open the Raspberry Pi Imager settings](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-15111fcf67fff5b9683e98971dcb15d2c6bc1833%2Fconnected-devices%3Adevice-agents%3Ainstall-rpi_2.png?alt=media)

   Set a hostname, username, and password. Configure Wi-Fi only if Ethernet will not be available for initial access.

   ![Set the hostname and login details](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-0cb06f3163145a1876087dc7995ab05b42cab889%2Fconnected-devices%3Adevice-agents%3Ainstall-rpi_3.png?alt=media)

   Under **Services**, enable SSH. Public-key authentication is recommended.

   ![Enable SSH in Raspberry Pi Imager](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-78b2163f25050a8aeaa5eabba867b742990a26a4%2Fconnected-devices%3Adevice-agents%3Ainstall-rpi_4.png?alt=media)

   Write the card, start the Raspberry Pi, and connect it by Ethernet.
2. Replace `pi` and `raspberrypi.local` with the username and hostname that you configured in Raspberry Pi Imager:

   ```bash
   ssh pi@raspberrypi.local
   cat /etc/os-release
   uname -m
   ```

   If SSH is disabled, connect a keyboard and monitor to the Raspberry Pi and open a terminal. Run `sudo raspi-config`, select `3 Interface Options > I1 SSH`, and enable SSH. Then retry the SSH connection.

   `armv7l` is 32-bit. `aarch64` is 64-bit.
3. Install the legacy 32-bit libraries only when ThousandEyes supplies an `armhf` package and instructs you to use it.

   The current `rpi_64` Updater package is native ARM64 and does not declare `armhf` dependencies, so do not add these libraries to a 64-bit host by default:

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

## 2. Verify and Extract the Downloaded Package

Complete this step on the workstation where you downloaded the package.

Keep the downloaded package compressed until you verify its signature. Verification checks the exact bytes of the `.tar.gz` file.

{% hint style="warning" %}
The package filename must end in `.tar.gz`. Its signature must end in `.tar.gz.signature`.

If the package ends in `.tar`, the browser might have decompressed it. Do not rename or recompress it because the signature will not match. Disable browser settings that automatically open downloaded files, then download the original package again.
{% endhint %}

1. On the computer where you downloaded the package, create a folder containing only the agent package and its signature.
2. Open a terminal and change to that folder. You can type `cd` , drag the folder into Terminal, and press Return.

   For example:

   ```bash
   cd /Users/<your-username>/Downloads/myagentpackage
   ```
3. Replace `MY_AGENT_PACKAGE.tar.gz` in the commands below with the complete filename of your downloaded package. Confirm that the package is still gzip-compressed:

   ```bash
   file MY_AGENT_PACKAGE.tar.gz
   ```

   The output must include:

   ```
   gzip compressed data
   ```
4. Download the Cisco Root CA certificate:

   ```bash
   curl -fLO https://www.cisco.com/security/pki/certs/csirca4096.pem
   ```
5. Verify the package. Replace both example filenames with the complete filenames you downloaded:

   ```bash
   openssl cms -verify -binary \
     -CAfile csirca4096.pem \
     -in MY_AGENT_PACKAGE.tar.gz.signature \
     -inform DER \
     -content MY_AGENT_PACKAGE.tar.gz \
     -out /dev/null
   ```

   Continue only when the command reports:

   ```
   Verification successful
   ```
6. Extract the verified outer package:

   ```bash
   tar -xzf MY_AGENT_PACKAGE.tar.gz
   ```

The extracted directory contains the `.deb` file to install.

## 3. Install the Agent Updater

1. From the extracted package directory on your workstation, copy the `.deb` file to the target:

   ```bash
   scp cdev-agent-updater_*.deb pi@raspberrypi.local:~/
   ```
2. Connect to the target, then use `apt` to install the package and its declared dependencies:

   ```bash
   ssh pi@raspberrypi.local
   sudo apt install ~/cdev-agent-updater_*.deb
   ```

   The package installs the Agent Updater under `/opt/thousandeyes/cdev/router_agent_updater` and registers the `thousandeyes_cdev` systemd service.

## 4. Enter the Agent Configuration Values

1. The installer prompts for:

   | Prompt                | Enter                                                                        |
   | --------------------- | ---------------------------------------------------------------------------- |
   | Base model            | `rpi` for the 32-bit Raspberry Pi package or `rpi-64` for the 64-bit package |
   | Client                | Org Client ID for lab testing, or the agreed production label                |
   | Authentication secret | Lab secret for lab testing, or production secret for deployment              |

   The installer selects the interface carrying the default IPv4 route for the agent identity. Disconnect any VPN first, or enter a different stable interface when prompted.

When you test a production image in the lab, set `client` to your Org Client ID so the agent appears in your organization.

For the final production image:

* **ISP-led integrations** must use their organization's production `client`.
* **OEM-led integrations (multi-ISP firmware)** should use dynamic lookup or an OEM-selected label, as described in [Identity and ISP Routing](/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md).
* **OEM-led integrations (single-ISP firmware)** should request and use the ISP organization's production `client`. They can also use the same dynamic lookup or label used for multi-ISP firmware distributions. This approach requires an additional backend mapping coordinated with Cisco.

Clear the pre-filled `unknown` value before entering each answer. An accepted `unknown` value prevents correct activation.

2. To correct an answer after installation, rerun the package configuration and restart the service:

   ```bash
   sudo dpkg-reconfigure cdev-agent-updater
   sudo systemctl restart thousandeyes_cdev
   ```

## 5. Confirm Activation

1. Confirm that the service is active:

   ```bash
   sudo systemctl status thousandeyes_cdev
   ```

   Press `q` to exit the status view.
2. Follow the log:

   ```bash
   sudo journalctl -u thousandeyes_cdev -f
   ```

   Wait for the `Service started` message. It confirms that the Updater installed and started the agent. Press `Ctrl+C` to stop following the log.

## 6. Validate the Agent with Self-Test Mode

1. Stop the `thousandeyes_cdev` service before running the agent in self-test mode.

   ```bash
   sudo systemctl stop thousandeyes_cdev
   ```
2. Run the Agent Updater in self-test mode:

   ```bash
   sudo /opt/thousandeyes/cdev/router_agent_updater/bin/router_agent_updater \
     --self-test-mode
   ```

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Agent Updater versions v7.14 and v7.15 require you to run the installed agent in self-test mode:</p><pre class="language-bash"><code class="lang-bash">cd /tmp/cdev/installation
   bin/skagent -K
   bin/skagent --self-test-mode
   </code></pre><p>Versions earlier than v7.14 do not support self-test mode.</p></div>

All tests should pass. If a test fails, use the applicable troubleshooting guide:

* If self-test fails, follow [Validate with self-test mode](/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/validate-with-self-test-mode.md).
* If installation or activation fails, follow [Installation and activation troubleshooting](/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/installation-and-activation-troubleshooting.md).

## 7. Confirm Speed Results Are Satisfactory

Your first self-test speed measurements should be close to, but slightly below, the theoretical maximum speeds.

By default, self-test mode targets servers outside your network to reflect the home broadband experience. When a home accesses apps hosted outside your network, latency can reduce throughput.

TCP tests reach about 94% of line rate. On a 1 Gbps line, the theoretical maximum is 940 to 949 Mbps. Added latency might reduce throughput by up to 20%.

{% hint style="info" %}
**Troubleshooting Low Speed Results**

If self-test passes but speed is below the intended tier, use [Speed quick wins](/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/speed-quick-wins.md).
{% endhint %}

## 8. Restart the Service and Confirm in the Portal

1. Restart the `thousandeyes_cdev` service after self-test:

   ```bash
   sudo systemctl start thousandeyes_cdev
   ```
2. Confirm that the agent appears in the expected organization under **Connected Devices > Settings > Agent Settings > Agents**.

## Updating the Agent Updater

Verify and copy the newer `.deb` using the same procedure as the initial installation, then install it on the Raspberry Pi:

```bash
sudo apt install ~/cdev-agent-updater_*.deb
```

The package restarts the service. It regenerates `skagent.cfg` from the stored package answers and retains the previous file as `skagent.cfg.old`. Confirm the resolved identity and authentication after upgrading.

## Removing the Agent Updater

To remove the package and its configuration:

```bash
sudo dpkg --purge cdev-agent-updater
```

If the Raspberry Pi was a lab substitute, return to [Plan, deploy and update the Agent](/product-documentation/connected-devices/device-agents/plan-deploy-and-update-the-agent.md) and choose the guide for the production device. If the Raspberry Pi is the production target, use the same page for production planning, device QA, rollout, and updates.