summaryrefslogtreecommitdiff
path: root/doc/s6-taiclock.html
diff options
context:
space:
mode:
authorLaurent Bercot <ska-skaware@skarnet.org>2014-12-15 23:08:59 +0000
committerLaurent Bercot <ska-skaware@skarnet.org>2014-12-15 23:08:59 +0000
commite0fc82203d677a6f1e808e9a1a46176c109d89be (patch)
treee9609209b755e3f7a8480aea86601ffe9d4ca540 /doc/s6-taiclock.html
downloads6-networking-e0fc82203d677a6f1e808e9a1a46176c109d89be.tar.xz
Initial commit
Diffstat (limited to 'doc/s6-taiclock.html')
-rw-r--r--doc/s6-taiclock.html114
1 files changed, 114 insertions, 0 deletions
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 @@
+<html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>s6-networking: the s6-taiclock program</title>
+ <meta name="Description" content="s6-networking: the s6-taiclock program" />
+ <meta name="Keywords" content="s6-networking s6-taiclock tai clock tai64 tai64n tai64na client" />
+ <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+ </head>
+<body>
+
+<p>
+<a href="index.html">s6-networking</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>s6-taiclock</tt> program </h1>
+
+<p>
+<tt>s6-taiclock</tt> is a client for the
+<a href="http://cr.yp.to/proto/taiclock.txt">TAICLOCK</a> 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.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+ s6-taiclock [ -f ] [ -v <em>verbosity</em> ] [ -r <em>roundtrips</em> ] [ -t <em>triptimeout</em> ] [ -h <em>throttle</em> ] [ -T <em>totaltimeout</em> ] [ -e <em>errmax</em> ] [ -p <em>port</em> ] <em>ipaddress</em> | s6-clockview
+</pre>
+
+<ul>
+ <li> s6-taiclock exchanges TAICLOCK messages with a server such as
+<a href="s6-taiclockd.html">s6-taiclockd</a>
+listening on <em>ipaddress</em>, UDP port 4014.
+<em>ipaddress</em> can be IPv4 or IPv6. </li>
+ <li> It computes the mean difference between the absolute time
+given by the system clock and the one given by the server. </li>
+ <li> It prints the difference to stdout in a format understood
+by <a href="s6-clockadd">s6-clockadd</a> and
+<a href="s6-clockview">s6-clockview</a>. It then exits 0. </li>
+</ul>
+
+<h2> Options </h2>
+
+<ul>
+ <li> <tt>-f</tt>&nbsp;: force. Normally, s6-taiclock exits 111 if it cannot
+compute a time with a smaller uncertainty than <em>errmax</em>. If this
+option is set, it will output a time difference and exit 0 even if the
+error is too big. </li>
+ <li> <tt>-v&nbsp;<em>verbosity</em></tt>&nbsp;: be more or less verbose.
+By default, <em>verbosity</em> is 1. 0 means only print fatal error
+messages; 2 means print advanced warnings. </li>
+ <li> <tt>-r&nbsp;<em>roundtrips</em></tt>&nbsp;: perform <em>roundtrips</em>
+exchanges with the server. By default, <em>roundtrip</em> is 10. A lower
+value yields a higher time uncertainty; a higher value puts more load on
+the server. </li>
+ <li> <tt>-t&nbsp;<em>triptimeout</em></tt>&nbsp;: if a TAICLOCK exchange with
+the server takes more than <em>triptimeout</em> milliseconds, abort this
+exchange and move on to the next one. By default, <em>triptimeout</em>
+is 2000. </li>
+ <li> <tt>-h&nbsp;<em>throttle</em></tt>&nbsp;: wait <em>throttle</em>
+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, <em>throttle</em> is 0. It is recommended to set it to a
+reasonable nonzero value when increasing <em>roundtrips</em>. </li>
+ <li> <tt>-T&nbsp;<em>totaltimeout</em></tt>&nbsp;: if the whole
+operation takes more than <em>totaltimeout</em> milliseconds, abort
+and exit 1. By default, <em>totaltimeout</em> is 10000. </li>
+ <li> <tt>-e&nbsp;<em>errmax</em></tt>&nbsp;: accept a maximum time
+uncertainty of <em>errmax</em> milliseconds. By default, <em>errmax</em>
+is 100. </li>
+ <li> <tt>-p&nbsp;<em>port</em></tt>&nbsp;: contact a server on port
+<em>port</em>. By default, <em>port</em> is 4014. </li>
+</ul>
+
+<h2> Notes </h2>
+
+<h3> On the usage of NTP vs. TAICLOCK </h3>
+
+<ul>
+ <li> 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. </li>
+ <li> 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. </li>
+ <li> 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. </li>
+ <li> TAICLOCK is much easier to implement. The
+<a href="s6-sntpclock.html">s6-sntpclock</a> client binary code
+(statically linked on a i386) is 50% bigger than the s6-taiclock
+client. Also, the <a href="s6-taiclockd.html">s6-taiclockd</a>
+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. </li>
+</ul>
+
+<h3> Related work </h3>
+
+<ul>
+ <li> The <a href="http://cr.yp.to/clockspeed.html">clockspeed</a> package
+is the original inspiration for the clock management part of s6-networking.
+Unfortunately, it is unmaintained. </li>
+</ul>
+
+</body>
+</html>