From e0fc82203d677a6f1e808e9a1a46176c109d89be Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 15 Dec 2014 23:08:59 +0000 Subject: Initial commit --- doc/s6-sntpclock.html | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 doc/s6-sntpclock.html (limited to 'doc/s6-sntpclock.html') diff --git a/doc/s6-sntpclock.html b/doc/s6-sntpclock.html new file mode 100644 index 0000000..0d4c45b --- /dev/null +++ b/doc/s6-sntpclock.html @@ -0,0 +1,166 @@ + + + + + s6-networking: the s6-sntpclock program + + + + + + +

+ +

The `s6-sntpclock` program

+ +

+s6-sntpclock is a small SNTP client. It connects to a +SNTP or NTP server, computes an estimated discrepancy between the +local clock time and the absolute time given by the server, and +outputs it on stdout. +

+ +

Interface

+ +

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

+ +

s6-sntpclock exchanges SNTPv4 messages with a SNTP server +listening on ipaddress, UDP port 123. +ipaddress can be IPv4 or IPv6.
It computes the mean difference between the absolute time +given by the system clock and the one given by the server.
It prints the difference to stdout in a format understood +by s6-clockadd and +s6-clockview. It then exits 0.

+ +

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.
-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.
-r roundtrips : perform roundtrips +exchanges with the server. By default, roundtrip is 10. A lower +value yields a higher time uncertainty; a higher value puts more load on +the server.
-t triptimeout : if a 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.
-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.

+ +

Notes

+ +

There are a lot of infelicities in the NTP protocol (which SNTP is +a subset of). The biggest offender is probably that NTP 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. This is a 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 or +s6-clock +to a closer time (such as 2013-01-01, which will be good up to 2047), then +contact the NTP server.
A less obvious problem with NTP is that it works with UTC time, +which means that 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 and +s6-taiclockd programs provide tools to +do so.

+ + +

A word on ntpd

+ +

+ From a Unix software engineering standpoint, the well-known +ntpd program is an +eldritch abomination. The main reason for it is that, just like its +lovely cousin BIND, +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". +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.
Local system clock management itself involves several duties. There +is the regular setting of the system clock, which can be done with +a loop over a simple program such as s6-clockadd. +There is 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 package.
ntpd includes a complete cryptographic key management system for the +crypto part of NTP. 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. +

+ +

+ Network synchronization is important, NTP has its perks and +valid use cases, and its existence is a good thing. However, I wish that +the main NTP implementation weren't written as a big fat clumsy process +running as root. s6-sntpclock together with +s6-clockadd aims to provide a small, simple +tool to keep system clocks, especially in embedded devices, synchronized +to a NTP server. +

+ + + -- cgit v1.2.3

The s6-sntpclock program

Interface

Options

Notes

A word on ntpd

The `s6-sntpclock` program