> 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/validation-and-troubleshooting/validate-with-self-test-mode.md).

# Validate with Self-Test Mode

A passing self-test confirms the speeds a device can expect to measure with its default configuration. It also verifies that the agent can read the device configuration, activate, retrieve its schedule, run the available tests, and inspect the configured cross-traffic counters.

Starting with agent v7.14, self-test mode can replace the equivalent manual QA sequence. You still need to check physical cables and reboot the device.

Agent v7.16 or later is required for the final summary, ICMP ping, UDP speed, and target-override behavior.

## Running Self-Test

Use the instructions for the selected update model:

{% tabs %}
{% tab title="Agent Updater" %}
Stop the Updater before you run self-test mode. If it runs in the current terminal, press `Ctrl+C`. If you started it directly with `-D`, stop it by running:

```bash
/opt/thousandeyes/cdev/router_agent_updater/bin/router_agent_updater -K
```

If the integration starts the Updater as a managed service, stop that service first.

**Agent Updater v7.16 or later**

Run self-test mode through the Updater:

```bash
/opt/thousandeyes/cdev/router_agent_updater/bin/router_agent_updater \
  --self-test-mode
```

**Agent Updater v7.14 or v7.15**

Run self-test mode through the installed agent:

```bash
cd /tmp/cdev/installation
bin/skagent -K
bin/skagent \
  --config-file /opt/thousandeyes/cdev/router_agent_updater/etc/skagent.cfg \
  --self-test-mode
```

Versions earlier than v7.14 do not support self-test mode.
{% endtab %}

{% tab title="Agent-only" %}
For agent version v7.14 or later, stop the agent service, then run the agent in self-test mode:

```bash
cd /opt/samknows/router_agent
bin/skagent -K
bin/skagent --self-test-mode
```

Versions earlier than v7.14 do not support self-test mode.
{% endtab %}
{% endtabs %}

To use a different configuration file for an agent-only installation, run:

```bash
bin/skagent --self-test-mode -c /path/to/skagent.cfg
```

Self-test runs once, displays its results locally, and exits. It does not report the results to ThousandEyes.

Agent versions earlier than v7.14 do not support self-test mode.

## Running Self-Test Against an On-Net Server

Use a target override to run the agent in self-test mode against a nearby on-net server.

1. Confirm that the on-net server is ready for the diagnostic.

   The on-net server does not need to be provisioned or visible in the ThousandEyes platform for this diagnostic. It only needs to run the supported test-server software and be reachable from the device. See [On-Net Test Server Installation](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/on-net-test-server-installation.md).
2. Replace `192.0.2.10` below with the hostname or IP address of your on-net test server, then run the agent in self-test mode:

The override changes the target for HTTP speed, UDP speed, jitter, and ICMP ping checks. Assigned tests retain their ports, paths, directions, and other options.

A normal self-test run does not require a target. It uses assigned tests and built-in defaults. UDP speed runs when scheduled. With a target override, self-test mode automatically adds any missing UDP direction.

## Reading the Result

Each step reports one of these statuses:

| Status    | Meaning                        | Action                           |
| --------- | ------------------------------ | -------------------------------- |
| `PASSED`  | The check completed            | Continue                         |
| `FAILED`  | The check found a problem      | Fix the reported cause and rerun |
| `SKIPPED` | An earlier prerequisite failed | Fix the earlier failure first    |

Self-test ends with a summary similar to this:

```
Self-test overall result: PASSED

+------------------------+----------+
| Step                   | Result   |
+------------------------+----------+
| device_info            | PASSED   |
| time_check             | PASSED   |
| activation             | PASSED   |
| schedule_retrieval     | PASSED   |
| a3p_schedule_retrieval | PASSED   |
| ping_test              | PASSED   |
| speed_test             | PASSED   |
| jitter_test            | PASSED   |
| cross_traffic          | PASSED   |
+------------------------+----------+
```

Build-disabled checks are omitted. The command succeeds only if every displayed check passes.

## Checks

### `device_info`

Shows the agent version, model, MAC, client, WAN interface, metadata, and any detected accelerator information.

A pass means the configuration was read. Compare the MAC with the device label and verify the model, firmware, client, and WAN interface.

### `time_check`

Compares device time with the configured time service. The check fails when the offset exceeds 30 seconds. Correct the device time before investigating activation.

### `activation`

Contacts the activation service and prints the Unit ID when successful. Common failures include an incorrect secret, incorrect device time, DNS resolution or HTTPS reachability problems, and firewall or proxy policy.

Schedule-dependent checks are skipped when activation fails.

### `schedule_retrieval` and `a3p_schedule_retrieval`

Retrieve and parse the applicable agent schedules. The task counts show which tasks the agent received. They do not confirm that the tasks ran.

### `ping_test`

Runs assigned ICMP ping tests and prints latency and packet-loss metrics. If none are assigned, the self-test run uses `samknows-cdn.com`. A target override replaces the ping target.

### `speed_test`

Runs assigned HTTP and UDP speed tests. Each speed test runs three iterations.

TCP results can include `Speed backend`, which identifies the software or hardware measurement path used for that iteration. Common values include `software`, `broadcom-htoa-fro`, `broadcom-htoa-enhanced-software-gso`, and `qualcomm-socket-offload`. UDP results do not include this field.

The self-test can pass even when `Speed backend` is absent. For supported acceleration options, see [System Requirements](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/getting-started/system-requirements.md#hardware-acceleration). If test results are below the expected tier, see [Speed Quick Wins](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/speed-quick-wins.md).

On agent builds that support speed-test hooks, HTTP self-test measurements run the configured setup and cleanup phases. Self-test startup also attempts recovery cleanup. A passing speed-test result doesn’t confirm that cleanup succeeded. Check the logs and verify that device settings and hook-owned firewall state returned to their expected states. See [Speed-Test Optimization Hooks](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/speed-test-optimization-hooks.md).

### `jitter_test`

Runs assigned UDP jitter tests or a built-in default when none are assigned.

### `cross_traffic`

Reads the configured cross-traffic counters, generates a controlled software-mode download, and confirms that the receive counters increased by the expected amount.

A failure usually means that the agent selected the wrong WAN interface, that the interface counters do not include agent traffic, or that the background-traffic monitor could not read the counters.

## After the Test

Restart the normal agent or Agent Updater process after self-test. Confirm that the Unit ID remains unchanged.

If speed is below the intended tier, follow [Speed Quick Wins](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/speed-quick-wins.md). For support, include the complete self-test output, Unit ID, firmware and kernel versions, WAN type, target, and any configuration changes already tried.
