doc: improve and add more questions to FAQ

doc/faq.adoc

@@ -475,6 +475,64 @@ identically configured leap-smearing servers. Note that some clients can get
 leap seconds from other sources (e.g. with the `leapsectz` directive in
 `chrony`) and they will not work correctly with a leap smearing server.
 
+=== How should `chronyd` be configuration with `gpsd`?
+
+A GPS or other GNSS receiver can be used as a reference clock with `gpsd`. It
+can work as one or two separate time sources for each connected receiver. The
+first time source is based on timestamping of messages sent by the receiver.
+Typically, it is accurate to milliseconds. The other source is much more
+accurate. It is timestamping a pulse-per-second (PPS) signal, usually connected
+to a serial port (e.g. DCD pin) or GPIO pin.
+
+If the PPS signal is connected to the serial port which is receiving messages
+from the GPS/GNSS receiver, `gpsd` should detect and use it automatically. If
+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
+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:
+
+----
+# 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
+----
+
+Each option has 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
+  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
+  <<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 SHM 0 offset 0.5 delay 0.1 refid GPS
+----
+
 === Does `chrony` support PTP?
 
 No, the Precision Time Protocol (PTP) is not supported as a protocol for
@@ -498,6 +556,27 @@ transport for NTP messages (NTP over PTP) to enable hardware timestamping on
 hardware which can timestamp PTP packets only. It can be enabled by the
 `ptpport` directive.
 
+=== Why are client log records dropped before reaching `clientloglimit`?
+
+The number of dropped client log records reported by the `serverstats` command
+can be increasing before the number of clients reported by the `clients` command
+reaches the maximum value corresponding to the memory limit set by the
+`clientloglimit` directive.
+
+This is due to the design of the data structure keeping the client records. It
+is a hash table which can store only up to 16 colliding addresses per slot. If
+a slot has more collisions and the table already has the maximum size, the
+oldest record will be dropped and replaced by the new client.
+
+Note that the size of the table is always a power of two and it can only grow.
+The limit set by the `clientloglimit` directive takes into account that two
+copies of the table exist when it is being resized. This means the actual
+memory usage reported by `top` and other utilities can be significantly smaller
+than the limit even when the maximum number of records is used.
+
+The absolute maximum number of client records kept at the same time is
+16777216.
+
 === What happened to the `commandkey` and `generatecommandkey` directives?
 
 They were removed in version 2.2. Authentication is no longer supported in the
@@ -692,12 +771,14 @@ frequently, you can effectively disable the test by setting the
 `maxdelaydevratio` option to a very large value (e.g. 1000000), or speed up the
 recovery by increasing the clock error rate with the `maxclockerror` directive.
 
+[[using-pps-refclock]]
 === Using a PPS reference clock?
 
 A pulse-per-second (PPS) reference clock requires a non-PPS time source to
 determine which second of UTC corresponds to each pulse. If it is another
 reference clock specified with the `lock` option in the `refclock` directive,
-the offset between the two reference clocks must be smaller than 0.2 seconds in
+the offset between the two reference clocks must be smaller than 0.4 seconds
+(0.2 seconds with `chrony` versions before 4.1) in
 order for the PPS reference clock to work. With NMEA reference clocks it is
 common to have a larger offset. It needs to be corrected with the `offset`
 option.
@@ -716,7 +797,7 @@ foo.example.net             7   3   200     -2.991     16.141   -107us   492us
 
 the offset of the NMEA source would need to be increased by about 0.504
 seconds. It does not have to be very accurate. As long as the offset of the
-NMEA reference clock stays below 0.2 seconds, the PPS reference clock should be
+NMEA reference clock stays below the limit, the PPS reference clock should be
 able to determine the seconds corresponding to the pulses and allow the samples
 to be used for synchronisation.
 
@@ -772,6 +853,10 @@ in parentheses) on the `Reference ID` line.
 Only by the source code. See _cmdmon.c_ (`chronyd` side) and _client.c_
 (`chronyc` side).
 
+Note that this protocol is not compatible with the mode 6 or mode 7 protocol
+supported by `ntpd`, i.e. the `ntpq` or `ntpdc` utility cannot be used to
+monitor `chronyd`, and `chronyc` cannot be used to monitor `ntpd`.
+
 == Real-time clock issues
 
 === What is the real-time clock (RTC)?
@@ -898,6 +983,34 @@ timestamps (e.g. daemon timestamp vs kernel timestamp) for serving time and
 synchronisation of its own clock, which will cause the other computer to
 measure a significant offset.
 
+== Operation
+
+=== What clocks does `chronyd` use?
+
+There are several different clocks used by `chronyd`:
+
+* *System clock:* software clock maintained by the kernel. It is the main clock
+  used by applications running on the computer. It is synchronised by `chronyd`
+  to its NTP clock, unless started with the *-x* option.
+* *NTP clock:* software clock (virtual) based on the system clock and internal
+  to `chronyd`. It keeps the best estimate of the true time according to the
+  configured time sources, which is served to NTP clients unless time smoothing
+  is enabled by the *smoothtime* directive. The *System time* value in the
+  `tracking` report is the current offset between the system and NTP clock.
+* *Real-time clock (RTC):* hardware clock keeping time even when the
+  computer is turned off. It is used by the kernel to initialise the system
+  clock on boot and also by `chronyd` to compensate for its measured drift if
+  configured with the `rtcfile` directive and started with the `-s` option.
+  The clock can be kept accurate only by stepping enabled by the `rtcsync` or
+  `rtcautotrim` directive.
+* *Reference clock:* hardware clock used as a time source. It is specified by
+  the `refclock` directive.
+* *NIC clock (also known as PTP hardware clock):* hardware clock timestamping
+  packets received and transmitted by a network device specified by the
+  *hwtimestamp* directive. The clock is expected to be running free. It is not
+  synchronised by `chronyd`. Its offset is tracked relative to the NTP clock in
+  order to convert the hardware timestamps.
+
 == Operating systems
 
 === Does `chrony` support Windows?