> 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/generic-linux.md).

# Generic Linux

Use this guide to integrate the agent when the device runs Linux and the other production integration guides do not apply.

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

The instructions in this guide 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 you build the package, continue with **Prepare the Agent Configuration**. Then add the package and configuration to your firmware build.

## 1. Prepare the Package

{% tabs %}
{% tab title="Agent Updater" %}
Verify the Cisco CMS signature before adding the TAR archive to the image build.

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

Extract the Agent Updater archive from the verified outer package:

```bash
tar -xzf cdev_agent_updater-*.tar.gz
```

Keep the extracted package tree on the preparation computer until you complete Step 2.
{% endtab %}

{% tab title="Agent-only" %}
Use the agent archive that matches the target platform and architecture:

```
sk_router_agent-<version>-<platform>.tar.gz
sk_router_agent-<version>-<platform>.tar.gz.signature
```

Verify the detached Cisco CMS signature before adding the archive to the image build.

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

Extract the archive. The archive contains the agent filesystem tree in a `release_dir` folder, as well as documentation and service examples.

Example `systemd`, `SysV`, and `procd` service definitions are in `init_examples`.

If you choose another persistent installation root, update the configuration, service working directory, and validation commands to match.
{% endtab %}
{% endtabs %}

## 2. Prepare the Agent Configuration

1. Because Generic Linux does not provide a platform data model to identify devices automatically, choose a stable source for each configuration field:

   | Field                    | Recommended source                                         |
   | ------------------------ | ---------------------------------------------------------- |
   | `base` (model or SKU)    | Stable literal, file, or command                           |
   | Client                   | See the production-client guidance below                   |
   | MAC                      | Stable WAN MAC from the device platform or physical label  |
   | Serial number            | Stable file or command                                     |
   | Firmware                 | Running-version file or command                            |
   | Cross-traffic interfaces | Default route or explicit WAN interfaces                   |
   | Authentication secret    | Provisioning process that injects the secret at first boot |

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. On the preparation computer, complete the supplied **skagent.cfg** in the extracted package tree:

Do not compile a production secret into downloadable firmware. Test file and command inputs during early boot, not only after the device is fully online.

For input examples, see [Identity and ISP Routing](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md#1-firmware-identifies-the-isp). For field details, see [Configuration Reference](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/configuration-reference.md).

An [OpenSync template](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/opensync.md) is available when the platform uses OpenSync.

## 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 standard working directory is `/tmp/cdev`, 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. Add Startup and Persistence

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

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

1. Use the supplied `systemd`, `SysV`, or `procd` example as the starting point for the platform service.

   The service starts:

   ```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 to keep one Updater instance running. The Updater supervises the agent.
   {% endtab %}

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

1. Use the applicable service example from `init_examples`.

   Set `/opt/samknows/router_agent` as the service working directory and start:

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

2. Configure the process manager to restart the agent after an unexpected exit. Stop the agent cleanly before you replace the package, and 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, DNS resolution, outbound HTTPS access, and correct time.

## 5. Validate the Integration

1. Check the values resolved by the configuration.
2. Confirm that the reported MAC address, model, firmware, client, serial number, and WAN interfaces are correct 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.

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