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
27       selects 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       -p NUMBER
68               Specify phone NUMBER for modem drivers. This option may be used
69               multiple times to specify more than one number.
70
71       -d      Increase debug level.
72
73       -l      Print a list of drivers included in the ntp-refclock binary.
74
75       -v      Print version.
76
77       -h      Print a help message.
78
79

EXAMPLES

81   GPS_NMEA driver
82       With a GPS receiver connected to a serial port using the NMEA protocol,
83       the ntp-refclock command could be:
84
85       ntp-refclock -s /var/run/chrony-NMEA.sock 127.127.20.0 mode 80 time2 0.5
86
87       The driver will use /dev/gps0 to access the serial device, which  could
88       be  a symbolic link to /dev/ttyS0 for instance. The mode option selects
89       the baud rate (115200  bps)  and  time2  specifies  the  delay  of  the
90       received messages (0.5 seconds).
91
92       The  time  source  needs  to be specified in chrony.conf as a SOCK ref‐
93       clock. If the GPS receiver provides also a PPS signal,  the  configura‐
94       tion could be:
95
96       refclock SOCK /var/run/chrony-NMEA.sock refid NMEA delay 0.1 noselect
97       refclock PPS /dev/pps0 refid GPS lock NMEA
98
99       If  the drivers have been compiled with PPS support, the PPS signal can
100       be processed by the GPS_NMEA driver itself. If the flag1 option is  set
101       to  1, the driver will use /dev/gpspps0 to access the PPS device (which
102       can link to /dev/pps0). The command could be:
103
104       ntp-refclock -s /var/run/chrony-GPS.sock 127.127.20.0 mode 80 flag1 1 time2 0.5
105
106       In this case chrony.conf could specify just the SOCK  refclock  without
107       the noselect option:
108
109       refclock SOCK /var/run/chrony-GPS.sock refid GPS
110
111       A  systemd  unit file which attaches the PPS device with ldattach, cre‐
112       ates the symbolic links and starts ntp-refclock automatically  on  boot
113       after chronyd could be:
114
115       [Unit]
116       Description=GPS reference clock
117       After=chronyd.service
118       BindsTo=chronyd.service
119
120       [Service]
121       ExecStartPre=/bin/ln -sf pps0 /dev/gpspps0
122       ExecStartPre=/bin/ln -sf ttyS0 /dev/gps0
123       ExecStart=/bin/sh -c 'ldattach 18 /dev/ttyS0; \
124       ntp-refclock -s /var/run/chrony-GPS.sock 127.127.20.0 mode 80 time2 0.5 flag1 1'
125       ExecStopPost=/bin/rm -f /dev/gps0 /dev/gpspps0
126
127       [Install]
128       WantedBy=multi-user.target
129
130       On Linux, the symbolic links can be created automatically also by writ‐
131       ing udev rules to a file in /etc/udev/rules.d/:
132
133       KERNEL=="ttyS0", SUBSYSTEM=="tty", SYMLINK+="gps0"
134       KERNEL=="pps0", SUBSYSTEM=="pps", SYMLINK+="gpspps0"
135
136
137   PARSE driver
138       With a DCF77 receiver connected to a serial port and  sending  raw  DCF
139       pulses, the ntp-refclock command could be:
140
141       ntp-refclock -s /var/run/chrony-DCFa.sock 127.127.8.0 mode 142 time2 0.034
142
143       The  driver  will  use  /dev/refclock-0 to access the serial device and
144       /dev/refclockpps-0 to access the PPS device. The mode option selects  a
145       RAWDCF variant of the clock (type 14) and enables PPS (128 added to the
146       mode).  The time2 option specifies the offset of  the  PPS  signal  (34
147       milliseconds),  which should correspond to the physical distance of the
148       receiver from the DCF77 transmitter in Germany.
149
150       The time source could be specified in chrony.conf as:
151
152       refclock SOCK /var/run/chrony-DCFa.sock refid DCFa delay 0.01
153
154       If the DCF77 receiver used the Meinberg time string format  instead  of
155       raw DCF pulses, the ntp-refclock command could be:
156
157       ntp-refclock -s /var/run/chrony-DCFa.sock 127.127.8.0 mode 2 time1 0.034
158
159

SEE ALSO

161       chrony.conf(5), chronyd(8), ldattach(8), systemd.service(5), udev(7)
162
163       Documentation  for  ntp  reference clock drivers in /usr/share/doc/ntp-
164       refclock/drivers/
165
166
167
168                                                               ntp-refclock(8)