> 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/rdk-b.md).

# RDK-B

Use this guide to integrate the agent into an RDK-B device.

Confirm that your device meets the [System Requirements](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/getting-started/system-requirements.md). 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), then use the matching tab throughout this guide.

The instructions below use the native TAR archive.

If your platform requires an IPK package, see [Build an IPK from the TAR Archive](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides/appendix-build-an-ipk-from-the-tar-archive.md). After building the package, continue with **Preparing the Agent Configuration** and add the package and configuration to the firmware build in Step 3.

## 1. Preparing 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. Use the supplied `skagent.rdkb.cfg` file and copy it to the runtime filename:

   ```bash
   cd opt/thousandeyes/cdev/router_agent_updater/etc
   cp skagent.rdkb.cfg skagent.cfg
   ```

   Complete the copied `skagent.cfg` in Step 2. Keep the extracted tree on the preparation computer until the configuration is complete.
   {% endtab %}

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

1. Select the archive for the target platform and CPU architecture. Use the signature file with the same `<version>` and `<platform>` values:

   ```
   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.
8. Use the supplied `skagent.rdkb.cfg` file and copy it to the runtime filename:

   ```bash
   cd release_dir/opt/samknows/router_agent/etc
   cp skagent.rdkb.cfg skagent.cfg
   ```

   Complete the copied `skagent.cfg` in Step 2. Keep the extracted tree on the preparation computer until the configuration is complete.

The archive also contains example `systemd`, SysV, and `procd` service definitions under `init_examples`.
{% endtab %}
{% endtabs %}

## 2. Preparing the Agent Configuration

1. Run these `dmcli` commands on the target to verify that the supplied RDK-B configuration returns the expected device identity and metadata before you finalize the production image:

   ```bash
   dmcli eRT getv Device.DeviceInfo.ModelName
   dmcli eRT getv Device.DeviceInfo.Manufacturer
   dmcli eRT getv Device.DeviceInfo.X_RDKCENTRAL-COM_Syndication.PartnerId
   dmcli eRT getv Device.DeviceInfo.X_COMCAST-COM_WAN_MAC
   dmcli eRT getv Device.DeviceInfo.SerialNumber
   ```
2. Confirm that the firmware version file returns the expected value:

   ```bash
   cat /version.txt
   ```
3. Confirm the WAN interface separately:

   ```bash
   ip route show default
   ```

   The interface name after `dev` in the output must match the configured cross-traffic interface. `erouter0` is common on RDK-B, but do not assume that the device uses it.
4. On the preparation computer, open the `skagent.cfg` prepared in Step 1:
5. Replace every `CHANGE ME` value, including the authentication secret.

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.

For the RDK-B production image, keep the supplied `dmcli_get` lookup and confirm that `Device.DeviceInfo.X_RDKCENTRAL-COM_Syndication.PartnerId` returns the ISP or customer label agreed with ThousandEyes. If your RDK-B data model uses a different parameter, update `client_name_parameter`.

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 [Identity and ISP Routing](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md) for the routing model and [Configuration Reference](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/configuration-reference.md) for individual fields.

## 3. Adding 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
   ```

   The supplied `skagent.rdkb.cfg` file uses `/tmp/cdev` as its working directory, so the Updater downloads the agent to `/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. Adding Startup and Persistence

Start the selected component only after RDK-B WAN provisioning provides a usable route, DNS resolution, outbound HTTPS access, and the correct time. If you rely only on `network-online.target`, the service might start before platform WAN provisioning is complete.

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

1. Use the supplied `systemd` example to configure the platform service.

   Start the Updater with:

   ```bash
   exec /opt/thousandeyes/cdev/router_agent_updater/bin/router_agent_updater
   ```
2. Configure the 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. Configure the service using the applicable example in `init_examples`. Set `/opt/samknows/router_agent` as the working directory, then start the agent:

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

2. Configure the 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. After a complete power cycle, verify that the service starts only after WAN provisioning and that the configured cross-traffic interface still carries the default route.

## 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, vendor, 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. After self-test, restart the normal service.

   Confirm that the Unit ID remains stable after another cold boot.

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