How to Report Issues with NTS Servers in the jauderho/nts-servers Repository

To report issues with NTS servers in the jauderho/nts-servers repository, verify the problem using the scripts/ntsCheck.sh script, document the failure with metadata from nts-sources.yml, and submit a GitHub issue or pull request with corrected server details.

The jauderho/nts-servers repository maintains a curated list of Network Time Security (NTS) capable NTP servers for secure time synchronization. When you discover a server that is unreachable, misclassified, or incorrectly described, the repository provides specific workflows and automation scripts to standardize the process of reporting and fixing these entries.

Verifying NTS Server Problems with the Provided Script

Before submitting a report, confirm the server failure using the verification script located at scripts/ntsCheck.sh. This script validates that the target server cannot be reached via NTS.

Run the script with the hostname of the suspect server:

./scripts/ntsCheck.sh <NTS_SERVER_NAME>

Capture the console output or take a screenshot of the results to attach to your report. This verification step ensures that reported issues are reproducible and not transient network errors.

Documenting Server Details from nts-sources.yml

Gather the current metadata for the problematic entry from nts-sources.yml, the canonical source file defining all listed servers. According to the repository structure, each entry includes:

• Hostname – The DNS name of the NTS server
• Stratum – The time source hierarchy level
• Location – Geographic region or country code
• Owner – Organization operating the server
• VM flag – Boolean indicating if the server is virtualized
• Notes – Additional descriptive text

Copy these fields exactly as they appear in nts-sources.yml when preparing your report. This metadata provides maintainers with the context needed to locate and verify the specific entry.

Submitting a GitHub Issue for NTS Server Problems

Open a new issue on the project's issue tracker at https://github.com/jauderho/nts-servers/issues. Structure your report with the following sections to match the repository's workflow:

1. Server Details – Provide the hostname and current metadata from nts-sources.yml
2. Observed Problem – Describe the failure mode, include timestamps, and paste the verification command output
3. Suggested Fix (optional) – Propose corrected metadata or recommend removal if the server is permanently offline

Including the output from scripts/ntsCheck.sh demonstrates that you have followed the verification protocol and helps maintainers prioritize the report.

Contributing Fixes via Pull Request

If you know the correct information, you may bypass the issue tracker and submit a pull request directly. Edit nts-sources.yml to update or remove the problematic entry, following the contribution guidelines specified in README.md.

Maintain alphabetical order by country when modifying the list. After editing the YAML file, regenerate the derived configuration files using the converter script:

./scripts/ntpServerConverter.py nts-sources.yml

This command synchronizes chrony.conf and ntp.toml with your changes. Before submitting, verify the complete diff to ensure consistency across all generated files:

git diff origin README.md chrony.conf ntp.toml

Submit the pull request with a clear description referencing the verification output and the specific fields changed in nts-sources.yml.

Reporting Security Vulnerabilities

For security-sensitive findings—such as servers that leak timing data or are susceptible to denial-of-service attacks—follow the responsible disclosure process outlined in SECURITY.md. Do not open public issues for vulnerabilities.

Instead, report via the GitHub vulnerability reporting function as described in the security policy. This ensures that sensitive server weaknesses are addressed privately before public disclosure.

Summary

• Verify first – Use scripts/ntsCheck.sh to confirm NTS connectivity failures before reporting
• Document metadata – Copy hostname, stratum, location, owner, and VM status from nts-sources.yml
• Submit via GitHub Issues – Include server details, problem description, and verification output
• Contribute directly – Edit nts-sources.yml, run ./scripts/ntpServerConverter.py nts-sources.yml, and submit a PR with regenerated configs
• Handle security separately – Report vulnerabilities through GitHub's private vulnerability reporting per SECURITY.md

Frequently Asked Questions

How do I verify an NTS server is actually broken before reporting?

Run the ./scripts/ntsCheck.sh script with the server hostname as the argument. This script performs an NTS connectivity test and outputs diagnostic information. Attach this output to your GitHub issue to prove the failure is reproducible and not a transient network issue on your end.

What metadata should I include when reporting a bad NTS server?

Include the complete entry from nts-sources.yml: the hostname, current stratum, geographic location, owning organization, virtualization status (the vm flag), and any existing notes. This allows maintainers to quickly locate the exact line in the YAML file that needs correction or removal.

Can I fix the server list myself instead of opening an issue?

Yes. Edit nts-sources.yml directly, ensuring entries remain in alphabetical order by country. Then run ./scripts/ntpServerConverter.py nts-sources.yml to regenerate chrony.conf and ntp.toml. Verify your changes with git diff origin README.md chrony.conf ntp.toml before submitting the pull request.

How do I report security vulnerabilities in listed NTS servers?

For vulnerabilities like timing side-channels or denial-of-service susceptibility, use the GitHub vulnerability reporting function rather than public issues. Follow the process described in SECURITY.md to disclose security problems responsibly and privately.

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