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

# Configuration Reference

Use this page to look up `skagent.cfg` fields and input formats. For decisions about customer identity and routing, use [Identity and ISP Routing](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md).

## Verifying the Current Configuration

Run this command from the agent installation directory:

```bash
bin/skagent --device-info
```

Check the resolved MAC, model, client, firmware, serial number, and WAN interfaces. If a field is empty or changes after a reboot, choose a different input source.

## Field Index

| Field                                               | Purpose                                     | Requirement                                                                                                                                                               |
| --------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authentication.secret` or `authentication.command` | agent authentication                        | Required                                                                                                                                                                  |
| `identity.client`                                   | Organization and ISP routing                | Required                                                                                                                                                                  |
| `identity.mac`                                      | Stable device identity                      | Required                                                                                                                                                                  |
| `identity.base`                                     | Model or SKU                                | Required                                                                                                                                                                  |
| `logging`                                           | Global log level                            | Optional. Defaults to `stdout` and `rotating_file` sinks.                                                                                                                 |
| `logging.sinks`                                     | Log destinations and sink-specific settings | Optional. Defaults to `stdout` and `rotating_file` when unset. An empty array disables log output.                                                                        |
| `metadata.Firmware`                                 | Running firmware                            | Required if the agent does not supply firmware internally. Otherwise, recommended.                                                                                        |
| `metadata.SerialNumber`                             | Inventory                                   | Optional                                                                                                                                                                  |
| `measurements.speed_tests.hook`                     | Configure HTTP speed-test hooks             | Optional. See [Speed-Test Hook Reference](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/speed-test-hook-reference.md) |
| `resource_checker.cross-traffic`                    | Detect traffic on the WAN                   | Required for reliable scheduling with cross-traffic detection                                                                                                             |
| `resource_checker.cross-traffic-check`              | Enable or disable cross-traffic checks      | Optional; defaults to `true`                                                                                                                                              |
| `updater.cdev_package.working_directory`            | agent runtime location used by the Updater  | Current packaged templates use `/tmp/cdev`                                                                                                                                |
| `ubus.socket`                                       | Native `ubus` socket override               | Only for native `ubus` input                                                                                                                                              |

## Common Input Types

| Input               | Reads               | Common use                                  |
| ------------------- | ------------------- | ------------------------------------------- |
| `string` or literal | Configuration value | Any field                                   |
| `file`              | File contents       | Identity and metadata                       |
| `program`           | Command output      | Identity, metadata, and interface selection |
| `network_interface` | Interface MAC       | MAC only                                    |
| `default route`     | Routing table       | Cross-traffic interfaces only               |

## Authentication Secret

**Purpose:** authenticates the agent when it registers.

**Requirement:** The secret is always required. ThousandEyes can supply separate authentication secrets for lab and production use. Do not compile a production secret into downloadable firmware.

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

The agent can instead retrieve the secret from a program:

```toml
[authentication]
command=['/usr/bin/get-agent-secret']
```

Use either `secret` or `command`, not both. Restrict access to a configuration file containing a secret with mode `0600`.

## Client

**Purpose:** routes the device to the correct ThousandEyes organization.

**Requirement:** when testing a production image in the lab, use the assigned Org Client ID so the agent is visible in your organization. Otherwise, use the stable ISP or customer label agreed with ThousandEyes before rollout.

**Accepted inputs:** literal, `file`, `program`, and supported platform data-model inputs as listed below.

| Platform      | Typical production input                 |
| ------------- | ---------------------------------------- |
| RDK-B         | `dmcli_get`                              |
| OpenSync      | `plume_lookup_api`                       |
| OpenWrt       | File, program, or supported `ubus` value |
| Generic Linux | Stable file or program                   |

```toml
[identity.client]
input='file'
path='/etc/sysconfig/isp'
```

The label must already have a backend mapping. See [Identity and ISP Routing](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md) for direct routing, mapped routing, and lab-to-production guidance.

## MAC

**Purpose:** provides the stable device identifier used by ThousandEyes.

**Requirement:** resolve the real WAN MAC and compare it with the device label.

**Accepted inputs:** literal, `file`, `program`, `network_interface`, `dmcli_get`, or `ubus` on agent v7.14 or later. `default route` is not valid for MAC.

**Accepted values:** MAC values can use colons, dashes, or no separator. Case does not matter.

```toml
[identity.mac]
input='network_interface'
interface='eth0'
offset=0
```

Use `offset` only when the WAN interface MAC consistently differs from the label MAC by a fixed amount. The value is the label MAC minus the interface MAC. Negative values are accepted.

When the WAN can move between physical ports, publish the active WAN MAC to a stable file after the platform selects the port:

```toml
[identity.mac]
input='file'
path='/tmp/device_mac'
```

## Base

**Purpose:** records the model or SKU and can be used to select the compatible agent build when the Updater retrieves one.

**Requirement:** use a stable product identifier.

Changing this value does not update the registered base of an existing Unit ID. See [Identity and ISP Routing](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/configuration/identity-and-isp-routing.md#first-registration).

**Accepted inputs:** literal and platform data-model inputs. `file` and `program` require agent v7.13 or later; `ubus` requires v7.14 or later. On an older agent, set a literal.

**Accepted values:** 1–20 characters, using lowercase letters, digits, `-`, `_`, or `+`.

```toml
[identity.base]
input='program'
command=['/usr/bin/device-model']
```

## Firmware

**Purpose:** records the running firmware for inventory and troubleshooting.

**Requirement:** Required if the agent does not supply firmware internally. Otherwise, this field is recommended. Recheck it after firmware changes.

**Accepted inputs:** literal, `file`, `program`, `dmcli_get`, or `ubus` on agent v7.14 or later.

| Platform      | Example source                                    |
| ------------- | ------------------------------------------------- |
| RDK-B         | Data model or stable version file                 |
| OpenSync      | Platform API                                      |
| OpenWrt       | Stable file or a program that reads the UCI value |
| Generic Linux | Stable file or program                            |

```toml
[metadata.Firmware]
input='file'
path='/etc/firmwareversion'
```

Use the applicable platform integration guide for platform-specific examples. Confirm the source on the target and recheck it after a firmware update.

## Serial Number

**Purpose:** adds an inventory identifier.

**Requirement:** optional. Use a stable platform value when available.

**Accepted inputs:** literal, `file`, `program`, `dmcli_get`, or `ubus` on agent v7.14 or later.

```toml
[metadata.SerialNumber]
input='file'
path='/etc/device-serial'
```

## Cross-Traffic Detection

**Purpose:** pauses scheduled measurements while customer traffic is using the WAN over the set threshold. See [Testing thresholds](https://docs.thousandeyes.com/product-documentation/connected-devices/test-management/testing-thresholds).

**Requirement:** monitor every interface that carries WAN bytes.

Use the default route when it represents the full WAN path:

```toml
[resource_checker.cross-traffic]
input='/sys/class/net bytes'

