1ntp-refclock(8) System Manager's Manual ntp-refclock(8)
2
6 ntp-refclock - measure offset of the system clock relative to a refer‐
7 ence clock
8
11 ntp-refclock [OPTION]... 127.127.TYPE.UNIT [DRIVER-OPTION]...
12
15 ntp-refclock is a wrapper for reference clock drivers included in the
16 ntpd daemon <http://www.ntp.org/>, which enables other NTP implementa‐
17 tions to use the supported hardware reference clocks for synchroniza‐
18 tion of the system clock.
19 It provides a minimal environment for the drivers to be able to run in
21 a separate process, measuring the offset of the system clock relative
22 to the reference clock and sending the measurements to another process
23 controlling the system clock.
24 The reference clock is specified on the command line as an IPv4 pseudo
26 address 127.127.TYPE.UNIT, where TYPE selects the driver and UNIT se‐
27 lects the device of the reference clock. The following driver options
28 can be specified after the address:
29 mode MODE
32 time1 FUDGE
34 time2 FUDGE
36 flag1 0|1
38 flag2 0|1
40 flag3 0|1
42 flag4 0|1
44 The meaning of the options is specific to each driver and is
46 explained in their documentation.
47
50 -s SOCKET
51 Send the measurements to the chrony SOCK refclock driver lis‐
52 tening on SOCKET. ntp-refclock needs to be started after
53 chronyd. If this option is not used, the measurements will be
54 printed to the standard output.
55 -u USER Run as USER in order to drop the root privileges. The -h option
57 prints the default user. This option is ignored if ntp-refclock
58 is started under a non-root user.
59 -d DIR Change the root directory of the process to DIR. The -h option
61 prints the default root directory. This option is ignored if
62 ntp-refclock is started under a non-root user.
63 -c FILE Write reference clock statistics (clockstats) to FILE. If FILE
65 is -, the statistics will be printed to the standard output.
66 -i INTERVAL
68 Set the minpoll and maxpoll values of the time source. This can
69 be useful with drivers that produce samples at the source
70 polling interval instead of the one-second driver timer or mes‐
71 sage rate of the device. Some drivers override this setting.
72 The default value is 6 (64 seconds).
73 -p NUMBER
75 Specify phone NUMBER for modem drivers. This option may be used
76 multiple times to specify more than one number.
77 -d Increase debug level.
79 -l Print a list of drivers included in the ntp-refclock binary.
81 -v Print version.
83 -h Print a help message.
85
88 GPS_NMEA driver
89 With a GPS receiver connected to a serial port using the NMEA protocol,
90 the ntp-refclock command could be:
91 ntp-refclock -s /var/run/chrony-NMEA.sock 127.127.20.0 mode 80 time2 0.5
93 The driver will use /dev/gps0 to access the serial device, which could
95 be a symbolic link to /dev/ttyS0 for instance. The mode option selects
96 the baud rate (115200 bps) and time2 specifies the delay of the re‐
97 ceived messages (0.5 seconds).
98 The time source needs to be specified in chrony.conf as a SOCK ref‐
100 clock. If the GPS receiver provides also a PPS signal, the configura‐
101 tion could be:
102 refclock SOCK /var/run/chrony-NMEA.sock refid NMEA delay 0.1 noselect
104 refclock PPS /dev/pps0 refid GPS lock NMEA
105 If the drivers have been compiled with PPS support, the PPS signal can
107 be processed by the GPS_NMEA driver itself. If the flag1 option is set
108 to 1, the driver will use /dev/gpspps0 to access the PPS device (which
109 can link to /dev/pps0). The command could be:
110 ntp-refclock -s /var/run/chrony-GPS.sock 127.127.20.0 mode 80 flag1 1 time2 0.5
112 In this case chrony.conf could specify just the SOCK refclock without
114 the noselect option:
115 refclock SOCK /var/run/chrony-GPS.sock refid GPS
117 A systemd unit file which attaches the PPS device with ldattach, cre‐
119 ates the symbolic links and starts ntp-refclock automatically on boot
120 after chronyd could be:
121 [Unit]
123 Description=GPS reference clock
124 After=chronyd.service
125 BindsTo=chronyd.service
126 [Service]
128 ExecStartPre=/bin/ln -sf pps0 /dev/gpspps0
129 ExecStartPre=/bin/ln -sf ttyS0 /dev/gps0
130 ExecStart=/bin/sh -c 'ldattach 18 /dev/ttyS0; \
131 ntp-refclock -s /var/run/chrony-GPS.sock 127.127.20.0 mode 80 time2 0.5 flag1 1'
132 ExecStopPost=/bin/rm -f /dev/gps0 /dev/gpspps0
133 [Install]
135 WantedBy=multi-user.target
136 On Linux, the symbolic links can be created automatically also by writ‐
138 ing udev rules to a file in /etc/udev/rules.d/:
139 KERNEL=="ttyS0", SUBSYSTEM=="tty", SYMLINK+="gps0"
141 KERNEL=="pps0", SUBSYSTEM=="pps", SYMLINK+="gpspps0"
142 PARSE driver
145 With a DCF77 receiver connected to a serial port and sending raw DCF
146 pulses, the ntp-refclock command could be:
147 ntp-refclock -s /var/run/chrony-DCFa.sock 127.127.8.0 mode 142 time2 0.034
149 The driver will use /dev/refclock-0 to access the serial device and
151 /dev/refclockpps-0 to access the PPS device. The mode option selects a
152 RAWDCF variant of the clock (type 14) and enables PPS (128 added to the
153 mode). The time2 option specifies the offset of the PPS signal (34
154 milliseconds), which should correspond to the physical distance of the
155 receiver from the DCF77 transmitter in Germany.
156 The time source could be specified in chrony.conf as:
158 refclock SOCK /var/run/chrony-DCFa.sock refid DCFa delay 0.01
160 If the DCF77 receiver used the Meinberg time string format instead of
162 raw DCF pulses, the ntp-refclock command could be:
163 ntp-refclock -s /var/run/chrony-DCFa.sock 127.127.8.0 mode 2 time1 0.034
165
168 chrony.conf(5), chronyd(8), ldattach(8), systemd.service(5), udev(7)
169 Documentation for ntp reference clock drivers in /usr/share/doc/ntp-re‐
171 fclock/drivers/
172 ntp-refclock(8)