For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Verifying the Current Configuration

Run this command from the agent installation directory:

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

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.

The agent can instead retrieve the secret from a program:

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

The label must already have a backend mapping. See Identity and ISP Routing 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.

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:

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.

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 +.

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

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.

Cross-Traffic Detection

Purpose: pauses scheduled measurements while customer traffic is using the WAN over the set threshold. See Testing thresholds.

Requirement: monitor every interface that carries WAN bytes.

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

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:

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

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:

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:

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:

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:

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.

Logging to Standard Output Only

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

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:

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:

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

Last updated