doc: update man pages

doc/chrony.conf.adoc

@@ -166,11 +166,11 @@ accuracy of the measurements.
 The interleaved mode is compatible with servers that support only the basic
 mode, but peers must both support and have enabled the interleaved mode,
 otherwise the synchronisation will work only in one direction. Note that even
-servers that support the interleaved mode may respond in the basic mode as the
+servers that support the interleaved mode might respond in the basic mode as
-interleaved mode requires the servers to keep some state for each client and
+the interleaved mode requires the servers to keep some state for each client
-the state can be dropped when there are too many clients (e.g.
+and the state might be dropped when there are too many clients (e.g.
-<<clientloglimit,*clientloglimit*>> is too small), or it can be overwritten by
+<<clientloglimit,*clientloglimit*>> is too small), or it might be overwritten
-other clients that have the same IP address (e.g. computers behind NAT or
+by other clients that have the same IP address (e.g. computers behind NAT or
 someone sending requests with a spoofed source address). The *presend* option
 can be used to shorten the interval in which the server has to keep the state
 for this computer and be able to respond in the interleaved mode.
@@ -246,26 +246,33 @@ pool pool.ntp.org iburst maxsources 3
 
 [[peer]]*peer* _hostname_ [_option_]...::
 The syntax of this directive is identical to that for the <<server,*server*>>
-directive, except that it is used to specify an NTP peer rather than an NTP
+directive, except that it specifies a symmetric association with an NTP peer
-server.
+instead of a client/server association with an NTP server. A single symmetric
+association allows the peers to be both servers and clients to each other. This
+is mainly useful when the NTP implementation of the peer (e.g. *ntpd*) supports
+ephemeral symmetric associations and does not need to be configured with an
+address of this host. *chronyd* does not support ephemeral associations.
 +
 When a key is specified by the *key* option to enable authentication, both
-peers must be configured to use the same key and the same key number.
+peers must use the same key and the same key number.
 +
-Please note that NTP peers that are not configured with a key to enable
+Note that the symmetric mode is less secure than the client/server mode. A
-authentication are vulnerable to a denial-of-service attack. An attacker
+denial-of-service attack is possible on unauthenticated symmetric associations,
-knowing that NTP hosts A and B are peering with each other can send a packet
+i.e. when the peer was specified without the *key* option. An attacker who does
-with random timestamps to host A with source address of B which will set the
+not see network traffic between two hosts, but knows that they are peering with
-NTP state variables on A to the values sent by the attacker. Host A will then
+each other, can periodically send them unauthenticated packets with spoofed
-send on its next poll to B a packet with an origin timestamp that does not match
+source addresses in order to disrupt their NTP state and prevent them from
-the transmit timestamp of B and the packet will be dropped. If the attacker
+synchronising to each other. When the association is authenticated, an attacker
-does this periodically for both hosts, they will not be able to synchronise to
+who does see the network traffic, but cannot prevent the packets from reaching
-each other.
+the other host, can still disrupt the state by replaying old packets. The
-+
+attacker has effectively the same power as a man-in-the-middle attacker. A
-This attack can be prevented by enabling authentication with the *key* option,
+partial protection against this attack is implemented in *chronyd*, which can
-or by using the <<server,*server*>> directive on both sides to specify the other
+protect the peers if they are using the same polling interval and they never
-host as a server instead of a peer. The disadvantage of the *server* directive
+sent an authenticated packet with a timestamp from future, but it should not be
-is that it will double the network traffic between the two hosts.
+relied on as it is difficult to ensure the conditions are met. If two hosts
+should be able to synchronise to each other in both directions, it is
+recommended to use two separate client/server associations (specified by the
+<<server,*server*>> directive on both hosts) instead.
 
 [[initstepslew]]*initstepslew* _step-threshold_ [_hostname_]...::
 In normal operation, *chronyd* slews the time when it needs to adjust the
@@ -534,12 +541,12 @@ saved.
 An example of the directive is:
 +
 ----
-dumpdir @CHRONYVARDIR@
+dumpdir @CHRONYSOCKDIR@
 ----
 +
-A source whose reference ID (the IP address for IPv4 sources) is _1.2.3.4_
+A source whose IP address is _1.2.3.4_ would have its measurement history saved
-would have its measurement history saved in the file
+in the file _@CHRONYSOCKDIR@/1.2.3.4.dat_. History of reference clocks is saved
-_/var/lib/chrony/1.2.3.4.dat_.
+to files named by their reference ID in form of _refid:XXXXXXXX.dat_.
 
 [[dumponexit]]*dumponexit*::
 If this directive is present, it indicates that *chronyd* should save the
@@ -1036,25 +1043,20 @@ There is also a *deny all* directive with similar behaviour to the *allow all*
 directive.
 
 [[bindaddress]]*bindaddress* _address_::
-The *bindaddress* directive allows you to restrict the network interface to
+The *bindaddress* directive binds the socket on which *chronyd* listens for NTP
-which *chronyd* will listen for NTP requests. This provides an additional level
+requests to a local address of the computer. On systems other than Linux, the
-of access restriction above that available through the <<deny,*deny*>>
+address of the computer needs to be already configured when *chronyd* is
-mechanism.
+started.
 +
-Suppose you have a local network with addresses in the _192.168.1.0_
+An example of the use of the directive is:
-subnet together with an Internet connection. The network interface's IP
-address is _192.168.1.1_. Suppose you want to block all access through the
-Internet connection. You could add the line:
 +
 ----
 bindaddress 192.168.1.1
 ----
 +
-to the configuration file.
+Currently, for each of the IPv4 and IPv6 protocols, only one *bindaddress*
-+
+directive can be specified. Therefore, it is not useful on computers which
-For each of the IPv4 and IPv6 protocols, only one *bindaddress* directive can be
+should serve NTP on multiple network interfaces.
-specified. Therefore, it is not useful on computers which should serve NTP on
-multiple network interfaces.
 
 [[broadcast]]*broadcast* _interval_ _address_ [_port_]::
 The *broadcast* directive is used to declare a broadcast address to which
@@ -1173,6 +1175,23 @@ An example of the directive is:
 local stratum 10 orphan
 ----
 
+[[ntpsigndsocket]]*ntpsigndsocket* _directory_::
+This directive specifies the location of the Samba *ntp_signd* socket when it
+is running as a Domain Controller (DC). If *chronyd* is compiled with this
+feature, responses to MS-SNTP clients will be signed by the *smbd* daemon.
++
+Note that MS-SNTP requests are not authenticated and any client that is allowed
+to access the server by the <<allow,*allow*>> directive, or the
+<<chronyc.adoc#allow,*allow*>> command in *chronyc*, can get an MS-SNTP
+response signed with a trust account's password and try to crack the password
+in a brute-force attack. Access to the server should be carefully controlled.
++
+An example of the directive is:
++
+----
+ntpsigndsocket /var/lib/samba/ntp_signd
+----
+
 [[port]]*port* _port_::
 This option allows you to configure the port on which *chronyd* will listen for
 NTP requests. The port will be open only when an address is allowed by the
@@ -1282,16 +1301,17 @@ smoothtime 50000 0.01
 === Command and monitoring access
 
 [[bindcmdaddress]]*bindcmdaddress* _address_::
-The *bindcmdaddress* directive allows you to specify the network interface on
+The *bindcmdaddress* directive allows you to specify an IP address of an
-which *chronyd* will listen for monitoring command packets (issued by
+interface on which *chronyd* will listen for monitoring command packets (issued
-*chronyc*). This provides an additional level of access restriction above that
+by *chronyc*). On systems other than Linux, the address of the interface needs
-available through the <<cmddeny,*cmddeny*>> mechanism.
+to be already configured when *chronyd* is started.
 +
 This directive can also change the path of the Unix domain command socket,
 which is used by *chronyc* to send configuration commands. The socket must be
 in a directory that is accessible only by the root or _chrony_ user. The
 directory will be created on start if it does not exist. The compiled-in default
-path of the socket is _@CHRONYSOCKDIR@/chronyd.sock_.
+path of the socket is _@CHRONYSOCKDIR@/chronyd.sock_. The socket can be
+disabled by setting the path to _/_.
 +
 By default, *chronyd* binds to the loopback interface (with addresses
 _127.0.0.1_ and _::1_). This blocks all access except from localhost. To listen
@@ -1304,8 +1324,8 @@ bindcmdaddress ::
 +
 to the configuration file.
 +
-For each of the IPv4 and IPv6 protocols, only one *bindcmdaddress* directive can be
+For each of the IPv4, IPv6, and Unix domain protocols, only one
-specified.
+*bindcmdaddress* directive can be specified.
 +
 An example that sets the path of the Unix domain command socket is:
 +
@@ -1754,9 +1774,14 @@ capabilities should include _SOF_TIMESTAMPING_RAW_HARDWARE_,
 _SOF_TIMESTAMPING_TX_HARDWARE_, _SOF_TIMESTAMPING_RX_HARDWARE_, and the filter
 modes should have _HWTSTAMP_FILTER_ALL_. When *chronyd* is running, no other
 process should be working with the clock on the NIC. If no *hwtimestamp*
-directive is specified, *chronyd* will try to enable software timestamping.
+directive is specified, *chronyd* will try to use software (kernel)
-The source of the timestamps is indicated in the _measurements.log_ file if
+timestamping. With both hardware and software timestamping there are
-enabled by the <<log,*log measurements*>> directive.
+some limitations on which packets can be actually timestamped, e.g. transmit
+timestamping does not currently work with IPv6 packets using IP options and
+hardware receive timestamping does not work with packets from bridged
+interfaces. The timestamping used in measurements is indicated in the
+_measurements.log_ file if enabled by the <<log,*log measurements*>> directive,
+and the <<chronyc.adoc#ntpdata,*ntpdata*>> report in *chronyc*.
 +
 An example of the directive is:
 +
@@ -1824,23 +1849,9 @@ should result in lower and more consistent latency. It should not have
 significant impact on performance as *chronyd's* memory usage is modest. The
 *mlockall(2)* man page has more details.
 
-[[ntpsigndsocket]]*ntpsigndsocket* _directory_::
-This directive specifies the location of the Samba *ntp_signd* socket when it
-is running as a Domain Controller (DC). If *chronyd* is compiled with this
-feature, responses to MS-SNTP clients will be signed by the *smbd* daemon. Note
-that MS-SNTP requests are not authenticated, so any NTP client can get
-responses authenticated with passwords of users in the domain. Access to the
-server should be carefully controlled.
-+
-An example of the directive is:
-+
-----
-ntpsigndsocket /var/lib/samba/ntp_signd
-----
-
 [[pidfile]]*pidfile* _file_::
 *chronyd* always writes its process ID (PID) to a file, and checks this file on
-startup to see if another *chronyd* may already be running on the system. By
+startup to see if another *chronyd* might already be running on the system. By
 default, the file used is _@DEFAULT_PID_FILE@_. The *pidfile* directive
 allows the name to be changed, e.g.:
 +
@@ -2179,6 +2190,34 @@ For the system shutdown, *chronyd* should receive a SIGTERM several seconds
 before the final SIGKILL; the SIGTERM causes the measurement histories and RTC
 information to be saved.
 
+=== Public NTP server
+
+*chronyd* can be configured to operate as a public NTP server, e.g. to join the
+http://www.pool.ntp.org/en/join.html[pool.ntp.org] project. The configuration
+is similar to the NTP client with permanent connection, except it needs to
+allow client access from all addresses. It is recommended to handpick at least
+few good servers, and possibly combine them with a random selection of other
+servers in the pool. Rate limiting can be enabled to not waste too much
+bandwidth on misconfigured and broken NTP clients. The *-r* option with the
+*dumpdir* directive shortens the time for which *chronyd* will not serve time
+to its clients when it needs to be restarted for any reason.
+
+The configuration file might be:
+
+----
+server foo.example.net iburst
+server bar.example.net iburst
+server baz.example.net iburst
+pool pool.ntp.org iburst
+makestep 1.0 3
+rtcsync
+allow
+ratelimit interval 2 burst 10
+driftfile @CHRONYVARDIR@/drift
+dumpdir @CHRONYSOCKDIR@
+dumponexit
+----
+
 == SEE ALSO
 
 <<chronyc.adoc#,*chronyc(1)*>>, <<chronyd.adoc#,*chronyd(8)*>>

doc/chronyd.adoc

@@ -75,14 +75,15 @@ This option is similar to *-q*, but it will only print the offset without any
 corrections of the clock.
 
 *-r*::
-This option will reload sample histories for each of the servers and refclocks
+This option will try to reload and then delete files containing sample
-being used. These histories are created by using the
+histories for each of the servers and reference clocks being used. These
-<<chronyc.adoc#dump,*dump*>> command in *chronyc*, or by setting the
+histories are created by using the <<chronyc.adoc#dump,*dump*>> command in
-<<chrony.conf.adoc#dumponexit,*dumponexit*>> directive in the configuration
+*chronyc*, or by setting the <<chrony.conf.adoc#dumponexit,*dumponexit*>>
-file. This option is useful if you want to stop and restart *chronyd* briefly
+directive in the configuration file. This option is useful if you want to stop
-for any reason, e.g. to install a new version. However, it should be used only
+and restart *chronyd* briefly for any reason, e.g. to install a new version.
-on systems where the kernel can maintain clock compensation whilst not under
+However, it should be used only on systems where the kernel can maintain clock
-*chronyd*'s control (i.e. Linux, FreeBSD, NetBSD and Solaris).
+compensation whilst not under *chronyd*'s control (i.e. Linux, FreeBSD, NetBSD
+and Solaris).
 
 *-R*::
 When this option is used, the <<chrony.conf.adoc#initstepslew,*initstepslew*>>
@@ -161,4 +162,4 @@ https://chrony.tuxfamily.org/.
 
 == AUTHORS
 
-chrony was written by Richard Curnow, Miroslav Lichvar and others.
+chrony was written by Richard Curnow, Miroslav Lichvar, and others.