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

To add a new NTS server to the jauderho/nts-servers list, validate the server using scripts/verifyNTSServers.py, add an entry to nts-sources.yml in alphabetical order by country, and regenerate the derived files with 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 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:

# 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. This is the single source of truth; you never edit README.md, chrony.conf, or 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:

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

Alphabetical Ordering by Country

The repository requires strict alphabetical sorting. According to 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, you must regenerate all downstream artifacts. The repository does not accept manual edits to derived files.

Using ntpServerConverter.py

Run scripts/ntpServerConverter.py without specifying an output format to update all files in-place:

# 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 with a freshly-generated Markdown table.

• generate_chrony_conf – Writes a new chrony.conf containing server … nts iburst lines, grouped by location.

• generate_ntp_toml – Writes a new 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:

# 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:

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 to confirm NTS connectivity before adding any server.
• Edit the source: Add entries only to nts-sources.yml, placing them in alphabetical order by country as specified in AGENTS.md.
• Regenerate automatically: Run scripts/ntpServerConverter.py to update README.md, chrony.conf, and 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 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 handles parsing during file generation.

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

Run the verification script 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 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 and 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, chrony.conf, or ntp.toml. These are auto-generated files created by 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}