1ntp-refclock(8)             System Manager's Manual            ntp-refclock(8)
2
3
4

NAME

6       ntp-refclock  - measure offset of the system clock relative to a refer‐
7       ence clock
8
9

SYNOPSIS

11       ntp-refclock [OPTION]... 127.127.TYPE.UNIT [DRIVER-OPTION]...
12
13

DESCRIPTION

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
20       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
25       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
30
31       mode MODE
32
33       time1 FUDGE
34
35       time2 FUDGE
36
37       flag1 0|1
38
39       flag2 0|1
40
41       flag3 0|1
42
43       flag4 0|1
44
45               The  meaning  of  the options is specific to each driver and is
46               explained in their documentation.
47
48

OPTIONS

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
56       -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
60       -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
64       -c FILE Write  reference clock statistics (clockstats) to FILE. If FILE
65               is -, the statistics will be printed to the standard output.
66
67       -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
74       -p NUMBER
75               Specify phone NUMBER for modem drivers. This option may be used
76               multiple times to specify more than one number.
77
78       -d      Increase debug level.
79
80       -l      Print a list of drivers included in the ntp-refclock binary.
81
82       -v      Print version.
83
84       -h      Print a help message.
85
86

EXAMPLES

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
92       ntp-refclock -s /var/run/chrony-NMEA.sock 127.127.20.0 mode 80 time2 0.5
93
94       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
99       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
103       refclock SOCK /var/run/chrony-NMEA.sock refid NMEA delay 0.1 noselect
104       refclock PPS /dev/pps0 refid GPS lock NMEA
105
106       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
111       ntp-refclock -s /var/run/chrony-GPS.sock 127.127.20.0 mode 80 flag1 1 time2 0.5
112
113       In this case chrony.conf could specify just the SOCK  refclock  without
114       the noselect option:
115
116       refclock SOCK /var/run/chrony-GPS.sock refid GPS
117
118       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
122       [Unit]
123       Description=GPS reference clock
124       After=chronyd.service
125       BindsTo=chronyd.service
126
127       [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
134       [Install]
135       WantedBy=multi-user.target
136
137       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
140       KERNEL=="ttyS0", SUBSYSTEM=="tty", SYMLINK+="gps0"
141       KERNEL=="pps0", SUBSYSTEM=="pps", SYMLINK+="gpspps0"
142
143
144   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
148       ntp-refclock -s /var/run/chrony-DCFa.sock 127.127.8.0 mode 142 time2 0.034
149
150       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
157       The time source could be specified in chrony.conf as:
158
159       refclock SOCK /var/run/chrony-DCFa.sock refid DCFa delay 0.01
160
161       If the DCF77 receiver used the Meinberg time string format  instead  of
162       raw DCF pulses, the ntp-refclock command could be:
163
164       ntp-refclock -s /var/run/chrony-DCFa.sock 127.127.8.0 mode 2 time1 0.034
165
166

SEE ALSO

168       chrony.conf(5), chronyd(8), ldattach(8), systemd.service(5), udev(7)
169
170       Documentation for ntp reference clock drivers in /usr/share/doc/ntp-re‐
171       fclock/drivers/
172
173
174
175                                                               ntp-refclock(8)
Impressum