> 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/configuration/opensync.md).

# OpenSync

Use the OpenSync template to configure an embedded Linux integration that exposes the OpenSync platform APIs.

Choose and complete the applicable [Generic Linux](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides/generic-linux.md), [OpenWrt](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides/openwrt.md), or [RDK-B](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/production-integration-guides/rdk-b.md) installation route first. When that guide reaches **Configure the Agent**, return to this article.

## Using the OpenSync Configuration

1. Prepare the supplied configuration file for your package type.
   * For an Agent Updater package, copy the supplied OpenSync configuration to the runtime filename:

     ```bash
     cd opt/thousandeyes/cdev/router_agent_updater/etc
     cp skagent.opensync.cfg skagent.cfg
     ```
   * For an agent-only package, update the supplied `etc/skagent.cfg` file in the agent tree.
2. Replace every `CHANGE ME` value before adding the configuration to the image.

   In the supplied OpenSync configuration, set the stable WAN interface under `[identity.mac]` and replace the authentication secret. Keep the OpenSync lookups for model, firmware, serial number, active uplink, and production client routing unless the target platform requires a different input.

   The OpenSync configuration reads model, serial number, firmware, and uplink information from the platform. These values describe the device and its uplink; they do not identify the customer or authenticate the agent.
3. Confirm the resolved values on the target.

| Field                   | OpenSync template                | You supply or confirm                                                                                                     |
| ----------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Model                   | `ovsh_awlan_node`                | Confirm the result                                                                                                        |
| Serial number           | `ovsh_awlan_node`                | Confirm the result                                                                                                        |
| Firmware                | `ovsh_awlan_node`                | Recheck after firmware changes                                                                                            |
| Cross-traffic interface | `ovsh_connection_manager_uplink` | Confirm after startup and failover                                                                                        |
| MAC                     | Interface input                  | Set the stable WAN interface and verify its MAC                                                                           |
| Client                  | `plume_lookup_api`               | Use the Org Client ID when testing a production image in the lab; otherwise confirm the emitted label and backend mapping |
| Authentication secret   | Not supplied                     | Inject it securely                                                                                                        |

Current Agent Updater packages include the OpenSync template for armv7a and arm64. Confirm that ThousandEyes supplies a matching agent-only target before choosing agent-only for an OpenSync integration.

## Setting the MAC

1. Find the interface carrying the default route:

   ```bash
   ip route show default
   ```

   The interface name follows `dev`.
2. Replace `eth0` below with that name, then read its MAC address:

   ```bash
   cat /sys/class/net/eth0/address
   ```

Use the MAC printed on the device label when the runtime interface address is not the stable customer identifier.

## Setting Client Routing and Authentication

When testing a production image in the lab, use your Org Client ID so the agent is visible in your organization:

```toml
[identity]
client='<your-org-client-id>'

[authentication]
secret='<your-authentication-secret>'
```

Otherwise, use the OpenSync platform lookup to provide the stable ISP or customer label agreed with ThousandEyes:

```toml
[identity.client]
input='plume_lookup_api'

[authentication]
secret='YOUR-PRODUCTION-AUTHENTICATION-SECRET'
```

Tell ThousandEyes the exact label emitted by the platform before rollout. A label does not route devices until the backend mapping exists.

{% hint style="warning" %}
Do not compile a production secret into firmware. Inject it at first boot through your ACS or secret provider.
{% endhint %}

## Starting After the Uplink Is Ready

Wait for the platform's uplink-ready state, not merely for an interface to exist. Starting earlier can resolve the wrong cross-traffic interface while activation still succeeds.

On a device with failover, confirm the resolved interface again after failover.

## Verifying

If the integration uses the Updater, follow its log:

```bash
tail -n 100 -f /var/run/opt/thousandeyes/cdev/router_agent_updater/updater_log
```

If the log repeatedly reports that it is polling for platform sockets, wait before continuing. Continue after activation issues a Unit ID, the agent package is downloaded and verified, and the log reports `Service started`. Resolve any logged error before running `--device-info` or the agent in self-test mode.

For agent-only integrations, skip the Updater log check.

1. Run the device information check from the agent installation directory:

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

```bash
cd /tmp/cdev/installation
bin/skagent --device-info
```

{% endtab %}

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

```bash
cd /opt/samknows/router_agent
bin/skagent --device-info
```

{% endtab %}
{% endtabs %}

2. Check the model, serial number, firmware, MAC, client, and cross-traffic interface. Then [validate with self-test mode](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/validate-with-self-test-mode.md).
