> 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/production-integration-guides/openwrt/openwrt-ipk.md).

# OpenWrt IPK

Use this guide to retrieve the signed OpenWrt IPK from the ThousandEyes feed, store it in your own artifact repository, and add it through your normal firmware build.

Confirm that your device meets the [System Requirements](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/getting-started/system-requirements.md), then choose the Agent Updater or agent-only model in [Plan, Deploy, and Update the Agent](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/plan-deploy-and-update-the-agent.md). Use the matching tab throughout this guide.

## 1. Confirm the Package Architecture

1. Run this command on the target device to identify the feed family:

   ```bash
   opkg print-architecture
   ```
2. Use the device-specific architecture with the highest priority number and map it to a `<family>` value in the table below.

Ignore generic entries such as `all` and `noarch`. If a representative target is unavailable, use the package architecture reported by the firmware build.

| Device-specific OpenWrt architecture   | Use as `<family>` |
| -------------------------------------- | ----------------- |
| `aarch64_*`                            | `arm64`           |
| `arm_cortex-a*`                        | `armv7a`          |
| `mips_*`                               | `mips`            |
| `mipsel_*`                             | `mipsel`          |
| `i386_*`, `i486_*`, `i586_*`, `i686_*` | `x86`             |
| `x86_64`                               | `x86_64`          |

Do not use `uname -m` to identify the package ABI. It reports the machine architecture, not the OpenWrt package ABI.

## 2. Retrieve the IPK

Run the remaining package-preparation commands on a separate computer or build host with Bash and `curl`. You do not need to copy or install the IPK on the target during this stage.

The commands below retrieve the latest agent-only package for an `arm64` target.

For the Agent Updater, replace `te-cdev-agent` with `te-cdev-agent-updater`. For another architecture, replace `arm64` with the matching feed family above.

{% hint style="info" %}
The examples use the latest release:

`https://downloads.thousandeyes.com/te-cdev-agent/openwrt/arm64/`

If ThousandEyes asks you to pin to [another version](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/connected-devices-release-versions), use the versioned endpoint instead. For example, the agent-only `arm64` feed for version 7.15.4 is:

`https://downloads.thousandeyes.com/te-cdev-agent/main/v7.15.4/openwrt-feed/arm64/`
{% endhint %}

1. On your preparation computer, create and enter a new empty directory for the package files.

   If this directory already exists, choose another name so files from different releases are not mixed:

   ```bash
   mkdir thousandeyes-openwrt-package
   cd thousandeyes-openwrt-package
   ```
2. Download the package index:

   ```bash
   curl -fLO https://downloads.thousandeyes.com/te-cdev-agent/openwrt/arm64/Packages
   ```
3. Read and confirm the exact filename and checksum from the index:

   ```bash
   IPK="$(sed -n 's/^Filename: //p' Packages | head -n 1)"
   IPK_SHA="$(sed -n 's/^SHA256sum: //p' Packages | head -n 1)"
   test -n "$IPK" || { echo "No package filename found" >&2; exit 1; }
   test -n "$IPK_SHA" || { echo "No package checksum found" >&2; exit 1; }
   printf 'Package: %s\nSHA-256: %s\n' "$IPK" "$IPK_SHA"
   ```
4. Download the IPK named by the index:

   ```bash
   curl -fLO "https://downloads.thousandeyes.com/te-cdev-agent/openwrt/arm64/$IPK"
   ```
5. Verify the signed ThousandEyes feed if your package retrieval or firmware build process doesn’t already do so.

   If the process already validates OpenWrt feed signatures and package checksums, continue to the next step. Otherwise, verify the download before using the IPK. Run the following commands in an OpenWrt SDK, ImageBuilder, or lab-device environment with `usign` and `sha256sum`. The commands verify the files without installing the IPK.

   Download the index signature and the immutable signing key for the package version:

   ```bash
   curl -fLO https://downloads.thousandeyes.com/te-cdev-agent/openwrt/arm64/Packages.sig
   PACKAGE="$(sed -n 's/^Package: //p' Packages | head -n 1)"
   PACKAGE_VERSION="$(sed -n 's/^Version: //p' Packages | head -n 1 | cut -d- -f1)"
   KEY_ROOT="https://downloads.thousandeyes.com/$PACKAGE/main/v$PACKAGE_VERSION/openwrt-feed"
   curl -fLO "$KEY_ROOT/thousandeyes-openwrt-feed.pub"
   ```

   Verify the signed index and downloaded IPK:

   ```bash
   usign -V -p thousandeyes-openwrt-feed.pub -m Packages -x Packages.sig
   printf '%s  %s\n' "$IPK_SHA" "$IPK" | sha256sum -c -
   ```

