> 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/on-net-test-server-installation.md).

# On-Net Test Server Installation

Install an on-net test server to create a controlled measurement target inside your network. Compare its results with an off-net target to assess device and internal-network performance. This comparison also helps you account for public internet paths and remote target capacity.

## Choosing How to Use the Server

You can use the same server in two ways:

* For a target override in self-test mode, install the supported server software and confirm that it is running and reachable from the device. The server does not need to be provisioned or visible in the ThousandEyes platform.
* For scheduled tests or Test Settings, install the software and ask Cisco ThousandEyes to provision the server as a platform target.

For how on-net and off-net targets fit into measurement design, see [Test Server Methodology](https://docs.thousandeyes.com/product-documentation/connected-devices/test-management/test-targets/test-server-methodology).

## Before You Begin

* Provision a host that meets the [server requirements](#server-requirements) below.
* Plan [firewall rules](#configuring-firewall-rules) so Device Agents can reach the test ports from the networks you will measure.
* Confirm that the host can resolve DNS and reach the package repository.

## Server Requirements

On-net test servers can be virtual machines or dedicated hardware. Use dedicated hosts only as test servers, not as general web or file servers.

### 10 Gbps (Minimum)

| Component    | Requirement                                                    |
| ------------ | -------------------------------------------------------------- |
| CPU          | Quad-core Xeon, 2 GHz or faster                                |
| RAM          | 16 GB                                                          |
| Disk         | 250 GB SSD                                                     |
| OS           | Ubuntu 22.04 LTS (preferred), Ubuntu 24.04, or Rocky Linux 9.x |
| Connectivity | 10 Gbps minimum                                                |

### 100 Gbps (Recommended for Large Deployments)

| Component    | Requirement                                                    |
| ------------ | -------------------------------------------------------------- |
| CPU          | 20+ cores, 2.4 GHz or faster                                   |
| RAM          | 64 GB                                                          |
| Disk         | 250 GB SSD                                                     |
| OS           | Ubuntu 22.04 LTS (preferred), Ubuntu 24.04, or Rocky Linux 9.x |
| Connectivity | 100 Gbps with NVIDIA/Mellanox ConnectX-5/6/7                   |

## Installing the Server

Download the installer script for your operating system from the [thousandeyes/On-net-installer](https://github.com/thousandeyes/On-net-installer) repository. Run it as root on the target host.

### Ubuntu (22.04 or 24.04)

```bash
curl -fLO https://raw.githubusercontent.com/thousandeyes/On-net-installer/master/test_server_installer_ubuntu.sh
chmod +x test_server_installer_ubuntu.sh
./test_server_installer_ubuntu.sh
```

### Rocky Linux 9

```bash
curl -fLO https://raw.githubusercontent.com/thousandeyes/On-net-installer/master/test_server_installer_rocky_9.sh
chmod +x test_server_installer_rocky_9.sh
./test_server_installer_rocky_9.sh
```

### Choosing Installer Options

When the script starts, select an option:

1. Select `Install` to apply the recommended defaults automatically.
2. Select `Verbose Install` to have the installer prompt before each change.
3. Select `Exit` to leave the host unchanged.

The installer typically:

* Adds the Cisco ThousandEyes / SamKnows package repository.
* Installs on-net test server packages.
* Applies recommended network `sysctl` tuning.
* Configures the host firewall (UFW) with the required ports.
* Installs Nginx (optional SSL configuration).
* Installs a kernel with fair queuing enabled where applicable.

## Configuring Firewall Rules

If possible, host test servers without an external hardware firewall or restrictive ACL in front of them. If you use a firewall, make sure it can sustain the throughput you plan to test.

### Inbound (Minimum)

| Source | Protocol    | Port(s)   | Purpose                |
| ------ | ----------- | --------- | ---------------------- |
| ALL    | TCP         | 80, 443   | HTTP/HTTPS (Nginx)     |
| ALL    | TCP and UDP | 5000–7000 | Test applications      |
| ALL    | TCP         | 8080      | HTTP speed test server |
| ALL    | TCP         | 8000      | UDP speed control      |
| ALL    | UDP         | 8001      | UDP speed measurement  |

Allow return traffic from these services back to Device Agents on your measurement networks.

### Outbound

If outbound traffic is denied by default, allow TCP 80 and 443 to reach the package repository. Ensure that the host has working DNS resolvers.

## After Installation

1. Check each service on the on-net server. Each command should return `active`.

   ```bash
   systemctl is-active skhttp_server
   systemctl is-active skjitter_server
   systemctl is-active sklatency_server
   systemctl is-active sklightweightcapacity_server
   systemctl is-active skudpspeed_server
   systemctl is-active skwebsocket_speed_server
   systemctl is-active dart
   ```

   If a service is not active, inspect it with `systemctl status SERVICE_NAME` before continuing.
2. From a Device Agent host, confirm that routing, DNS, and firewall rules allow connections to the server hostname or IP on the ports above.
3. Establish a self-test baseline directly against the server, or [register the server as a test target](#registering-the-server-as-a-test-target) before assigning scheduled Device Agent tests. For the full deployment workflow, see [Plan, Deploy, and Update the Agent](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/plan-deploy-and-update-the-agent.md#8-plan-the-production-rollout-and-manage-agent-updates).

### Using the Server for Self-Test Without Provisioning

For a one-off diagnostic, the server does not need to be provisioned or visible in the ThousandEyes platform. After you install the supported test-server software, confirm that it is running and reachable from the device. Then use its hostname or IP as the [target override in self-test mode](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/validate-with-self-test-mode.md#running-self-test-against-an-on-net-server).

Provision the server only if you need to assign it through managed schedules or select it as a test target in the ThousandEyes platform.

## Registering the Server as a Test Target

Installing the server software does not register the server as a measurement target. Cisco ThousandEyes must provision it before you can assign it to scheduled Device Agent tests. This includes download and upload speed tests in [Test Settings](https://docs.thousandeyes.com/product-documentation/connected-devices/test-management/test-settings), where you choose targets from a fixed list.

Before requesting provisioning:

* Assign at least one publicly routable IPv4 address per server, with no NAT in front of it.
* Configure the server DNS records. Use separate IPv4 and IPv6 names when both are in use.
* Confirm that the [firewall rules](#configuring-firewall-rules) allow Device Agents to reach the server.

Send the [server details for provisioning](#server-details-for-provisioning) to your Cisco ThousandEyes account manager.

### Server Details for Provisioning

Provide the following per server (one submission per measurement server):

| Information                        | Notes                                                                                               |
| ---------------------------------- | --------------------------------------------------------------------------------------------------- |
| Server hostname                    | Must match the output of the `hostname` command on the server                                       |
| Fully qualified domain name (FQDN) | Must match the output of `hostname -f`                                                              |
| Geographic coordinates             | Decimal latitude and longitude of the server location                                               |
| Operating system                   | For example Ubuntu 22.04 LTS                                                                        |
| Hardware meets requirements        | Confirm the host meets the [server requirements](#server-requirements) for your intended link speed |
| Public IPv4 addresses              | All public IPv4 addresses used for testing (no NAT in front of the server)                          |
| Public IPv6 addresses              | Optional; list all public IPv6 addresses if used                                                    |
| IPv4-only FQDN                     | Required when IPv4 is enabled; DNS name used for IPv4 tests                                         |
| IPv6-only FQDN                     | Required when IPv6 is enabled; DNS name used for IPv6 tests                                         |
| Firewall requirements understood   | Confirm [firewall rules](#configuring-firewall-rules) are implemented on the host or network        |
| Primary interface name             | Interface carrying test traffic, for example `eth0`, `eno1`, `bond0`                                |
| Network link speed                 | Link speed of the primary interface (for example `10 Gbps`), not expected customer throughput       |
| Auto-manage UFW rules              | Whether the installer should manage UFW rules for test services (`Yes` / `No`)                      |

If Cisco ThousandEyes manages the server on your behalf, your account team might also request secure credentials and management access details separately. Most ISP and OEM lab servers are customer-managed and only require the fields above.

### After Cisco ThousandEyes Provisions the Server

Choose the workflow that matches how you assign tests in your account.

#### Managed Test Schedules (Test Manager)

If Cisco ThousandEyes manages your test schedules, provide the same [server details](#server-details-for-provisioning). Your account team provisions the server in the legacy Test Manager and associates it with the appropriate schedules or agents.

After your account team confirms provisioning, coordinate schedule and target assignment with your account manager.

#### Self-Serve Test Settings

If your devices run agent version 8 or later, the provisioned server can appear in the target lists for tests you configure in the UI, including download and upload speed tests.

1. Confirm the server is installed and reachable (see [After Installation](#after-installation)).
2. In Test Settings, create or edit a test group with the required test types.
3. For download and upload speed tests, select the provisioned on-net server from the target dropdown. Filter by on-net or private targets as needed.
4. Assign the test group to the relevant Device Agents.

See [Configuring Connected Devices Tests](https://docs.thousandeyes.com/product-documentation/connected-devices/test-management/test-settings/configuring-connected-devices-tests).

#### Validating on Devices

After you assign targets in Test Settings or legacy schedules, run the agent in [self-test mode](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/validation-and-troubleshooting/validate-with-self-test-mode.md) on representative devices. If the agent measures 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).

## Related Topics

* [Test Targets](https://docs.thousandeyes.com/product-documentation/connected-devices/test-management/test-targets)
* [Test Server Methodology](https://docs.thousandeyes.com/product-documentation/connected-devices/test-management/test-targets/test-server-methodology)
* [Test Settings](https://docs.thousandeyes.com/product-documentation/connected-devices/test-management/test-settings)
* [Configuring Connected Devices Tests](https://docs.thousandeyes.com/product-documentation/connected-devices/test-management/test-settings/configuring-connected-devices-tests)
