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.

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
 ----