[resource_checker.cross-traffic.interfaces]
input='default route'
```

`default route` checks the current IPv4 and IPv6 default-route interfaces. If both routes use the same interface, the agent monitors it once.

Name interfaces explicitly when counters are split across more than one independent traffic path, such as a hardware-accelerated path:

```toml
[resource_checker.cross-traffic]
input='/sys/class/net bytes'
interfaces=['eth0', 'eth0.accel']
```

If the device has a cellular backup unit, include both primary and backup WAN interfaces when each has independent traffic counters:

```toml
[resource_checker.cross-traffic]
input='/sys/class/net bytes'
interfaces=['eth0', 'wwan0']
```

Replace `wwan0` with the actual cellular WAN interface. Test with each connection active and confirm that only the corresponding counters increase.

All selected counters are added together. Do not include logical and physical interfaces that count the same traffic, because the agent would count the traffic twice. Use either an inline `interfaces` list or the separate interfaces table used by `default route`, `program` or OpenSync. Do not configure both forms.

### Finding and Checking the WAN Interface

Identify the interface carrying the default route:

```bash
ip route show default
```

In output such as `default via 192.168.2.1 dev eth0`, the interface is the name after `dev`. Replace `eth0` below with that interface and read both counters:

```bash
cat /sys/class/net/eth0/statistics/rx_bytes
cat /sys/class/net/eth0/statistics/tx_bytes
```

Both commands should return integers that increase as traffic crosses the WAN. `No such file` means the interface name is wrong.

### Containers

Cross-traffic detection works when the container shares the host network namespace because the agent reads sysfs counters. Use `--network=host` with Docker. Docker Desktop exposes the virtual machine's counters rather than the PC's network interfaces, so it cannot validate cross-traffic detection for the PC or target device.

### Disabling Cross-Traffic Checks

Cross-traffic checks are enabled by default. If the device cannot provide reliable WAN counters, disable them in `skagent.cfg`:

```toml
[resource_checker]
cross-traffic-check=false
```

When disabled, the agent ignores configured `[resource_checker.cross-traffic]` settings.

### Verifying the Counters

Self-test mode reads the WAN counters, runs a controlled download, reads them again and compares the increase with the bytes downloaded. A pass confirms the counters used by the active WAN path during that run. Repeat the check after failover or a change in acceleration state when those paths use different counters.

A failure such as `bgtrafmon RX delta outside expected range` usually means that the agent is watching the wrong interface. Correct the configuration and run the agent in self-test mode again.

## Working Directory

**Purpose:** sets the directory in which the Updater installs the agent.

Current packaged templates use:

```toml
[updater.cdev_package]
working_directory='/tmp/cdev'
```

The resulting agent directory is `/tmp/cdev/installation`. A custom integration might use another writable and executable location. Create and test the selected directory before the Updater starts.

## Logging

The logging table is optional. If you do not define it, the agent logs information to both standard output (`stdout`) and a rotating file.

### Global Logging Configuration

Set the global log level with the `level` parameter. It accepts the following values, which correspond to the `spdlog` logging library levels:

* `trace`
* `debug`
* `info`
* `warn`
* `err`
* `critical`

### Logging Sinks

The `logging.sinks` array lets you define multiple logging destinations with specific levels and parameters.

* **Default behavior:** If you do not set `logging.sinks`, the agent creates one `stdout` sink and one `rotating_file` sink with default settings.
* **Disabling logs:** Set `logging.sinks` to an empty array to disable log output.

#### Sink Parameters

Configure the following options for all logging sinks:

* **level:** A sink-specific mask that filters messages by priority. If you do not specify a level, the agent defaults to `trace` and outputs all messages.
* **pattern:** A sink-specific format for output lines that uses the pattern flags from the `spdlog` C++ library. If you do not specify a pattern, the agent uses a default pattern.

#### Sink Types

The agent supports the following sink types:

* **stdout:** Sends logs to standard output. This type requires no additional parameters.
* **rotating\_file:** Sends logs to a file and appends a sequence number to the filename. Configure these parameters:
  * **path:** The file path for logs.
  * **max\_size:** The maximum size of each log file.
  * **max\_count:** The maximum number of log files to retain.

### Configuration Examples

#### Configuring Different Levels and Patterns

This example sets a global debug level and applies specific configurations for the standard output and file sinks.

```toml
[logging]
level=debug

