readme

A NTP client is a program which user can synchronize the time with time server assigned. This prog

ntpclient is an NTP (RFC-1305) client for unix-alike computers.
Its functionality is a small subset of xntpd, but IMHO performs
better (or at least has the potential to function better) within
that limited scope.  Since it is much smaller than xntpd, it is
also more relevant for embedded computers.

ntpclient is Copyright 1997, 1999, 2000, 2003 Larry Doolittle, and
may be freely used and copied according to the terms of the GNU
General Public License, version 2.  If you want to distribute ntpclient
under other terms, contact me.  I might agree to some other arrangement,
if you talk to me _before_ you start violating GPL terms.

ntpclient home page: http://doolittle.faludi.com/ntpclient/

To build on Linux, type "make".  Solaris and other Unix users will
probably need to adjust the Makefile slightly.  It's not complex.
For changing the system clock frequency, only the Linux adjtimex(2)
interface is implemented at this time.  Non-Linux systems can only
use ntpclient to measure time differences and set the system clock.

Usage: ntpclient [options]
options:
 -c count     stop after count time measurements (default 0 means go forever)
 -d           print diagnostics (feature can be disabled at compile time)
 -g goodness  causes ntpclient to stop after getting a result more accurate 
                   than goodness (microseconds, default 0 means go forever)
 -h hostname  (mandatory) NTP server host, against which to measure system time
 -i interval  check time every interval seconds (default 600)
 -l           attempt to lock local clock to server using adjtimex(2)
 -p port      local NTP client UDP port (default 0 means "any available")
 -r           replay analysis code based on stdin
 -s           simple clock set (implies -c 1)

Mortal users can use this program for monitoring, but not clock setting
(with the -s or -l switches).  The -l switch has only seen serious testing
in a low latency (less than 2 ms) Ethernet environment, although I also use
it successfully with a cable modem (latency about 15 ms).  Users in other
environments should study ntpclient's behavior, and be prepared to adjust
internal tuning parameters.  A long description of how and why to use
ntpclient is in the HOWTO file.  ntpclient always sends packets to the
server's UDP port 123.

The test.dat file has 200 lines of sample output.  Its first few lines,
with the output column headers that are shown when the -d option is
chosen, are:
 day   second     elapsed    stall     skew  dispersion  freq
51785 00180.386    1398.0     40.3  953773.9    793.5  -1240000
51785 00780.382    1358.0     41.3  954329.0    915.5  -1240000
51785 01380.381    1439.0     56.0  954871.3    915.5  -1240000

day, second: time of measurement, UTC, relative to Unix epoch (Jan 1, 1970)
elapsed:     total time from query to response (microseconds)
stall:       time the server reports that it sat on the request (microseconds)
skew:        difference between local time and server time (microseconds)
dispersion:  reported by server, see RFC-1305 (microseconds)
freq:        local clock frequency adjustment (Linux only, ppm*65536)

test.dat is suitable for piping into ntpclient -r.  I have over 200000
samples (lines) archived for study, that I don't include here.
They are generally spaced 10 minutes apart, representing over three
years of data logging (from a variety of machines, and not continuous,
unfortunately).

As a special, added bonus, I also include my adjtimex(1) program.
See its man page and the HOWTO file for more information.

envelope is a perl script that I have used for my lock studies.
It's kind of a hack and not worth documenting here.

Changes since the widely distributed ntpclient_2000_345 version:
 -- new -g option (has had limited testing)
 -- changed max frequency adjustment from 91 ppm to 150 ppm
 -- fixed "inconsistent" bug in phaselock.c triggered by large freq errors
 -- new files: HOWTO, adjtimex.c, adjtimex.1, rate.awk, log2date.pl
 -- minor source code cleanups
 -- source is now as 64-bit clean as practical; tested on Alpha
 -- optional patches provided by Andy Warner, see andyw.patch
 -- optional patches provided by Linksys, see linksys.patch
 -- removed unexplained and unreasonable 15020 day offset in date column

Bugs:
 -- Doesn't understand the LI (Leap second Indicator) field of an NTP packet
 -- Doesn't interact with adjtimex(2) status value

       - Larry Doolittle  <[e-mail]>