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.

diff --git a/doc/chrony.conf.adoc b/doc/chrony.conf.adoc
index 761d04207f8453dc9c8d1490419539bbd5ed1878..ffcaafb243a72e5cec61a881a14111449401fcec 100644 (file)
--- a/doc/chrony.conf.adoc
+++ b/doc/chrony.conf.adoc
@@ -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_::

diff --git a/doc/faq.adoc b/doc/faq.adoc
index f7da34f1aeb95632880362946ad700dd560a9dd1..1753ffa8cc6eb8ce0d2eb2c4a378c0da248d876a 100644 (file)
--- a/doc/faq.adoc
+++ b/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
 ----