ntp-refclock(8)

📦 version 0.7, in fedora 43, fedora 44

✨ NAME ✨

ntp-refclock — measure the offset of the system clock relative to a reference clock 💅

🎀 SYNOPSIS 🎀

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

🌸 DESCRIPTION 🌸

Okay so bestie, <pink>ntp-refclock</pink> is a wrapper for the reference clock drivers that ship inside the ntpd daemon (http://www.ntp.org/). What that means: it lets other NTP implementations use all those supported hardware reference clocks to sync up the system clock. iconic behaviour, honestly.

It gives the drivers a minimal environment so they can run as their very own separate process — measuring the offset of the system clock relative to the reference clock, and then sending those measurements off to another process that's the one actually controlling the system clock. teamwork makes the dream work 🫶

You tell it which reference clock you want by handing it an IPv4 pseudo address on the command line, shaped like this:

127.127.TYPE.UNIT
  • TYPE — picks the driver
  • UNIT — picks the device of the reference clock

And then you can sprinkle these driver options right after the address:

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

What those actually mean is specific to each driver — the driver docs explain it, so go check those. iykyk 📖

💖 OPTIONS 💖

  • -s SOCKET — Send the measurements over to the chrony SOCK refclock driver that's listening on SOCKET. Heads up: <pink>ntp-refclock</pink> has to be started after chronyd. If you don't use this option, the measurements just get printed to the standard output instead.
  • -u USER — Run as USER to drop those root privileges. The -h option prints the default user. This one gets 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. Also 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 get printed to the standard output instead. 💅
  • -i INTERVAL — Set the minpoll and maxpoll values of the time source. Super useful with drivers that produce samples at the source polling interval rather than the one-second driver timer or the message rate of the device. Some drivers override this setting, so don't be shocked. Default value is 6 (that's 64 seconds).
  • -p AT-COMMAND — Specify the AT command that modem drivers should send to the modem to dial a phone number ☎️. You can repeat this option up to 10 times to specify multiple phone numbers.
  • -d — Increase debug level. 🐛
  • -l — Print a list of drivers included in the ntp-refclock binary.
  • -v — Print version.
  • -h — Print a help message.
Not a typo, bestie: there are two -d entries in the original — -d DIR takes an argument, and plain -d bumps the debug level. Keep them straight. 🙈

🌈 EXAMPLES 🌈

🛰️ GPS_NMEA driver

Got a GPS receiver plugged into a serial port speaking the NMEA protocol? Then your <pink>ntp-refclock</pink> 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 (that's 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 your GPS receiver also provides 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. Set the flag1 option to 1 and 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 that 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 that 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, those symbolic links can also be created automatically 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

DCF77 receiver connected to a serial port and sending raw DCF pulses? Then your <pink>ntp-refclock</pink> 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 🦋

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

okay that's the whole page, bestie, you ate it 💅 this one comes out of the System Manager's Manual and signs off as <rainbow>ntp-refclock(8)</rainbow> — go sync something, you've got this 👑💖

📦 where this page comes from