The latest feed path does not contain a `/latest` segment. Its signed indexes can be replaced or rolled back, while the IPKs they reference remain immutable.

## 3. Prepare the Agent Configuration

1. On the preparation computer, create `skagent.cfg` in your preferred text or code editor, using the OpenWrt configuration below.

   Save it in the working directory alongside the downloaded IPK. Do not unpack or modify the IPK to replace its placeholder configuration, because doing so changes the published package.

OpenWrt has no standard data model for every required identity value. Confirm the source used for the model, client, WAN MAC, firmware version and serial number on the target firmware.

To find the configured WAN interface, inspect the OpenWrt network configuration:

```bash
cat /etc/config/network
```

Find the section labeled `config interface 'wan'`. Its `option device` or `option ifname` identifies the default WAN port, such as `eth0` or `wan`.

Confirm that the active default route uses the same interface:

```bash
ip route show default
```

Start from this configuration and replace every placeholder. Your ThousandEyes contact supplies the Org Client ID or agreed production label and the authentication secret. The `uci` path used for the serial number is an example and must be verified on the target.

```toml
identity.base='YOUR-DEVICE-MODEL'
identity.client='YOUR-ORG-CLIENT-ID-OR-PRODUCTION-LABEL'

[identity.mac]
input='network_interface'
interface='YOUR-WAN-INTERFACE'

[resource_checker.cross-traffic]
input='/sys/class/net bytes'

[resource_checker.cross-traffic.interfaces]
input='default route'

[metadata.Firmware]
input='program'
command=["/usr/bin/awk", "-F'", "/^DISTRIB_REVISION=/ {print $2}", "/etc/openwrt_release"]

[metadata.SerialNumber]
input='program'
command=["/sbin/uci", "get", "env.var.serial"]

[authentication]
secret='YOUR-AUTHENTICATION-SECRET'
```

{% tabs %}
{% tab title="Agent Updater" %}
Add the Updater working directory:

```toml
[updater.cdev_package]
working_directory='/tmp/cdev'
```

{% endtab %}

{% tab title="Agent-only" %}
The Agent-only configuration does not require an `[updater.cdev_package]` table.
{% endtab %}
{% endtabs %}

