> 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-feed-and-imagebuilder.md).

# OpenWrt Feed and ImageBuilder

Use this guide to configure OpenWrt ImageBuilder to resolve and add the IPK directly from the signed ThousandEyes feed.

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. Adding the Current Feed to ImageBuilder

The build host must have `curl` and `sha256sum`. Run the following commands from the extracted OpenWrt ImageBuilder directory.

1. Get the target package architecture, confirm that the command returned a value, and map it to the corresponding feed family:

   ```bash
   ARCH="$(make -s val.ARCH_PACKAGES)"
   test -n "$ARCH" || { echo "No ImageBuilder package architecture found" >&2; exit 1; }
   case "$ARCH" in
     aarch64_*) FAMILY="arm64" ;;
     arm_cortex-a*) FAMILY="armv7a" ;;
     i386_*|i486_*|i586_*|i686_*) FAMILY="x86" ;;
     x86_64) FAMILY="x86_64" ;;
     mipsel_*) FAMILY="mipsel" ;;
     mips_*) FAMILY="mips" ;;
     *) echo "Unsupported ImageBuilder package architecture: $ARCH" >&2; exit 1 ;;
   esac

   printf 'Feed family: %s\n' "$FAMILY"
   ```

   Use the ImageBuilder target architecture. Do not copy a family selected on another development device.

   Each IPK in the feed is marked `Architecture: all`, so ImageBuilder accepts it across compatible OpenWrt architecture names. The filename retains its family suffix, such as `_armv7a.ipk`. The package's architecture check rejects an incompatible target.

   The commands below retrieve the latest agent-only package. For the Agent Updater, replace `te-cdev-agent` with `te-cdev-agent-updater`. The detected `$FAMILY` value selects the matching feed family.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The latest agent-only <code>arm64</code> feed is:</p><p><code>https://downloads.thousandeyes.com/te-cdev-agent/openwrt/arm64/</code></p><p>If ThousandEyes asks you to pin another version, see <a href="https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/connected-devices-release-versions">Connected Devices Agent Release Versions</a> and use the versioned endpoint instead. For example, the agent-only <code>arm64</code> feed for version 7.15.4 is:</p><p><code>https://downloads.thousandeyes.com/te-cdev-agent/main/v7.15.4/openwrt-feed/arm64/</code></p></div>
2. Download the package index and its signature:

   ```bash
   curl -fL "https://downloads.thousandeyes.com/te-cdev-agent/openwrt/$FAMILY/Packages" \
     -o /tmp/thousandeyes-openwrt-Packages
   curl -fL "https://downloads.thousandeyes.com/te-cdev-agent/openwrt/$FAMILY/Packages.sig" \
     -o /tmp/thousandeyes-openwrt-Packages.sig
   ```
3. Read the package name and version from the index. These values locate the matching immutable signing key:

   ```bash
   PACKAGE="$(sed -n 's/^Package: //p' /tmp/thousandeyes-openwrt-Packages | head -n 1)"
   PACKAGE_VERSION="$(sed -n 's/^Version: //p' /tmp/thousandeyes-openwrt-Packages | head -n 1 | cut -d- -f1)"
   test -n "$PACKAGE" || { echo "No package name found" >&2; exit 1; }
   test -n "$PACKAGE_VERSION" || { echo "No package version found" >&2; exit 1; }
   printf 'Package: %s\nVersion: %s\n' "$PACKAGE" "$PACKAGE_VERSION"
   ```
4. Set the immutable signing-key location, then download the key and its checksum:

   ```bash
   KEY_ROOT="https://downloads.thousandeyes.com/$PACKAGE/main/v$PACKAGE_VERSION/openwrt-feed"
   curl -fL "$KEY_ROOT/thousandeyes-openwrt-feed.pub" \
     -o /tmp/thousandeyes-openwrt-feed.pub
   curl -fL "$KEY_ROOT/thousandeyes-openwrt-feed.pub.sha256" \
     -o /tmp/thousandeyes-openwrt-feed.pub.sha256
   ```
5. Verify the signing key:

   ```bash
   (cd /tmp && sha256sum -c thousandeyes-openwrt-feed.pub.sha256)
   ```
6. Verify the signed package index:

   ```bash
   ./staging_dir/host/bin/usign -V \
     -p /tmp/thousandeyes-openwrt-feed.pub \
     -m /tmp/thousandeyes-openwrt-Packages \
     -x /tmp/thousandeyes-openwrt-Packages.sig
   ```
7. Read the signing-key ID and add the key to ImageBuilder:

   ```bash
   KEY_ID="$(./staging_dir/host/bin/usign -F \
     -p /tmp/thousandeyes-openwrt-feed.pub)"
   mkdir -p keys
   install -m 0644 /tmp/thousandeyes-openwrt-feed.pub "keys/$KEY_ID"
   ```
8. Set the local feed name, remove any existing entry with the same name, and register the selected family feed:

   ```bash
   FEED_NAME="thousandeyes_cdev"
   sed -i "/^[[:space:]]*src\/gz[[:space:]][[:space:]]*$FEED_NAME[[:space:]]/d" \
     repositories.conf
   echo "src/gz $FEED_NAME https://downloads.thousandeyes.com/te-cdev-agent/openwrt/$FAMILY" \
     >> repositories.conf
   ```

   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.

## 2. Preparing the Agent Configuration

1. Create `skagent.cfg` in your preferred text or code editor using the OpenWrt configuration below.

   Save it outside the signed IPK. Do not unpack or modify the 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.

Do not compile a production authentication secret into downloadable firmware. Inject it at first boot using the platform's ACS or secret provider.

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.

See the [Configuration Reference](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/configuration-reference.md) for individual fields and its [cross-traffic detection](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/configuration-reference.md#cross-traffic-detection) guidance for devices with more than one WAN counter.

2. Copy the completed configuration into the ImageBuilder root-filesystem overlay.

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

   The `FILES` overlay replaces the packaged placeholder in the generated image. The signed IPK remains unchanged.

## 3. Building the Image

1. Build the image with the selected package and completed overlay:

   ```bash
   make image PROFILE="<profile>" PACKAGES="$PACKAGE" FILES="$PWD/files"
   ```

   The package architecture checker rejects an incompatible target. Do not bypass that check.
2. Flash the generated image to a representative lab device before continuing.

## 4. Adding 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 `procd` to restart the Updater after a failure and keep one instance running. The Updater supervises the agent.
   {% endtab %}

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

1. Run the packaged compatibility helper to start the agent:

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

2. Configure `procd` 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 survive the intended `sysupgrade` path.

## 5. Validating 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:
4. After self-test, restart the normal service.

   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.

## 6. Managing Subsequent Package Updates

When the firmware image controls the IPK version, rebuild and deploy the image with the current package from the unchanged signed feed. This keeps the package version aligned with the firmware manifest and rollback path.

Use a targeted `opkg upgrade <package-name>` only when the product is designed to manage this package independently in writable storage. Provision the signing key and selected feed on the device. Before using this model, 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 %}