[[logging.sinks]]
type="stdout"
level="err"
pattern="[%l] [%n] [%t] %v"

[[logging.sinks]]
type="rotating_file"
level="debug"
pattern="[%Y-%m-%d %H:%M:%S.%e] [%l] [%n] [%t] %v"
max_size=65536
max_count=4
```

#### Logging to Standard Output Only

To restrict logging to standard output, configure the sinks array as follows:

```toml
[logging]
level=debug

[[logging.sinks]]
type="stdout"
level="trace"
pattern="[%l] [%n] [%t] %v"
```

## `ubus` Input

**Purpose:** reads identity, metadata, or interface values from the OpenWrt or prpl data model.

**Requirement:** agent v7.14 or later. Confirm each vendor-specific data model path.

The standard prpl container uses the bind-mounted socket at `/root/host/ubus/ubus.sock`. A native OpenWrt install sets the real socket:

```toml
[ubus]
socket='/var/run/ubus/ubus.sock'

[identity.base]
input='ubus'
ubus_get='DeviceInfo.ModelName'

[metadata.Firmware]
input='ubus'
ubus_get='DeviceInfo.SoftwareVersion'
```

You can also apply `case` and `format` transforms to values returned by `ubus`.

## Value Transforms

`format`, `regex`, and `case` transforms are supported for identity and metadata values that use `file`, `program`, or `ubus`. Some platform-specific inputs support only `case`, as shown below. Ordinary configuration fields do not support these transforms.

The available transforms are:

* `format` - Builds a value using placeholders such as `{0}` and `{1}`. This is useful when combining multiple values.
* `regex` - Extracts or replaces text.
* `case` - Converts the result to `lower` or `upper`.

Transforms are applied in this order: format → regex → case.

For example:

```toml
[identity.base]
input = "ubus"
ubus_get = ["DeviceInfo.Manufacturer", "DeviceInfo.ModelName"]
format = "{0}-{1}"
case = "lower"
```

Field-level support:

| Configuration field | Full support: `format`, `regex`, and `case` | Case only                                                                          |
| ------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------- |
| `identity.base`     | `file`, `program`, or `ubus`                | `ovsh_awlan_node` (OpenSync), `dmcli_get` (RDK-B)                                  |
| `identity.client`   | `file`, `program`, or `ubus`                | `as_number`, `plume_lookup_api` (OpenSync), `dmcli_get` (RDK-B), `linksys-generic` |
| `identity.mac`      | `file`, `program`, or `ubus`                | `network_interface`, `dmcli_get` (RDK-B), `linksys-generic`                        |
| `metadata.<name>`   | `file`, `program`, or `ubus`                | `ovsh_awlan_node` (OpenSync), `dmcli_get` (RDK-B)                                  |

For `identity.base`, `case` accepts only `lower`. For all other listed fields, `case` accepts `lower` or `upper`.

When `ubus_get` contains multiple paths, `format` is required and uses placeholders such as `{0}` and `{1}`.
