ntp-refclock
============

ntp-refclock is a wrapper for reference clock drivers included in the ntpd
daemon (http://www.ntp.org/), which enables other NTP implementations to use
the supported hardware reference clocks for synchronization of the system
clock.

It provides a minimal environment for the drivers to be able to run in a
separate process, measuring the offset of the system clock relative to the
reference clock and sending the measurements to another process controlling
the system clock.

Supported is chrony (https://chrony.tuxfamily.org) using the SOCK driver.
In other applications the measurements can be parsed from the standard output.

Installation
------------

Before building ntp-refclock, the ntp source code needs to be downloaded and
compiled in a minimal configuration which enables the drivers that should be
included in ntp-refclock. The openssl and threads support should be disabled.

For example, to build ntpd with all drivers except those that have a
counterpart in chrony, run:

$ ./configure --enable-all-clocks --enable-parse-clocks \
	--disable-ATOM --disable-SHM --disable-LOCAL-CLOCK \
	--without-crypto --without-threads --without-sntp
$ make

To build ntp-refclock, run:

$ make NTP_SRC=$NTPDIR DEFAULT_USER=$USER DEFAULT_ROOTDIR=$ROOTDIR

where $NTPDIR is the path to the compiled ntp source code, $USER is a user to
which ntp-refclock should switch by default after start in order to drop the
root privileges and $ROOTDIR is an empty directory to which should it change
its root directory. If no DEFAULT_USER and DEFAULT_ROOTDIR is specified, they
will be set to nobody and /var/empty respectively.

To install the ntp-refclock binary and manual page to /usr/local, run:

# make install NTP_SRC=$NTPDIR prefix=/usr/local

Usage
-----

The reference clock is specified on the ntp-refclock command line. The syntax
is similar to the server and fudge directives of ntpd. The -s option specifies
the location of the chronyd's socket where ntp-refclock should send the
measurements. It needs to be started after chronyd to be able to connect to
the socket. If multiple reference clocks are used, each clock needs to have
a separate ntp-refclock instance.

Some examples of using ntp-refclock with chronyd are included in the
ntp-refclock man page.

Author
------

Miroslav Lichvar <mlichvar@redhat.com>