diff --git a/doc/chrony.conf.adoc b/doc/chrony.conf.adoc index 761d042..ffcaafb 100644 --- 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 f7da34f..1753ffa 100644 --- 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 <> 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 ----