ntp-refclock man page

ntp-refclock ā€” measure offset of the system clock relative to a reference clock

Synopsis

ntp-refclock [OPTION]... 127.127.TYPE.UNIT [DRIVER-OPTION]...

Description

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.

The reference clock is specified on the command line as an IPv4 pseudo address 127.127.TYPE.UNIT, where TYPE selects the driver and UNIT selects the device of the reference clock. The following driver options can be specified after the address:

mode MODE
time1 FUDGE
time2 FUDGE
flag1 0|1
flag2 0|1
flag3 0|1
flag4 0|1

The meaning of the options is specific to each driver and is explained in their documentation.

Options

-s SOCKET

Send the measurements to the chrony SOCK refclock driver listening on SOCKET. ntp-refclock needs to be started after chronyd. If this option is not used, the measurements will be printed to the standard output.

-u USER

Run as USER in order to drop the root privileges. The -h option prints the default user. This option is ignored if ntp-refclock is started under a non-root user.

-d DIR

Change the root directory of the process to DIR. The -h option prints the default root directory. This option is ignored if ntp-refclock is started under a non-root user.

-c FILE

Write reference clock statistics (clockstats) to FILE. If FILE is -, the statistics will be printed to the standard output.

-p NUMBER

Specify phone NUMBER for modem drivers. This option may be used multiple times to specify more than one number.

-d

Increase debug level.

-l

Print a list of drivers included in the ntp-refclock binary.

-v

Print version.

-h

Print a help message.

Examples

GPS_NMEA driver

With a GPS receiver connected to a serial port using the NMEA protocol, the ntp-refclock command could be:

ntp-refclock -s /var/run/chrony-NMEA.sock 127.127.20.0 mode 80 time2 0.5

The driver will use /dev/gps0 to access the serial device, which could be a symbolic link to /dev/ttyS0 for instance. The mode option selects the baud rate (115200 bps) and time2 specifies the delay of the received messages (0.5 seconds).

The time source needs to be specified in chrony.conf as a SOCK refclock. If the GPS receiver provides also a PPS signal, the configuration could be:

refclock SOCK /var/run/chrony-NMEA.sock refid NMEA delay 0.1 noselect
refclock PPS /dev/pps0 refid GPS lock NMEA

If the drivers have been compiled with PPS support, the PPS signal can be processed by the GPS_NMEA driver itself. If the flag1 option is set to 1, the driver will use /dev/gpspps0 to access the PPS device (which can link to /dev/pps0). The command could be:

ntp-refclock -s /var/run/chrony-GPS.sock 127.127.20.0 mode 80 flag1 1 time2 0.5

In this case chrony.conf could specify just the SOCK refclock without the noselect option:

refclock SOCK /var/run/chrony-GPS.sock refid GPS

A systemd unit file which attaches the PPS device with ldattach, creates the symbolic links and starts ntp-refclock automatically on boot after chronyd could be:

[Unit]
Description=GPS reference clock
After=chronyd.service
BindsTo=chronyd.service

[Service]
ExecStartPre=/bin/ln -sf pps0 /dev/gpspps0
ExecStartPre=/bin/ln -sf ttyS0 /dev/gps0
ExecStart=/bin/sh -c 'ldattach 18 /dev/ttyS0; \
ntp-refclock -s /var/run/chrony-GPS.sock 127.127.20.0 mode 80 time2 0.5 flag1 1'
ExecStopPost=/bin/rm -f /dev/gps0 /dev/gpspps0

[Install]
WantedBy=multi-user.target

On Linux, the symbolic links can be created automatically also by writing udev rules to a file in /etc/udev/rules.d/:

KERNEL=="ttyS0", SUBSYSTEM=="tty", SYMLINK+="gps0"
KERNEL=="pps0", SUBSYSTEM=="pps", SYMLINK+="gpspps0"

PARSE driver

With a DCF77 receiver connected to a serial port and sending raw DCF pulses, the ntp-refclock command could be:

ntp-refclock -s /var/run/chrony-DCFa.sock 127.127.8.0 mode 142 time2 0.034

The driver will use /dev/refclock-0 to access the serial device and /dev/refclockpps-0 to access the PPS device. The mode option selects a RAWDCF variant of the clock (type 14) and enables PPS (128 added to the mode). The time2 option specifies the offset of the PPS signal (34 milliseconds), which should correspond to the physical distance of the receiver from the DCF77 transmitter in Germany.

The time source could be specified in chrony.conf as:

refclock SOCK /var/run/chrony-DCFa.sock refid DCFa delay 0.01

If the DCF77 receiver used the Meinberg time string format instead of raw DCF pulses, the ntp-refclock command could be:

ntp-refclock -s /var/run/chrony-DCFa.sock 127.127.8.0 mode 2 time1 0.034

See Also

chrony.conf(5), chronyd(8), ldattach(8), systemd.service(5), udev(7)

Documentation for ntp reference clock drivers in /usr/share/doc/ntp-refclock/drivers/