> 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/native-tar.md).

# OpenWrt Native TAR Archive

Use this guide when you place the Agent Updater or agent tree directly into an OpenWrt firmware image.

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. Prepare the Package

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

1. Verify the Cisco CMS signature before using the TAR archive as an image-build input.

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
   ```
7. Extract the Agent Updater archive from the verified outer package:

   ```bash
   tar -xzf cdev_agent_updater-*.tar.gz
   ```
8. Keep the extracted tree on the preparation computer until you complete the agent configuration.
   {% endtab %}

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

1. Use the agent archive built for the target device’s platform and architecture:

   ```
   sk_router_agent-<version>-<platform>.tar.gz
   sk_router_agent-<version>-<platform>.tar.gz.signature
   ```
2. Verify the detached Cisco CMS signature before using the archive as an image-build input.

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
   ```
7. Extract the archive.

   It contains a `release_dir` folder with the agent filesystem tree, alongside its documentation and service examples.

   The archive also contains an example `procd` service definition under `init_examples`.
   {% endtab %}
   {% endtabs %}

## 2. Prepare the Agent Configuration

1. On the preparation computer, update the `skagent.cfg` file supplied with the selected TAR archive using the OpenWrt configuration below.

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.

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.

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

2. Store the completed configuration in the extracted package tree at the path for your selected update model:
3. Keep the runtime configuration at mode `0600` because it contains the authentication secret. This protects the file on the device. It does not make embedding a production secret in downloadable firmware acceptable.

## 3. Add the Package and Configuration to the Firmware Build

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

1. Overlay the extracted `opt` directory onto the image root.

   This adds the Updater and its completed configuration at:

   ```
   /opt/thousandeyes/cdev/router_agent_updater
   ```

   Keep `skagent.cfg` with the persistent Updater package. The configuration uses `/tmp/cdev` as the working directory, so the Updater installs the agent at `/tmp/cdev/installation`.
   {% endtab %}

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

1. Overlay the contents of `release_dir` onto the image root.

   This adds the agent and its completed configuration at:

   ```
   /opt/samknows/router_agent
   ```

{% endtab %}
{% endtabs %}

2. Confirm that the completed `skagent.cfg` is present in the final image at the path shown above.

## 4. Add Startup and Persistence

Use the supplied `procd` example to configure the platform service. Start the selected component only after the target has a usable WAN route, DNS resolution, outbound HTTPS access, and the correct time. Do not rely only on a fixed `START` priority.

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

1. Start the Updater with:

   ```bash
   exec /opt/thousandeyes/cdev/router_agent_updater/bin/router_agent_updater
   ```
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. Set `/opt/samknows/router_agent` as the working directory, then start the agent with:

   ```bash
   cd /opt/samknows/router_agent
   exec bin/skagent
   ```

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 default route still matches the configured cross-traffic interface.

## 5. Validate the Integration

Check the identity and metadata that the configuration resolves.

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

1. After the Updater installs the agent:

   ```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. Use the matching validation instructions:

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

{% 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 %}
