ntp-refclock - Man Page
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.
- -i INTERVAL
Set the minpoll and maxpoll values of the time source. This can be useful with drivers that produce samples at the source polling interval instead of the one-second driver timer or message rate of the device. Some drivers override this setting. The default value is 6 (64 seconds).
- -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/