ntpsec-rs-trace-0.3.48 is not a library.

ntpsec-rs-trace — ntptrace-rs

NTP path trace tool — traces the synchronization chain from a host to the reference clock.

Part of the ntpsec-rs workspace — a forensic Rust reconstruction of NTPsec. Version 0.3.48.

Overview

ntptrace-rs traces the NTP synchronization chain from a given host back to the ultimate reference clock (stratum 0/1 source). It recursively queries each hop's system peer, following the sys.peer chain and reporting stratum, offset, and delay at each step.

This is a forensic Rust reconstruction of the NTPsec ntptrace Python client.

How It Works

Query the starting host for its system variables via Mode 6.
Extract the system peer (syspeer association ID) and that peer's address.
Display the hop — host, refid, stratum, offset, delay.
Follow the chain — If the peer has a lower stratum, recursively query it.
Stop when — The reference clock (stratum 0/1) is reached, the host is unsynchronized (stratum ≥ 15), or the maximum depth is exceeded.

Usage

Basic Trace

ntptrace-rs

Traces from the local host (127.0.0.1):

ntptrace-rs v0.3.48 — NTP trace tool (Rust)
Tracing from: 127.0.0.1 (max depth: 10)

          host           refid  st      offset       delay
------------------------------------------------------------
     127.0.0.1      203.0.113.1   3    0.000456   0.012345
   ntp.example.com          GPS   2    0.000321   0.014567

Trace from a Specific Host

ntptrace-rs ntp.example.com

Custom Maximum Depth

ntptrace-rs -d 5

Limits the trace to 5 hops from the starting host.

Custom Timeout

ntptrace-rs -t 10

Each hop query has a 10-second timeout (default: 5).

Command-Line Flags

Flag	Description	Default
`host`	Hostname or IP to start tracing from	`127.0.0.1`
`-d, --max-depth <n>`	Maximum trace depth (hops)	`10`
`-t, --timeout <secs>`	Timeout per host query in seconds	`5`

Output Format

          host           refid  st      offset       delay
------------------------------------------------------------
   ntp.example.com          GPS   2    0.000456   0.012345

Column	Description
`host`	Hostname or IP address of the queried NTP daemon
`refid`	Reference identifier of the time source
`st`	Stratum level (1 = primary, 2–15 = secondary, 16 = unsynchronized)
`offset`	Reported clock offset in seconds
`delay`	Reported round-trip delay in seconds

Error Handling

When a host is unreachable or returns an error, ntptrace-rs reports it gracefully:

Indicator	Meaning
`TIMEOUT`	Query timed out
`UNREACH`	Network connection failed
`ERROR`	Other query error (protocol, authentication, etc.)

In all error cases, the trace stops at that point rather than continuing into unknown territory.

Trace Termination Conditions

The trace stops when any of the following conditions are met:

Reference clock reached — The current host has stratum 0 or 1 (typically a GPS receiver, atomic clock, or NIST time service).
Unsynchronized host — Stratum ≥ 15 indicates the host is not synchronized to any time source.
Maximum depth exceeded — The --max-depth limit is reached.
Query failure — The target host is unreachable or returns an error.
Loop detected — The trace detects it is revisiting a host already in the chain, preventing infinite loops.

Related Crates

All crates in the ntpsec-rs workspace on crates.io:

Crate	Description	crates.io
ntpsec-rs-core	Deterministic engine, wire codec, Mode 6, auth, refclocks, NTS
ntpsec-rs-io	Real I/O layer (system clock, network, state store)
ntpsec-rs	Umbrella facade crate
ntpsec-rs-d	ntpd-rs — NTP daemon binary
ntpsec-rs-query	ntpq-rs — Mode 6 query client
ntpsec-rs-dig	ntpdig-rs — NTP query tool
ntpsec-rs-keygen	NTP key generation
ntpsec-rs-leapfetch	Leap second file fetcher
ntpsec-rs-mon	Real-time NTP monitoring tool
ntpsec-rs-trace	NTP path trace tool
ntpsec-rs-wait	Wait until NTP server reachable
ntpsec-rs-viz	NTP data visualization
ntpsec-rs-frob	NTP configuration manipulator
ntpsec-rs-snmpd	SNMP monitoring daemon
ntpsec-rs-time	Single-shot time query tool
ntpsec-rs-sweep	Sweep through servers collecting stats
ntpsec-rs-loggps	GPS reference clock logging
ntpsec-rs-logtemp	System temperature logging