Table of Contents
ntpclient is an NTP client for UNIX-like systems, RFC 1305 and RFC 4330. Its functionality is a small subset of ntpd, chrony, OpenNTPd, and xntpd. Since it is much smaller, it is also more relevant for embedded systems in need of only a client.
All arguments are optional, ntpclient defaults to use
Usage: ntpclient [options] [SERVER] -c count Stop after count time measurements. Default: 0 (forever) -d Debug, or diagnostics mode Possible to enable more at compile -f frequency Initialize the frequency offset. Linux only, requires root -g goodness Stop after getting a result more accurate than goodness msec, microseconds. Default: 0 (forever) -h Show summary of command line options and exit -i interval Check time every interval seconds. Default: 600 -l Attempt to lock local clock to server using adjtimex(2) -L Use syslog instead of stdout for log messages, enabled by default when started as root -n Don't fork. Prevents ntpclient from daemonizing by default Only when running as root, does nothing for regular users Use -L with this to use syslog as well, for Finit + systemd -p port NTP client UDP port. Default: 0 ("any available") -q min_delay Minimum packet delay for transaction (default 800 microseconds) -s Simple clock set, implies -c 1 unliess -l is also set -t Trust network and server, no RFC-4330 recommended validation -v Be verbose. This option will cause time sync events, hostname lookup errors and program version to be displayed -V Display version and copyright information SERVER Optional NTP server to sync with, default: pool.ntp.org
Mortal users can use this program for monitoring, but not clock setting
-l switches). The
-l switch is designed to be
robust in any network environment, but has seen the most extensive
testing in a low latency (less than 2 ms) Ethernet environment. 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.
One commonly needed tuning parameter for lock mode is
shortest possible round-trip transaction time. This can be set with the
-q switch. The historical default of 800 microseconds
was good for local Ethernet hardware a few years ago. If it is set too
high, you will get a lot of "inconsistent" lines in the log file when
time locking (
-l switch). The only true future-proof value is 0, but
that will cause the local time to wander more than it should. Setting
it to 200 is recommended on an end client.
test.dat file that is part of the source distribution 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 36765 00180.386 1398.0 40.3 953773.9 793.5 -1240000 36765 00780.382 1358.0 41.3 954329.0 915.5 -1240000 36765 01380.381 1439.0 56.0 954871.3 915.5 -1240000
- day, second: time of measurement, UTC, relative to NTP epoch (Jan 1, 1900)
- 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)
ntclient performs a series of sanity checks on UDP packets received, as
recommended by RFC 4330. If it fails one of these tests, the line
described above is replaced by
36765 01380.381 rejected packet or, if
--enable-debug was selected at
configure, one of:
36765 01380.381 rejected packet: LI==3 36765 01380.381 rejected packet: VN<3 36765 01380.381 rejected packet: MODE!=3 36765 01380.381 rejected packet: ORG!=sent 36765 01380.381 rejected packet: XMT==0 36765 01380.381 rejected packet: abs(DELAY)>65536 36765 01380.381 rejected packet: abs(DISP)>65536 36765 01380.381 rejected packet: STRATUM==0
To see the actual values of the rejected packet, start ntpclient with
-d option; this will give a human-readable printout of every
packet received, including the rejected ones. To skip these checks, use
test.dat is suitable for piping into ntpclient -r.
There are more than 200000 samples (lines) archived for study. They are
generally spaced 10 minutes apart, representing over three years of data
logging (from a variety of machines, and not continuous, unfortunately).
If you are interested, contact Larry.
Also included is a version of the
adjtimex(1) tool. See its man page
and the HowTo file for more information.
Another tool is
envelope, which is a perl script that was used for the
lock studies. It's kind of a hack and not worth documenting here.
Some really old Linux systems (e.g., Red Hat EL-3.0 and Ubuntu 4.10)
have a totally broken POSIX
clock_settime() implementation. If you
get the following with ntpclient -s:
clock_settime: Invalid argument
configure --enable-obsolete. Linux systems that are even older
will not even compile without that switch set.
- Doesn't understand the LI (Leap second Indicator) field of an NTP packet
- Doesn't interact with
- Cannot query multiple servers
- Requires Linux
select()semantics, where timeout value is modified
Adherence to RFC 4330 chapter 10, Best practices:
- Enforced, unless someone tinkers with the source code
- No backoff, but no retry either; this isn't TCP
- Not in scope for the upstream source
- Defaults to pool.ntp.org, but is configurable
- Not in scope for the upstream source
- Supported, connection to server reopened once a day
- Not supported (scary opportunity to DOS the client)
ntpclient uses the GNU configure & build system:
The GNU build system use
/usr/local as the default install prefix. In
many cases this is useful, but many users expect
./configure --prefix=/usr make sudo make install-strip
The last command installs, there is also a possiblity to uninstall all files using:
sudo make uninstall
For changing the system clock frequency, only the Linux
interface is implemented at this time. Non-Linux systems can only use
ntpclient to measure time differences and set the system clock, by way
of the POSIX 1003.1-2001 standard, the routines
clock_settime(). Also, see section Bugs, below.
There are a few compile-time configurations possible. E.g., for older Linux kernels, before the tickless erea (pre 3.0), you want to:
However, first try without changing the default. That gives you a full-
ntpclient that uses modern POSIX time functions and works
reasonably well with any Linux kernel.
Solaris and other UNIX users may need to adjust the
For other options, see ./configure --help
Building from GIT
If you want to contribute, or try out the latest unreleased features, here is a few things to know about GNU build system:
configure.acand a per-directory
Makefile.amare key files
Makefile.inare generated from
autogen.sh, they are not stored in GIT but automatically generated for the release tarballs
Makefileis generated by
To build from GIT you first need to clone the repository and run the
autogen.sh script. This requires
autoconf to be
installed on your system.
git clone https://github.com/troglobit/ntpclient.git cd ntpclient/ ./autogen.sh ./configure && make
Remember: GIT sources are a moving target and are not recommended for production systems, unless you know what you are doing!
Origin & References
This fork at GitHub is maintained by Joachim Nilsson and adds a few features like syslog, background daemon, IPv6, and systemd support. As well as a few other small things.