S6-SNTPCLOCK(8)

📦 version 2.8.0.1, in nixpkgs unstable

💅 s6-sntpclock(8) — small SNTP client

okay so bestie, this is a page from the System Manager's Manual and it's about s6-sntpclock, a lil SNTP client that is genuinely iconic. let's get into it 🫶

✨ SYNOPSIS ✨

s6-sntpclock [-f] [-v verbosity] [-r roundtrips] [-t triptimeout]
             [-h throttle] [-T totaltimeout] [-e errmax] [-p port]
             ipaddress

🌸 DESCRIPTION 🌸

so s6-sntpclock connects to an SNTP or NTP server, figures out roughly how far off your local clock is from the absolute time that server says it is, and then prints that discrepancy to stdout. no cap. that's the whole job 💖

it does this by exchanging SNTPv4 messages with an SNTP server that's listening on ipaddress, UDP port 123. and ipaddress can be IPv4 or IPv6, we love a flexible queen ✨

it computes the mean difference between the absolute time given by the system clock and the one given by the server.

then it prints the difference to stdout in a format that s6-clockadd(8) and s6-clockview(8) understand, and exits 0. slay.

😭 the NTP protocol has infelicities (real)

there are a LOT of infelicities in the NTP protocol (and SNTP is a subset of it, so it inherits all of them, rip). the biggest offender is probably that NTP literally cannot handle a time difference of more than 34 years: if the time given by the NTP server is more than 34 years away from the time given by the system clock, then NTP just cannot compute. like, it gives up. 💀

this is a whole problem for CMOS-less systems, where the system clock is initialized to the Unix Epoch. the solution is to first manually initialize the system clock with a program such as date(1) or s6-clock[1] to a closer time (such as 2013-01-01, which will be good up to 2047), and then contact the NTP server. pre-game your clock, basically 🎀

a less obvious problem with NTP is that it works with UTC time, which means it gives inaccurate results when close to a leap second, up to one second off when used during a leap second, and this is bound to the use of UTC: there is nothing you can do about it. 🙈 the only solution to get reliable results even around a leap second is to use linear time such as TAI; the s6-taiclock(8) and s6-taiclockd(8) programs provide tools to do so.

🧚 a word on ntpd

from a Unix software engineering standpoint, the well-known ntpd[2] program is an eldritch abomination. i said what i said. the main reason for it is that, just like its lovely cousin BIND[3], ntpd performs a lot of different tasks in a unique process, instead of separating what could, and should, be separated. this is confusing for both the programmer and the software user. the term "NTP server" means two different things:

  • A program that serves NTP time to the Internet and can be accessed by NTP clients.
  • A daemon, i.e. a long-lived process, that runs on a machine and handles NTP-related stuff such as keeping the system clock accurate.

the former is the real meaning of "NTP server". the latter is a common usage for the term, but comes from a misuse of "server" to mean "daemon". iykyk ✨

ntpd does not help clear the misunderstanding since it does both. it acts as an NTP server, and as an NTP client getting its time from lower-strata NTP servers, and as a local system clock management daemon. those are already 3 separate tasks, bestie. three. 🫠

local system clock management itself involves several duties:

  • there's the regular setting of the system clock, which can be done with a loop over a simple program such as s6-clockadd(8).
  • there's also control of the clock skew, which s6-networking does not provide because there is no portable interface for that; there is such a tool in the clockspeed[4] package.

ntpd includes a complete cryptographic key management system for the crypto part of NTP. but NTP is not the only protocol that uses cryptography and asymmetric keys; managing keys in a separate tool, not in the NTP daemon itself, would be simpler and smarter. 💅

ntpd provides monitoring support for client and server timekeeping performance. this would be best implemented as a separate specific log analyzing tool.

and of course, no matter how many layers of complexity you add onto ntpd, it will never be able to give accurate time in the vicinity of a leap second, since the very protocol is flawed by design — but the ntpd authors cannot be blamed for that. also, the ntpd writers, not the designers, should be praised: the history of ntpd security flaws is remarkably small, which is quite a feat for a huge monolithic root daemon. genuinely impressive, we stan 👑

network synchronization is important, NTP has its perks and valid use cases, and its existence is a good thing. however, the author wishes that the main NTP implementation weren't written as a big fat clumsy process running as root. s6-sntpclock together with s6-clockadd(8) aims to provide a small, simple tool to keep system clocks — especially in embedded devices — synchronized to a NTP server. periodt. 🌈

🎀 OPTIONS 🎀

  • -f — Force. normally, s6-sntpclock exits 111 if it cannot compute a time with a smaller uncertainty than errmax. if this option is set, it will output a time difference and exit 0 even if the error is too big. (chaotic but valid 💀)
  • -v verbosity — Be more or less verbose. by default, verbosity is 1. 0 means only print fatal error messages; 3 means trace every exchange with the server. pick your vibe.
  • -r roundtrips — Perform roundtrips exchanges with the server. by default, roundtrips is 10. a lower value yields a higher time uncertainty; a higher value puts more load on the server. balance, bestie ⚖️
  • -t triptimeout — If an SNTP exchange with the server takes more than triptimeout milliseconds, abort this exchange and move on to the next one. by default, triptimeout is 2000.
  • -h throttle — Wait throttle milliseconds between exchanges with the server. a lower value gets the final result earlier, but exerts more load on the server. a higher value puts a lighter load on the server, but delays the computation. by default, throttle is 0. it is recommended to set it to a reasonable nonzero value when increasing roundtrips. be polite to the server fr fr 🥺
  • -T totaltimeout — If the whole operation takes more than totaltimeout milliseconds, abort and exit 1. by default, totaltimeout is 10000.
  • -e errmax — Accept a maximum time uncertainty of errmax milliseconds. by default, errmax is 100.
  • -p port — Contact a server on port port. by default, port is 123.

🦋 SEE ALSO 🦋

s6-clockadd(8), s6-clockview(8), s6-taiclock(8), s6-taiclockd(8)

[1] https://skarnet.org/software/s6-portable-utils/s6-clock.html

[2] https://doc.ntp.org/4.1.0/ntpd.htm

[3] https://www.isc.org/downloads/bind/

[4] https://cr.yp.to/clockspeed.html

this man page is ported from the authoritative documentation at: https://skarnet.org/software/s6-networking/s6-sntpclock.html

👑 AUTHORS 👑

Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)

okay that's the whole page bestie, go sync some clocks 💖

and that's a wrap, mwah 💋 — this one shipped on the Debian side of things, dated September 29, 2021, and it's the s6-sntpclock(8) page from the System Manager's Manual 🎀✨

📦 where this page comes from