# How to Add a New NTS Server to the jauderho/nts-servers List: A Complete Guide

> Learn to add a new NTS server to the jauderho/nts-servers list easily. Follow our step by step guide for validation, configuration, and file regeneration for seamless integration.

- Repository: [Jauder Ho/nts-servers](https://github.com/jauderho/nts-servers)
- Tags: how-to-guide
- Published: 2026-03-04

---

**To add a new NTS server to the jauderho/nts-servers list, validate the server using [`scripts/verifyNTSServers.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/verifyNTSServers.py), add an entry to [`nts-sources.yml`](https://github.com/jauderho/nts-servers/blob/main/nts-sources.yml) in alphabetical order by country, and regenerate the derived files with [`scripts/ntpServerConverter.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntpServerConverter.py).**

The **jauderho/nts-servers** repository maintains a curated, alphabetically-sorted collection of Network Time Security (NTS) servers. If you want to add a new NTS server to the jauderho/nts-servers list, you must follow a strict validation and generation workflow to ensure consistency across all derived configuration files.

## Validate the Server Before Submission

Before any server reaches the public list, it must be reachable via NTS and ordinary NTP. The repository enforces this through automated verification.

### Using verifyNTSServers.py

The helper script **[`scripts/verifyNTSServers.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/verifyNTSServers.py)** runs a `chronyd` query against hostnames to guarantee that only working servers end up in the public list. The script constructs a command using `chronyd -Q` within the `verify_ntp_server` function.

Validate a single candidate before editing the source file:

```bash

# Verify a specific hostname

python3 scripts/verifyNTSServers.py nts-sources.yml --hostname example.ntp.org

# Verify all servers (useful after bulk edits)

python3 scripts/verifyNTSServers.py nts-sources.yml

```

## Edit the Canonical Source File

All server data lives in **[`nts-sources.yml`](https://github.com/jauderho/nts-servers/blob/main/nts-sources.yml)**. This is the single source of truth; you never edit [`README.md`](https://github.com/jauderho/nts-servers/blob/main/README.md), [`chrony.conf`](https://github.com/jauderho/nts-servers/blob/main/chrony.conf), or [`ntp.toml`](https://github.com/jauderho/nts-servers/blob/main/ntp.toml) manually.

### Understanding nts-sources.yml Structure

Each entry follows a strict schema with fields for `hostname`, `stratum`, `location`, `owner`, optional `notes`, and a boolean `vm` flag.

A minimal entry looks like this:

```yaml
- hostname: example.ntp.org
  stratum: 2
  location: Wonderland
  owner: Example Corp
  vm: false

```

The `hostname` field may be a plain name or a Markdown link (e.g., `[example.ntp.org](https://example.ntp.org)`). The conversion scripts automatically extract the raw hostname when needed via the `extract_hostname` function in **[`scripts/ntpServerConverter.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntpServerConverter.py)**.

### Alphabetical Ordering by Country

The repository requires strict alphabetical sorting. According to **[`AGENTS.md`](https://github.com/jauderho/nts-servers/blob/main/AGENTS.md)** (lines 4-6), you must *“Place new entry in the proper location in nts-sources.yml by alphabetical country”*.

Locate the correct position by `location` (country), then insert your entry maintaining the existing alphabetical sequence.

## Regenerate Derived Configuration Files

After updating [`nts-sources.yml`](https://github.com/jauderho/nts-servers/blob/main/nts-sources.yml), you must regenerate all downstream artifacts. The repository does not accept manual edits to derived files.

### Using ntpServerConverter.py

Run **[`scripts/ntpServerConverter.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntpServerConverter.py)** without specifying an output format to update all files in-place:

```bash

# Regenerate README.md, chrony.conf, and ntp.toml

python3 scripts/ntpServerConverter.py nts-sources.yml

```

This script performs three critical operations via internal functions:
- **`generate_markdown`** – Replaces the “## The List” section in [`README.md`](https://github.com/jauderho/nts-servers/blob/main/README.md) with a freshly-generated Markdown table.

- **`generate_chrony_conf`** – Writes a new [`chrony.conf`](https://github.com/jauderho/nts-servers/blob/main/chrony.conf) containing `server … nts iburst` lines, grouped by location.
- **`generate_ntp_toml`** – Writes a new [`ntp.toml`](https://github.com/jauderho/nts-servers/blob/main/ntp.toml) in `ntpd-rs` format.

The script respects the `vm` flag, moving virtualized servers to a separate “known VM servers” block.

### Generate Specific Formats (Optional)

If you need only one output format for testing:

```bash

# Only markdown output

python3 scripts/ntpServerConverter.py nts-sources.yml markdown /tmp/servers.md

# Only chrony.conf output

python3 scripts/ntpServerConverter.py nts-sources.yml chrony /tmp/chrony.conf

```

## Commit and Submit Your Changes

Once validation and regeneration are complete, follow standard Git workflow:

```bash
git add nts-sources.yml scripts/ntpServerConverter.py README.md chrony.conf ntp.toml
git commit -m "Add example.ntp.org – Wonderland"
git push

```

The repository’s CI pipelines automatically lint the YAML, run the verification script on the new host, and ensure the generated configuration files stay in sync.

## Summary

- **Validate first**: Use [`scripts/verifyNTSServers.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/verifyNTSServers.py) to confirm NTS connectivity before adding any server.
- **Edit the source**: Add entries only to [`nts-sources.yml`](https://github.com/jauderho/nts-servers/blob/main/nts-sources.yml), placing them in alphabetical order by country as specified in [`AGENTS.md`](https://github.com/jauderho/nts-servers/blob/main/AGENTS.md).
- **Regenerate automatically**: Run [`scripts/ntpServerConverter.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntpServerConverter.py) to update [`README.md`](https://github.com/jauderho/nts-servers/blob/main/README.md), [`chrony.conf`](https://github.com/jauderho/nts-servers/blob/main/chrony.conf), and [`ntp.toml`](https://github.com/jauderho/nts-servers/blob/main/ntp.toml)—never edit these manually.
- **Follow the schema**: Include required fields (`hostname`, `stratum`, `location`, `owner`) and optional flags (`vm`, `notes`) using valid YAML syntax.

## Frequently Asked Questions

### What is the nts-sources.yml file format?

The [`nts-sources.yml`](https://github.com/jauderho/nts-servers/blob/main/nts-sources.yml) file is a YAML list where each item represents an NTS server with fields for `hostname`, `stratum`, `location`, `owner`, optional `notes`, and a boolean `vm` flag. The `hostname` can be a plain string or a Markdown link, and the `extract_hostname` function in [`scripts/ntpServerConverter.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntpServerConverter.py) handles parsing during file generation.

### How do I verify that my NTS server is working before submitting?

Run the verification script [`scripts/verifyNTSServers.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/verifyNTSServers.py) against your candidate hostname using the command `python3 scripts/verifyNTSServers.py nts-sources.yml --hostname your.server.org`. This script uses `chronyd -Q` via the `verify_ntp_server` function to confirm both NTS and NTP connectivity, ensuring only functional servers enter the public list.

### Why must entries be sorted by country in nts-sources.yml?

The repository requires alphabetical ordering by country (the `location` field) to maintain consistency and readability across the curated list. According to [`AGENTS.md`](https://github.com/jauderho/nts-servers/blob/main/AGENTS.md) lines 4-6, contributors must place new entries in the proper alphabetical location, which allows the conversion scripts to generate properly grouped configuration files for [`chrony.conf`](https://github.com/jauderho/nts-servers/blob/main/chrony.conf) and [`ntp.toml`](https://github.com/jauderho/nts-servers/blob/main/ntp.toml).

### Can I manually edit README.md or chrony.conf instead of using the converter script?

No, you should never manually edit [`README.md`](https://github.com/jauderho/nts-servers/blob/main/README.md), [`chrony.conf`](https://github.com/jauderho/nts-servers/blob/main/chrony.conf), or [`ntp.toml`](https://github.com/jauderho/nts-servers/blob/main/ntp.toml). These are auto-generated files created by [`scripts/ntpServerConverter.py`](https://github.com/jauderho/nts-servers/blob/main/scripts/ntpServerConverter.py) using functions like `generate_markdown`, `generate_chrony_conf`, and `generate_ntp_toml`. Manual edits will be overwritten the next time the script runs and will cause CI pipeline failures.