faraphel/chrony
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc: update man pages

Browse source
This commit is contained in:
Miroslav Lichvar 2016-11-28 16:02:51 +01:00
parent 633a007b7b
commit 6b3800cc94
2 changed files with 113 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

167
doc/chrony.conf.adoc
View file

@ -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
interleaved mode requires the servers to keep some state for each client and
the state can be dropped when there are too many clients (e.g.
<<clientloglimit,*clientloglimit*>> is too small), or it can be overwritten by
other clients that have the same IP address (e.g. computers behind NAT or
servers that support the interleaved mode might respond in the basic mode as
the interleaved mode requires the servers to keep some state for each client
and the state might be dropped when there are too many clients (e.g.
<<clientloglimit,*clientloglimit*>> is too small), or it might be overwritten
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
server.
directive, except that it specifies a symmetric association with an NTP peer
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
authentication are vulnerable to a denial-of-service attack. An attacker
knowing that NTP hosts A and B are peering with each other can send a packet
with random timestamps to host A with source address of B which will set the
NTP state variables on A to the values sent by the attacker. Host A will then
send on its next poll to B a packet with an origin timestamp that does not match
the transmit timestamp of B and the packet will be dropped. If the attacker
does this periodically for both hosts, they will not be able to synchronise to
each other.
+
This attack can be prevented by enabling authentication with the *key* option,
or by using the <<server,*server*>> directive on both sides to specify the other
host as a server instead of a peer. The disadvantage of the *server* directive
is that it will double the network traffic between the two hosts.
Note that the symmetric mode is less secure than the client/server mode. A
denial-of-service attack is possible on unauthenticated symmetric associations,
i.e. when the peer was specified without the *key* option. An attacker who does
not see network traffic between two hosts, but knows that they are peering with
each other, can periodically send them unauthenticated packets with spoofed
source addresses in order to disrupt their NTP state and prevent them from
synchronising to each other. When the association is authenticated, an attacker
who does see the network traffic, but cannot prevent the packets from reaching
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
partial protection against this attack is implemented in *chronyd*, which can
protect the peers if they are using the same polling interval and they never
sent an authenticated packet with a timestamp from future, but it should not be
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_
would have its measurement history saved in the file
_/var/lib/chrony/1.2.3.4.dat_.
A source whose IP address is _1.2.3.4_ would have its measurement history saved
in the file _@CHRONYSOCKDIR@/1.2.3.4.dat_. History of reference clocks is saved
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
which *chronyd* will listen for NTP requests. This provides an additional level
of access restriction above that available through the <<deny,*deny*>>
mechanism.
The *bindaddress* directive binds the socket on which *chronyd* listens for NTP
requests to a local address of the computer. On systems other than Linux, the
address of the computer needs to be already configured when *chronyd* is
started.
+
Suppose you have a local network with addresses in the _192.168.1.0_
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:
An example of the use of the directive is:
+
----
bindaddress 192.168.1.1
----
+
to the configuration file.
+
For each of the IPv4 and IPv6 protocols, only one *bindaddress* directive can be
specified. Therefore, it is not useful on computers which should serve NTP on
multiple network interfaces.
Currently, for each of the IPv4 and IPv6 protocols, only one *bindaddress*
directive can be 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
which *chronyd* will listen for monitoring command packets (issued by
*chronyc*). This provides an additional level of access restriction above that
available through the <<cmddeny,*cmddeny*>> mechanism.
The *bindcmdaddress* directive allows you to specify an IP address of an
interface on which *chronyd* will listen for monitoring command packets (issued
by *chronyc*). On systems other than Linux, the address of the interface needs
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
specified.
For each of the IPv4, IPv6, and Unix domain protocols, only one
*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.
The source of the timestamps is indicated in the _measurements.log_ file if
enabled by the <<log,*log measurements*>> directive.
directive is specified, *chronyd* will try to use software (kernel)
timestamping. With both hardware and software timestamping there are
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)*>>

19
doc/chronyd.adoc
View file

@ -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
being used. These histories are created by using the
<<chronyc.adoc#dump,*dump*>> command in *chronyc*, or by setting the
<<chrony.conf.adoc#dumponexit,*dumponexit*>> directive in the configuration
file. This option is useful if you want to stop and restart *chronyd* briefly
for any reason, e.g. to install a new version. However, it should be used only
on systems where the kernel can maintain clock compensation whilst not under
*chronyd*'s control (i.e. Linux, FreeBSD, NetBSD and Solaris).
This option will try to reload and then delete files containing sample
histories for each of the servers and reference clocks being used. These
histories are created by using the <<chronyc.adoc#dump,*dump*>> command in
*chronyc*, or by setting the <<chrony.conf.adoc#dumponexit,*dumponexit*>>
directive in the configuration file. This option is useful if you want to stop
and restart *chronyd* briefly for any reason, e.g. to install a new version.
However, it should be used only on systems where the kernel can maintain clock
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.