Run each configured file or command input directly on the target before relying on it. For mapped production routing, replace the literal `identity.client` value with a stable file or program input that identifies the ISP. Use [Identity and ISP Routing](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md) for the routing patterns.

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](https://docs.thousandeyes.com/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.

2. At first boot, use the platform's ACS or secret provider to inject the production authentication secret.

   Do not compile the secret into downloadable firmware.

If the device uses OpenSync for its configuration data, use the [OpenSync template](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/opensync.md) instead of reproducing it here.

Use the [Configuration Reference](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/configuration-reference.md) to look up individual fields. For devices with more than one WAN counter, see its [cross-traffic detection](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/configuration-reference.md#cross-traffic-detection) guidance.

At the end of this step, the preparation directory contains the unchanged IPK and your separate completed `skagent.cfg`.

## 4. Add the IPK and Configuration to the Firmware Build

1. Upload the unchanged IPK to your artifact repository or add it directly to the package input used by your normal OpenWrt firmware build.

   Keep its filename, package metadata, installation paths, and architecture checks intact.
2. Copy the separate `skagent.cfg` into the firmware root-filesystem overlay at its final device path.

   The overlay adds your configuration to the generated firmware image alongside the unchanged IPK; it does not add the file to the IPK itself.

   The examples use `files` as the root-filesystem overlay directory. If your firmware build uses another directory or configuration layer, use its equivalent and preserve the final path shown above.
3. Apply the configuration layer after the package contents.

   The generated image then contains your completed configuration instead of the packaged placeholder, while the signed IPK remains unchanged.

   If this replaces another agent package, remove that package and disable its startup integration so the resulting image cannot run two agent instances.

## 5. Add Startup and Persistence

Start the selected component only after the target has a usable WAN route, DNS resolution, outbound HTTPS access, and the correct time.

{% tabs %}
{% tab title="Agent Updater" %}

1. Run the packaged startup helper to validate the device family and CPU baseline before it starts the Updater:

   ```bash
   exec /usr/libexec/te-cdev-agent-updater/start
   ```
2. Configure the target's process manager to restart the Updater after a failure and keep one instance running. The Updater supervises the agent.
   {% endtab %}

{% tab title="Agent-only" %}

1. Use the packaged compatibility helper:

   ```bash
   exec /usr/libexec/te-cdev-agent/start
   ```

2. Configure the target's process manager to restart the agent after an unexpected exit and stop it cleanly before replacing the package.

   Keep one agent instance running.
   {% endtab %}
   {% endtabs %}

3. Test startup after a complete power cycle.

   Confirm that the service waits for a usable WAN route and that the selected package and configuration remain present.

## 6. Validate the Integration

Check the identity and metadata reported by the agent.

{% tabs %}
{% tab title="Agent Updater" %}

1. After the Updater installs the agent, run the device-info command:

   ```bash
   cd /tmp/cdev/installation
   bin/skagent --device-info
   ```

{% endtab %}

{% tab title="Agent-only" %}

1. Run the device-info command:

   ```bash
   cd /opt/samknows/router_agent
   bin/skagent --device-info
   ```

{% endtab %}
{% endtabs %}

2. Confirm the model, client, WAN MAC, serial number, firmware, and WAN interface before and after a cold boot.
3. Run the agent in self-test mode by following the instructions for your selected agent model:

{% tabs %}
{% tab title="Agent Updater" %}
Stop the Updater before you run self-test mode. If it runs in the current terminal, press `Ctrl+C`. If you started it directly with `-D`, stop it by running:

```bash
/opt/thousandeyes/cdev/router_agent_updater/bin/router_agent_updater -K
```

If the integration starts the Updater as a managed service, stop that service first.

**Agent Updater v7.16 or later**

Run self-test mode through the Updater:

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

**Agent Updater v7.14 or v7.15**

Run self-test mode through the installed agent:

```bash
cd /tmp/cdev/installation
bin/skagent -K
bin/skagent \
  --config-file /opt/thousandeyes/cdev/router_agent_updater/etc/skagent.cfg \
  --self-test-mode
```

Versions earlier than v7.14 do not support self-test mode.
{% endtab %}

{% tab title="Agent-only" %}
For agent version v7.14 or later, stop the agent service, then run the agent in self-test mode:

```bash
cd /opt/samknows/router_agent
bin/skagent -K
bin/skagent --self-test-mode
```

Versions earlier than v7.14 do not support self-test mode.
{% endtab %}
{% endtabs %}

4. Restart the normal service after self-test.

   Confirm that the Unit ID remains stable after another cold boot or `sysupgrade` that preserves configuration.

   Use [Validate with Self-Test Mode](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/validate-with-self-test-mode.md) to interpret the result.

## 7. Manage Subsequent Package Updates

When the firmware image controls the IPK version, repeat the signed-index verification and retrieval steps, add the new immutable IPK to the build, and validate and deploy a new firmware image. This keeps the package version aligned with the firmware manifest and rollback path.

You can use a targeted `opkg upgrade <package-name>` when the product is designed to manage this package independently in writable storage. In that case, validate available storage, package compatibility, persistence across firmware upgrades, and rollback behavior. Do not run a bare `opkg upgrade`.

{% hint style="info" %}
After the integration passes, use [Plan, Deploy, and Update the Agent](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/plan-deploy-and-update-the-agent.md) for device QA, rollout, and updates.
{% endhint %}
