The s6-sntpclock program
s6-sntpclock is a small SNTP client. It connects to an
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.
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.
- -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, roundtrips is 10. A lower
value yields a higher time uncertainty; a higher value puts more load on
- -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
- -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
- -p port : contact a server on port
port. By default, port is 123.
- 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
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-taiclockd programs provide tools to
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:
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.
- 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.
- 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
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.