> 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/appendix-build-an-ipk-from-the-tar-archive.md).

# Appendix: Build an IPK from the TAR Archive

Use this appendix when an `opkg`-based platform requires a customer-built IPK and cannot use the published [OpenWrt IPK](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides/openwrt/openwrt-ipk.md) unchanged. For a standard OpenWrt integration, retrieve the published IPK instead of rebuilding it from the TAR archive.

ThousandEyes publishes supported OpenWrt IPKs through the signed feed. Use this appendix only when the target package layout, architecture, or integration requires you to own a different IPK. Verify the supplied TAR archive before extracting it, then build, sign, and distribute the customer-owned IPK through your package system.

{% hint style="warning" %}
A customer-built IPK does not retain the source archive's integrity chain. Verify the source using the supplied method before extracting it, then sign the IPK or package index using your normal release process.
{% endhint %}

## Before You Start

You need:

* An agent TAR archive.
* `opkg-build`, normally supplied by `opkg-utils` or a matching OpenWrt SDK, on the build host.
* The architecture reported by `opkg print-architecture` on the target.
* A decision to package the Agent Updater or agent-only.

Build the package on your build host. Do not build it on a target device.

## 1. Verifying and Extracting the Source Archive

{% tabs %}
{% tab title="Agent Updater" %}
Use the Agent Updater TAR archive and the detached signature supplied with that exact package.

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

{% endtab %}

{% tab title="Agent-only" %}
Use the agent archive and detached signature supplied for the selected platform and architecture:

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

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

{% endtab %}
{% endtabs %}

## 2. Creating the Package Tree

1. Create the package root:

   ```bash
   mkdir -p pkgroot/CONTROL pkgroot/etc/init.d
   ```

{% tabs %}
{% tab title="Agent Updater" %}
2\)  Extract the Agent Updater archive from the verified outer package. Then copy the Updater tree and adapt the supplied init example:

````
```bash
tar -xzf cdev_agent_updater-*.tar.gz
cp -a opt pkgroot/
cp init_examples/procd/thousandeyes_cdev \
  pkgroot/etc/init.d/te-cdev-agent-updater
```

The default configuration path in this package layout is:

```
/opt/thousandeyes/cdev/router_agent_updater/etc/skagent.cfg
```

Do not add the agent binary to the same package. The Updater retrieves and verifies approved agent releases at runtime.
````

{% endtab %}

{% tab title="Agent-only" %}
2\.  After the verification step extracts the agent archive, copy its filesystem tree into `pkgroot/` and adapt the supplied `procd` example:

````
```bash
cp -a release_dir/. pkgroot/
cp init_examples/procd/samknows \
  pkgroot/etc/init.d/te-cdev-agent
```

The delivered agent tree is installed at `/opt/samknows/router_agent`.
````

{% endtab %}
{% endtabs %}

3. If your platform reads configuration from `/etc`, place the configuration file there and use a symlink or package-owned path that matches the platform page.

## 3. Adding Package Metadata

1. Create `pkgroot/CONTROL/control` and update the following fields as needed:
2. Mark the configuration as an `opkg` conffile so a locally updated file is preserved during package upgrades:

   If you relocate the configuration, record its installed path in `CONTROL/conffiles` instead.
3. Set the following fields:

   * `Version` to the component version plus your packaging revision.
   * `Architecture` to the compatible value reported by `opkg print-architecture`.
   * `Depends` only when the final package or startup integration requires a target package that is not already delivered in the verified component tree.

   Do not list libraries already supplied in the component tree. The `openssl` command used to verify the source archive runs on the build host and is not a target package dependency by itself.

   Do not use `Architecture: all` unless the package performs its own compatibility check.

## 4. Building and Inspecting the IPK

1. Build the IPK:

   ```bash
   opkg-build -o root -g root pkgroot .
   ```
2. Inspect the data archive before installing it:

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

```bash
ar -p te-cdev-agent-updater_*.ipk data.tar.gz | tar -tzf - | head
```

{% endtab %}

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

```bash
ar -p te-cdev-agent_*.ipk data.tar.gz | tar -tzf - | head
```

{% endtab %}
{% endtabs %}

3. Install the IPK on a lab device and confirm that the package paths match the configuration and startup unit.

## 5. Configuring Startup

1. Use the example in `init_examples/` for the platform's init system: `procd`, `systemd`, or SysV.
2. Start the component only after WAN connectivity, DNS resolution, and outbound HTTPS access are available.

For example, on an OpenWrt-derived platform:

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

```bash
/etc/init.d/te-cdev-agent-updater enable
/etc/init.d/te-cdev-agent-updater start
```

{% endtab %}

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

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

Run the agent through your platform's packaged init integration. The integration must set the persistent agent directory as its working directory and supervise the process.
{% endtab %}
{% endtabs %}

Installing the IPK should not silently enable or start the service. Express startup ordering in the image or provisioning configuration where it can be reviewed.

## Adding the Configuration Without the Authentication Secret

Add the remaining configuration during the build, or supply it through the target's provisioning process. Do not include the production authentication secret in distributable firmware or packages. Inject it at first boot from your ACS or secret provider.

For a lab package, you can edit the installed configuration and restart the service:

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

```bash
opkg install ./te-cdev-agent-updater_*.ipk
vi /opt/thousandeyes/cdev/router_agent_updater/etc/skagent.cfg
/etc/init.d/te-cdev-agent-updater restart
```

{% endtab %}

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

```bash
opkg install ./te-cdev-agent_*.ipk
vi /opt/samknows/router_agent/etc/skagent.cfg
# Restart the Agent through your packaged init integration.
```

{% endtab %}
{% endtabs %}

See [Identity and ISP Routing](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md).

## Signing and Publishing

Sign the output through your existing package process. If you publish an `opkg` feed, sign its index and publish the package checksum. If the IPK is embedded in an image, use the image build's package-signing controls.

For each update:

1. Verify the new TAR archive.
2. Rebuild the IPK.
3. Sign and publish it.
4. Validate installation with [Validate with Self-Test Mode](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/validate-with-self-test-mode.md) on a lab device.

For OpenWrt, use the published [OpenWrt IPK](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides/openwrt/openwrt-ipk.md) or let [OpenWrt feed and ImageBuilder](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides/openwrt/openwrt-feed-and-imagebuilder.md) resolve it directly.

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 production validation, rollout, and update ownership.
