chrony-rs

chrony-rs is a forensic Rust reconstruction of chrony's time-discipline behavior. It is developed by differential comparison against the real chrony 4.5 C sources and chronyd, deterministic trace replay, packet-level byte receipts, and explicit deployment-boundary documentation.

This is not a clean-room "inspired by chrony" rewrite, not a toy NTP daemon, and not a production replacement. The C chrony implementation remains the primary behavioral oracle; independent NTP/protocol witnesses (RFC vectors, FIPS/NIST known-answer tests) are used only to classify where chrony policy differs from generic protocol truth.

What exists today

Fully ported chrony 4.5 translation units (61)

Every function in each unit has a court-backed counterpart — differential-tested against the real compiled C and/or protocol-spec vectors.

The full per-file breakdown with notes is in the ported-modules.md. See the port-parity matrix for the file-level status of all 70 chrony C files, and the per-function gap view for individual C function coverage.

Other ported surfaces

In addition to the fully ported modules above, the following chrony surfaces have been ported (to varying degrees):

What is intentionally NOT claimed

chrony-rs does not discipline a real system clock, does not connect to a running daemon over the control socket, and makes no production-replacement claim. These are deliberate, documented boundaries — see docs/deployment-boundary.md and the generated docs/negative-capabilities.md. Host-clock mutation is forbidden outside declared lab courts. Where behavior is unknown, environmental, or version-dependent, it is classified as such rather than approximated.

Architecture

A lean Cargo workspace:

crates/
  chrony-rs        public umbrella crate (re-exports chrony-rs-core)
  chrony-rs-core   deterministic time-discipline brain (no host clock, no sockets)
  chronyd-rs       daemon/replay binary (lab & offline modes only)
  chronyc-rs       control client & output-parity tool
xtask              doc generation + freshness gating (cargo xtask gen|check)

Host mutation (clock, sockets, privileges) is kept behind narrow trait/closure boundaries so the brain is testable without the real system clock — every ported unit above injects its clock/syscalls/randomness. Each crate has its own generated README. See docs/architecture.md.

Generated docs & freshness gate

Machine-derivable facts (target chrony version, the 93-directive recognition set, source-option tables, unsafe count, oracle fixtures) are generated from the code into docs/generated/ by cargo xtask gen — including the port-parity matrix and a per-function gap view. The negative-capabilities ledger, all four crate READMEs, and this README are generated too.

A pre-commit hook runs cargo xtask check, which rejects any commit where (1) a generated doc is stale, or (2) a curated prose doc has drifted from a machine fact it restates. Nothing documented — generated or prose — can silently drift from the code. Activate the hook with:

git config core.hooksPath .githooks

Source archaeology

The chrony 4.5 C source is the structural oracle. Its directive dispatch (conf.c) and source-option tables (cmdparse.c) were extracted by Doxygen-style indexing and diffed against chrony-rs — see research/ and docs/source-archaeology.md. That diff plus the live chronyd -p oracle is how the config surface reached 1:1: 93/93 directives recognized, exact diagnostics, and source-option validation matching chrony.

Doctrine

Byte parity, behavior parity, operational-knowledge parity.

Every admitted behavior must be backed by a court with reproducible evidence (reports/). Code ports are not transliterations; they are archaeological restorations with executable evidence. The verbose source comments are part of the deliverable: a future engineer should understand chrony better from this reconstruction than from the C alone.

License

GPL-2.0-only, matching chrony's licensing posture. See LICENSE.

Crates on crates.io

All chrony-rs crates are published on crates.io:

Crate	Description
chrony-rs	Umbrella facade crate (re-exports chrony-rs-core)
chrony-rs-core	Deterministic time-discipline brain
chrony-rs-io	Real OS I/O layer (libc syscall wrappers)
chronyd-rs	Daemon/replay binary (lab & offline modes)
chronyc-rs	Control client and output-parity tool

Acknowledgements

chrony-rs is a forensic reconstruction of chrony, originally written by Richard P. Curnow and currently maintained by Miroslav Lichvar and the chrony community. chrony is the gold standard for NTP time synchronization on Linux, and this project would not exist without their decades of careful engineering, meticulous specification, and open-source dedication.

chrony-rs is independently implemented by observing chrony's behavior through differential testing against the real chrony C sources — it is not derived from chrony's C code. The chrony project remains the primary behavioral oracle for this work.