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-infoCheck 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
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
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.
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.
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:
tracedebuginfowarnerrcritical
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 onestdoutsink and onerotating_filesink with default settings.Disabling logs: Set
logging.sinksto 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
traceand outputs all messages.pattern: A sink-specific format for output lines that uses the pattern flags from the
spdlogC++ 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 tolowerorupper.
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