For the complete documentation index, see llms.txt. This page is also available as Markdown.

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, then choose the Agent Updater or agent-only model in Plan, Deploy, and Update the Agent. 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:

    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.

    The latest agent-only arm64 feed is:

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

    If ThousandEyes asks you to pin another version, see Connected Devices Agent Release Versions and 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/

  2. Download the package index and its signature:

    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:

    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:

    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:

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

    ./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:

    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:

    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:

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:

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.

Add the Updater working directory:

The Agent-only configuration does not require an [updater.cdev_package] table.

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

  • 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 instead of reproducing it here.

See the Configuration Reference for individual fields and its cross-traffic detection guidance for devices with more than one WAN counter.

  1. 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:

    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.

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

  2. Configure procd to restart the Updater after a failure and keep one instance running. The Updater supervises the agent.

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

  2. Configure procd to restart the agent after an unexpected exit and stop it cleanly before replacing the package. Keep one agent instance running.

  1. 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.

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

  1. Run the device-info command:

  1. Confirm the model, client, WAN MAC, serial number, firmware, and WAN interface before and after a cold boot.

  2. Run the agent in self-test mode by following the instructions for your selected agent model:

  3. 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 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.

After the integration passes, use Plan, Deploy, and Update the Agent for device QA, rollout, and updates.

Last updated