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-taiclock.html | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 doc/s6-taiclock.html (limited to 'doc/s6-taiclock.html') diff --git a/doc/s6-taiclock.html b/doc/s6-taiclock.html new file mode 100644 index 0000000..bbdc680 --- /dev/null +++ b/doc/s6-taiclock.html @@ -0,0 +1,114 @@ + + + + + s6-networking: the s6-taiclock program + + + + + + +

+ +

The `s6-taiclock` program

+ +

+s6-taiclock is a client for the +TAICLOCK protocol. +It connects to a TAICLOCK 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-taiclock [ -f ] [ -v verbosity ] [ -r roundtrips ] [ -t triptimeout ] [ -h throttle ] [ -T totaltimeout ] [ -e errmax ] [ -p port ] ipaddress | s6-clockview
+

+ +

s6-taiclock exchanges TAICLOCK messages with a server such as +s6-taiclockd +listening on ipaddress, UDP port 4014. +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-taiclock 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; 2 means print advanced warnings.
-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 TAICLOCK 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 4014.

+ +

Notes

+ +

On the usage of NTP vs. TAICLOCK

+ +

TAICLOCK is not as generic or failproof as NTP. It is not as +resistant to network latency. It has been designed to broadcast +time on a local area network, whereas NTP has been designed to +broadcast time over the whole Internet.
TAICLOCK will produce faster results on a LAN; moreover, the +point of TAICLOCK is to broadcast TAI instead of UTC, so it is +more accurate around a leap second.
The Internet is much more reliable latency-wise today +than it was when dialout connections and broken routing protocols +were the norm. So it is possible to use TAICLOCK +across a WAN if the accuracy expectations are not too strict.
TAICLOCK is much easier to implement. The +s6-sntpclock client binary code +(statically linked on a i386) is 50% bigger than the s6-taiclock +client. Also, the s6-taiclockd +server is extremely small (close to 50% smaller than the client), +whereas NTP servers, even SNTP servers, are behemoths requiring +a project of their own.

+ +

Related work

+ +

The clockspeed package +is the original inspiration for the clock management part of s6-networking. +Unfortunately, it is unmaintained.