doc: deprecate SHM refclocks in favor of SOCK
The NTP SHM refclock protocol has the following properties: - the memory segments have a predictable key (first segment 0x4e545030) - it's expected to work in any order of starting chronyd and the program providing samples to chronyd, i.e. both the consumer and producer need to be able to create the segment - the producer and consumer generally don't know under which user is the other side running (e.g. gpsd can create the segment as root and also as nobody after it drops root privileges) - there is no authentication of data provided via SHM - there is no way to restart the protocol This makes it difficult for chronyd to ensure it is receiving measurements from the process that the admin expects it to and not some other process that managed to create the segment before it was started. It's up to the admin to configure the system so that chronyd or the producer is started before untrusted applications or users can create the segment, or at least verify at some point later that the segment was created with the expected owner and permissions. There doesn't seem to be a backward-compatible fix of the protocol. Even if one side could detect the segment had a wrong owner or permissions, it wouldn't be able to tell the other side to reattach after recreating the segment with the expected owner and permissions, if it still had the permissions to do that. The protocol would need to specify which side is responsible for creating the segment and the start order would need to strictly follow that. As gpsd (likely the most common refclock source for chronyd) now supports in the latest version SOCK even for message-based timing, update the man page and FAQ to deprecate SHM in favor of SOCK.
This commit is contained in:
Miroslav Lichvar
parent
6fba5a4a7f
commit
bbeec7361c
2 changed files with 69 additions and 43 deletions
|
|
@ -473,16 +473,41 @@ instead.
|
|||
Examples:
|
||||
+
|
||||
----
|
||||
refclock PPS /dev/pps0 lock NMEA refid GPS
|
||||
refclock SHM 0 offset 0.5 delay 0.2 refid NMEA noselect
|
||||
refclock PPS /dev/pps0 lock NMEA refid GPS1
|
||||
refclock SOCK /var/run/chrony.clk.ttyS0.sock offset 0.5 delay 0.2 refid NMEA noselect
|
||||
refclock PPS /dev/pps1:clear refid GPS2
|
||||
----
|
||||
+
|
||||
*SOCK*:::
|
||||
Unix domain socket driver. This driver uses a datagram socket to receive
|
||||
samples from another application running on the system. The parameter is the
|
||||
path to the socket, which *chronyd* will create on start. The format of the
|
||||
messages is described in the _refclock_sock.c_ file in the chrony source code.
|
||||
+
|
||||
An application which supports the SOCK protocol is the *gpsd* daemon. It can
|
||||
provide accurate measurements using the receiver's PPS signal, and since
|
||||
version 3.25 also (much less accurate) measurements based on the timing of
|
||||
serial data (e.g. NMEA), which can be useful when the receiver does not provide
|
||||
a PPS signal, or it cannot be connected to the computer. The paths where *gpsd*
|
||||
expects the sockets to be created by *chronyd* are described in the *gpsd(8)*
|
||||
man page. Note that *gpsd* needs to be started after *chronyd* in order to
|
||||
connect to the socket.
|
||||
+
|
||||
Examples:
|
||||
+
|
||||
----
|
||||
refclock SOCK /var/run/chrony.ttyS0.sock refid GPS1 poll 2 filter 4
|
||||
refclock SOCK /var/run/chrony.clk.ttyUSB0.sock refid GPS2 offset 0.2 delay 0.1
|
||||
----
|
||||
+
|
||||
*SHM*:::
|
||||
NTP shared memory driver. This driver uses a shared memory segment to receive
|
||||
samples from another process (e.g. *gpsd*). The parameter is the number of the
|
||||
shared memory segment, typically a small number like 0, 1, 2, or 3. The driver
|
||||
supports the following option:
|
||||
NTP shared memory driver. This driver implements the protocol of the *ntpd*
|
||||
driver type 28. It is functionally similar to the SOCK driver, but uses a
|
||||
shared memory segment instead of a socket. The parameter is the unit number,
|
||||
typically a small number like 0, 1, 2, or 3, from which is derived the key of
|
||||
the memory segment as 0x4e545030 + unit.
|
||||
+
|
||||
The driver supports the following option:
|
||||
+
|
||||
*perm*=_mode_::::
|
||||
This option specifies the permissions of the shared memory segment created by
|
||||
|
|
@ -490,6 +515,16 @@ This option specifies the permissions of the shared memory segment created by
|
|||
(read-write access for owner only).
|
||||
{blank}:::
|
||||
+
|
||||
Unlike with the SOCK driver, there is no prescribed order of starting *chronyd*
|
||||
and the program providing measurements. Both are expected to create the memory
|
||||
segment if it does not exist. *chronyd* will attach to an existing segment even
|
||||
if it has a different owner than root or different permissions than the
|
||||
permissions specified by the *perm* option. The segment needs to be created
|
||||
before untrusted applications or users can execute code to prevent an attacker
|
||||
from feeding *chronyd* with false measurements. The owner and permissions of
|
||||
the segment can be verified with the *ipcs -m* command. For this reason, the
|
||||
SHM driver is deprecated in favor of SOCK.
|
||||
+
|
||||
Examples:
|
||||
+
|
||||
----
|
||||
|
|
@ -497,23 +532,6 @@ refclock SHM 0 poll 3 refid GPS1
|
|||
refclock SHM 1:perm=0644 refid GPS2
|
||||
----
|
||||
+
|
||||
*SOCK*:::
|
||||
Unix domain socket driver. It is similar to the SHM driver, but samples are
|
||||
received from a Unix domain socket instead of shared memory and the messages
|
||||
have a different format. The parameter is the path to the socket, which
|
||||
*chronyd* creates on start. An advantage over the SHM driver is that SOCK does
|
||||
not require polling and it can receive PPS samples with incomplete time. The
|
||||
format of the messages is described in the _refclock_sock.c_ file in the chrony
|
||||
source code.
|
||||
+
|
||||
An application which supports the SOCK protocol is the *gpsd* daemon. The path
|
||||
where *gpsd* expects the socket to be created is described in the *gpsd(8)* man
|
||||
page. For example:
|
||||
+
|
||||
----
|
||||
refclock SOCK /var/run/chrony.ttyS0.sock
|
||||
----
|
||||
+
|
||||
*PHC*:::
|
||||
PTP hardware clock (PHC) driver. The parameter is the path to the device of
|
||||
the PTP clock which should be used as a time source. If the clock is kept in
|
||||
|
|
@ -923,7 +941,7 @@ As an example, the following configuration using the default *mix* mode:
|
|||
server foo.example.net nts
|
||||
server bar.example.net nts
|
||||
server baz.example.net
|
||||
refclock SHM 0
|
||||
refclock SOCK /var/run/chrony.ttyS0.sock
|
||||
----
|
||||
+
|
||||
is equivalent to the following configuration using the *ignore* mode:
|
||||
|
|
@ -933,7 +951,7 @@ authselectmode ignore
|
|||
server foo.example.net nts require trust
|
||||
server bar.example.net nts require trust
|
||||
server baz.example.net
|
||||
refclock SHM 0 require trust
|
||||
refclock /var/run/chrony.ttyS0.sock require trust
|
||||
----
|
||||
|
||||
[[combinelimit]]*combinelimit* _limit_::
|
||||
|
|
|
|||
44
doc/faq.adoc
44
doc/faq.adoc
|
|
@ -499,45 +499,53 @@ it is connected to a GPIO pin, or another serial port, the PPS device needs to
|
|||
be specified on the command line as an additional data source. On Linux, the
|
||||
`ldattach` utility can be used to create a PPS device for a serial device.
|
||||
|
||||
The message-based time source provided by `gpsd` is specified as a `SHM 0`
|
||||
refclock, or other even number if `gpsd` is configured with multiple receivers.
|
||||
|
||||
The PPS-based time source is specified as a `SHM 1` refclock (or other odd
|
||||
number), or `SOCK /var/run/chrony.DEV.sock` where `DEV` is the name of the
|
||||
The PPS-based time source provided by `gpsd` is available as a `SHM 1`
|
||||
refclock, or other odd number if `gpsd` is configured with multiple receivers,
|
||||
and also as `SOCK /var/run/chrony.DEV.sock` where `DEV` is the name of the
|
||||
serial device (e.g. ttyS0).
|
||||
|
||||
With `chronyd` and `gpsd` both supporting PPS, and `gpsd` providing two
|
||||
different refclocks for PPS, there are three different recommended
|
||||
configurations:
|
||||
The message-based time source is available as a `SHM 0` refclock (or other even
|
||||
number) and since `gpsd` version 3.25 also as
|
||||
`SOCK /var/run/chrony.clk.DEV.sock` where `DEV` is the name of the serial
|
||||
device.
|
||||
|
||||
The SOCK refclocks should be preferred over SHM for better security
|
||||
(the shared memory segment needs to be created by `chronyd` or `gpsd` with an
|
||||
expected owner and permissions before an untrusted application or user has a
|
||||
chance to create its own in order to feed `chronyd` with false measurements).
|
||||
`gpsd` needs to be started after `chronyd` in order to connect to the socket.
|
||||
|
||||
With `chronyd` and `gpsd` both supporting PPS, there are two different
|
||||
recommended configurations:
|
||||
|
||||
----
|
||||
# First option
|
||||
refclock SOCK /var/run/chrony.ttyS0.sock refid GPS
|
||||
|
||||
# Second option
|
||||
refclock SHM 1 refid GPS
|
||||
|
||||
# Third option
|
||||
refclock PPS /dev/pps0 lock NMEA refid GPS
|
||||
refclock SHM 0 offset 0.5 delay 0.1 refid NMEA noselect
|
||||
refclock SOCK /var/run/chrony.clk.ttyS0.sock offset 0.5 delay 0.1 refid NMEA noselect
|
||||
----
|
||||
|
||||
Each option has some advantages:
|
||||
They both have some advantages:
|
||||
|
||||
* `SOCK` does not use polling (i.e. it can get samples earlier than `SHM`),
|
||||
but it requires `gpsd` to be started after `chronyd` in order to connect to
|
||||
its socket
|
||||
* `SOCK` and `SHM 1` can be more accurate than `PPS` if `gpsd` corrects for the
|
||||
* `SOCK` can be more accurate than `PPS` if `gpsd` corrects for the
|
||||
sawtooth error provided by the receiver in serial data
|
||||
* `PPS` can be used with higher PPS rates (specified by the `rate` option),
|
||||
but it requires a second refclock or another time source to pair pulses
|
||||
with seconds, and the `SHM 0` offset needs to be specified
|
||||
with seconds, and the `SOCK` offset needs to be specified
|
||||
<<using-pps-refclock,correctly>> to compensate for the message delay, while
|
||||
`gpsd` can apply HW-specific information
|
||||
|
||||
If the PPS signal is not available, or cannot be used for some reason, the only
|
||||
option is the message-based timing
|
||||
|
||||
----
|
||||
refclock SOCK /var/run/chrony.clk.ttyS0.sock offset 0.5 delay 0.1 refid GPS
|
||||
----
|
||||
|
||||
or the SHM equivalent if using `gpsd` version before 3.25
|
||||
|
||||
----
|
||||
refclock SHM 0 offset 0.5 delay 0.1 refid GPS
|
||||
----
|
||||
|
|
|
|||
Loading…
Reference in a new issue