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

doc: improve chrony.conf man page

Browse source
This commit is contained in:
Miroslav Lichvar 2021-04-07 16:37:11 +02:00
parent 69aa2eff99
commit 4f0dd72cf0
1 changed files with 94 additions and 87 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

181
doc/chrony.conf.adoc
View file

@ -131,9 +131,9 @@ of the messages was delayed the measurement error is likely to be substantial.
For small variations in the round-trip delay, *chronyd* uses a weighting scheme For small variations in the round-trip delay, *chronyd* uses a weighting scheme
when processing the measurements. However, beyond a certain level of delay the when processing the measurements. However, beyond a certain level of delay the
measurements are likely to be so corrupted as to be useless. (This is measurements are likely to be so corrupted as to be useless. (This is
particularly so on dial-up or other slow links, where a long delay probably particularly so on wireless networks and other slow links, where a long delay
indicates a highly asymmetric delay caused by the response waiting behind a lot probably indicates a highly asymmetric delay caused by the response waiting
of packets related to a download of some sort). behind a lot of packets related to a download of some sort).
+ +
If the user knows that round trip delays above a certain level should cause the If the user knows that round trip delays above a certain level should cause the
measurement to be ignored, this level can be defined with the *maxdelay* measurement to be ignored, this level can be defined with the *maxdelay*
@ -144,7 +144,7 @@ round-trip delay of 0.3 seconds or more should be ignored. The default value is
This option is similar to the *maxdelay* option above. *chronyd* keeps a record This option is similar to the *maxdelay* option above. *chronyd* keeps a record
of the minimum round-trip delay amongst the previous measurements that it has of the minimum round-trip delay amongst the previous measurements that it has
buffered. If a measurement has a round trip delay that is greater than the buffered. If a measurement has a round trip delay that is greater than the
maxdelayratio times the minimum delay, it will be rejected. specified ratio times the minimum delay, it will be rejected.
*maxdelaydevratio* _ratio_::: *maxdelaydevratio* _ratio_:::
If a measurement has a ratio of the increase in the round-trip delay from the If a measurement has a ratio of the increase in the round-trip delay from the
minimum delay amongst the previous measurements to the standard deviation of minimum delay amongst the previous measurements to the standard deviation of
@ -267,7 +267,7 @@ will send two extra packets instead of one.
When the synchronisation source is selected from available sources, sources When the synchronisation source is selected from available sources, sources
with lower stratum are normally slightly preferred. This option can be used to with lower stratum are normally slightly preferred. This option can be used to
increase stratum of the source to the specified minimum, so *chronyd* will increase stratum of the source to the specified minimum, so *chronyd* will
avoid selecting that source. This is useful with low stratum sources that are avoid selecting that source. This is useful with low-stratum sources that are
known to be unreliable or inaccurate and which should be used only when other known to be unreliable or inaccurate and which should be used only when other
sources are unreachable. sources are unreachable.
*version* _version_::: *version* _version_:::
@ -347,19 +347,8 @@ recommended to use two separate client/server associations (specified by the
<<server,*server*>> directive on both hosts) instead. <<server,*server*>> directive on both hosts) instead.
[[initstepslew]]*initstepslew* _step-threshold_ [_hostname_]...:: [[initstepslew]]*initstepslew* _step-threshold_ [_hostname_]...::
In normal operation, *chronyd* slews the time when it needs to adjust the (This directive is deprecated in favour of the <<makestep,*makestep*>>
system clock. For example, to correct a system clock which is 1 second slow, directive.)
*chronyd* slightly increases the amount by which the system clock is advanced
on each clock interrupt, until the error is removed. Note that at no time does
time run backwards with this method.
+
On most Unix systems it is not desirable to step the system clock, because many
programs rely on time advancing monotonically forwards.
+
When the *chronyd* daemon is initially started, it is possible that the system
clock is considerably in error. Attempting to correct such an error by slewing
might not be sensible, since it might take several hours to correct the error by
this means.
+ +
The purpose of the *initstepslew* directive is to allow *chronyd* to make a The purpose of the *initstepslew* directive is to allow *chronyd* to make a
rapid measurement of the system clock error at boot time, and to correct the rapid measurement of the system clock error at boot time, and to correct the
@ -380,29 +369,30 @@ error. *chronyd* then enters its normal operating mode.
An example of the use of the directive is: An example of the use of the directive is:
+ +
---- ----
initstepslew 30 foo.example.net bar.example.net initstepslew 30 foo.example.net bar.example.net baz.example.net
---- ----
+ +
where 2 NTP servers are used to make the measurement. The _30_ indicates that where 3 NTP servers are used to make the measurement. The _30_ indicates that
if the system's error is found to be 30 seconds or less, a slew will be used to if the system's error is found to be 30 seconds or less, a slew will be used to
correct it; if the error is above 30 seconds, a step will be used. correct it; if the error is above 30 seconds, a step will be used.
+ +
The *initstepslew* directive can also be used in an isolated LAN environment, The *initstepslew* directive can also be used in an isolated LAN environment,
where the clocks are set manually. The most stable computer is chosen as the where the clocks are set manually. The most stable computer is chosen as the
master, and the other computers are slaved to it. If each of the slaves is primary server and the other computers are its clients. If each of the clients
configured with the <<local,*local*>> directive, the master can be set up with is configured with the <<local,*local*>> directive, the server can be set up
an *initstepslew* directive which references some or all of the slaves. Then, with an *initstepslew* directive which references some or all of the clients.
if the master machine has to be rebooted, the slaves can be relied on to act Then, if the server machine has to be rebooted, the clients can be relied on to
analogously to a flywheel and preserve the time for a short period while the act analogously to a flywheel and preserve the time for a short period while
master completes its reboot. the server completes its reboot.
+ +
The *initstepslew* directive is functionally similar to a combination of the The *initstepslew* directive is functionally similar to a combination of the
<<makestep,*makestep*>> and <<server,*server*>> directives with the *iburst* <<makestep,*makestep*>> and <<server,*server*>> directives with the *iburst*
option. The main difference is that the *initstepslew* servers are used only option. The main difference is that the *initstepslew* servers are used only
before normal operation begins and that the foreground *chronyd* process waits before normal operation begins and that the foreground *chronyd* process waits
for *initstepslew* to finish before exiting. This is useful to prevent programs for *initstepslew* to finish before exiting. This prevent programs started in
started in the boot sequence after *chronyd* from reading the clock before it the boot sequence after *chronyd* from reading the clock before it has been
has been stepped. stepped. With the *makestep* directive, the
<<chronyc.adoc#waitsync,*waitsync*>> command of *chronyc* can be used instead.
[[refclock]]*refclock* _driver_ _parameter_[:__option__]... [_option_]...:: [[refclock]]*refclock* _driver_ _parameter_[:__option__]... [_option_]...::
The *refclock* directive specifies a hardware reference clock to be used as a The *refclock* directive specifies a hardware reference clock to be used as a
@ -700,6 +690,10 @@ or the <<chronyc.adoc#dump,*dump*>> command in *chronyc* is issued.
+ +
If the directory does not exist, it will be created automatically. If the directory does not exist, it will be created automatically.
+ +
The *-r* option of *chronyd* enables loading of the dump files on start. All
dump files found in the directory will be removed after start, even if the *-r*
option is not present.
+
An example of the directive is: An example of the directive is:
+ +
---- ----
@ -754,7 +748,7 @@ This directory is used also by the <<ntsdumpdir2,NTS server>> to save keys.
[[ntsrefresh]]*ntsrefresh* _interval_:: [[ntsrefresh]]*ntsrefresh* _interval_::
This directive specifies the maximum interval between NTS-KE handshakes (in This directive specifies the maximum interval between NTS-KE handshakes (in
seconds) in order to refresh the keys authenticating NTP packets. The default seconds) in order to refresh the keys authenticating NTP packets. The default
value is 2419200 (4 weeks). value is 2419200 (4 weeks) and the maximum value is 2^31-1 (68 years).
[[ntstrustedcerts]]*ntstrustedcerts* [_set-ID_] _file_|_directory_:: [[ntstrustedcerts]]*ntstrustedcerts* [_set-ID_] _file_|_directory_::
This directive specifies a file or directory containing certificates (in the This directive specifies a file or directory containing certificates (in the
@ -773,6 +767,9 @@ This directive can be used multiple times to specify one or more sets of
trusted certificates, each containing certificates from one or more files trusted certificates, each containing certificates from one or more files
and/or directories. and/or directories.
+ +
It is not necessary to restart *chronyd* in order to reload the certificates if
they change (e.g. after a renewal).
+
An example is: An example is:
+ +
---- ----
@ -783,16 +780,17 @@ ntstrustedcerts 2 /etc/pki/nts/qux.crt
---- ----
[[nosystemcert]]*nosystemcert*:: [[nosystemcert]]*nosystemcert*::
This directive disables the system's default trusted CAs. This directive disables the system's default trusted CAs. Only certificates
specified by the *ntstrustedcerts* directive will be trusted.
[[nocerttimecheck]]*nocerttimecheck* _limit_:: [[nocerttimecheck]]*nocerttimecheck* _limit_::
This directive disables the checks of the activation and expiration times of This directive disables the checks of the activation and expiration times of
certificates for the specified number of clock updates. It allows the NTS certificates for the specified number of clock updates. It allows the NTS
authentication mechanism to be used on computers which start with wrong time authentication mechanism to be used on computers which start with wrong time
(e.g. due to not having an RTC or backup battery). Disabling the time checks (e.g. due to not having an RTC or backup battery). Disabling the time checks
has important security implications, e.g. if an NTP server was ever has important security implications and should be used only as a last resort,
compromised, its certificate could be used in an attack after the expiration preferably with a minimal number of trusted certificates. The default value is
time. The default value is 0, which means the time checks are always enabled. 0, which means the time checks are always enabled.
+ +
An example of the directive is: An example of the directive is:
+ +
@ -896,11 +894,11 @@ source combining algorithm and only the selected source will be used to control
the system clock. the system clock.
[[maxdistance]]*maxdistance* _distance_:: [[maxdistance]]*maxdistance* _distance_::
The *maxdistance* directive sets the maximum allowed root distance of the The *maxdistance* directive sets the maximum root distance of a source to be
sources to not be rejected by the source selection algorithm. The distance acceptable for synchronisation of the clock. Sources that have a distance
includes the accumulated dispersion, which might be large when the source is no larger than the specified distance will be rejected. The distance estimates the
longer synchronised, and half of the total round-trip delay to the primary maximum error of the source. It includes the root dispersion and half of the
source. root delay (round-trip time) accumulated on the path to the primary source.
+ +
By default, the maximum root distance is 3 seconds. By default, the maximum root distance is 3 seconds.
+ +
@ -1117,10 +1115,10 @@ duration = sqrt(4 / wander)
---- ----
[[leapsectz]]*leapsectz* _timezone_:: [[leapsectz]]*leapsectz* _timezone_::
This directive specifies a timezone in the system tz database which *chronyd* This directive specifies a timezone in the system timezone database which
can use to determine when will the next leap second occur and what is the *chronyd* can use to determine when will the next leap second occur and what is
current offset between TAI and UTC. It will periodically check if 23:59:59 and the current offset between TAI and UTC. It will periodically check if 23:59:59
23:59:60 are valid times in the timezone. This typically works with the and 23:59:60 are valid times in the timezone. This normally works with the
_right/UTC_ timezone. _right/UTC_ timezone.
+ +
When a leap second is announced, the timezone needs to be updated at least 12 When a leap second is announced, the timezone needs to be updated at least 12
@ -1157,16 +1155,17 @@ Wed Dec 31 23:59:60 UTC 2008
[[makestep]]*makestep* _threshold_ _limit_:: [[makestep]]*makestep* _threshold_ _limit_::
Normally *chronyd* will cause the system to gradually correct any time offset, Normally *chronyd* will cause the system to gradually correct any time offset,
by slowing down or speeding up the clock as required. In certain situations, by slowing down or speeding up the clock as required. In certain situations,
the system clock might be so far adrift that this slewing process would take a e.g. when *chronyd* is initially started, the system clock might be so far
very long time to correct the system clock. adrift that this slewing process would take a very long time to correct the
system clock.
+ +
This directive forces *chronyd* to step the system clock if the adjustment is This directive forces *chronyd* to step the system clock if the adjustment is
larger than a threshold value, but only if there were no more clock updates larger than a threshold value, but only if there were no more clock updates
since *chronyd* was started than a specified limit (a negative value can be since *chronyd* was started than the specified limit. A negative value disables
used to disable the limit). the limit.
+ +
This is particularly useful when using reference clocks, because the On most systems it is desirable to step the system clock only on boot, before
<<initstepslew,*initstepslew*>> directive works only with NTP sources. starting programs that rely on time advancing monotonically forwards.
+ +
An example of the use of this directive is: An example of the use of this directive is:
+ +
@ -1228,8 +1227,8 @@ The *maxupdateskew* directive sets the threshold for determining whether an
estimate might be so unreliable that it should not be used. By default, the estimate might be so unreliable that it should not be used. By default, the
threshold is 1000 ppm. threshold is 1000 ppm.
+ +
Typical values for _skew-in-ppm_ might be 100 for a dial-up connection to Typical values for _skew-in-ppm_ might be 100 for NTP sources polled over a
servers over a phone line, and 5 or 10 for a computer on a LAN. wireless network, and 10 or smaller for sources on a local wired network.
+ +
It should be noted that this is not the only means of protection against using It should be noted that this is not the only means of protection against using
unreliable estimates. At all times, *chronyd* keeps track of both the estimated unreliable estimates. At all times, *chronyd* keeps track of both the estimated
@ -1456,14 +1455,14 @@ This directive can be used multiple times to specify multiple addresses.
The syntax is as follows: The syntax is as follows:
+ +
---- ----
broadcast 30 192.168.1.255 broadcast 32 192.168.1.255
broadcast 60 192.168.2.255 12123 broadcast 64 192.168.2.255 12123
broadcast 60 ff02::101 broadcast 64 ff02::101
---- ----
+ +
In the first example, the destination port defaults to UDP port 123 (the normal NTP In the first example, the destination port defaults to UDP port 123 (the normal NTP
port). In the second example, the destination port is specified as 12123. The port). In the second example, the destination port is specified as 12123. The
first parameter in each case (30 or 60 respectively) is the interval in seconds first parameter in each case (32 or 64 respectively) is the interval in seconds
between broadcast packets being sent. The second parameter in each case is the between broadcast packets being sent. The second parameter in each case is the
broadcast address to send the packet to. This should correspond to the broadcast address to send the packet to. This should correspond to the
broadcast address of one of the network interfaces on the computer where broadcast address of one of the network interfaces on the computer where
@ -1487,10 +1486,8 @@ This directive specifies the maximum amount of memory that *chronyd* is allowed
to allocate for logging of client accesses and the state that *chronyd* as an to allocate for logging of client accesses and the state that *chronyd* as an
NTP server needs to support the interleaved mode for its clients. The default NTP server needs to support the interleaved mode for its clients. The default
limit is 524288 bytes, which is sufficient for monitoring about four thousand limit is 524288 bytes, which is sufficient for monitoring about four thousand
clients at the same time. clients at the same time. The maximum value is 2^32-1 (4 GB) on 32-bit systems
+ and 2^35 (32 GB) on 64-bit systems.
In older *chrony* versions if the limit was set to 0, the memory allocation was
unlimited.
+ +
An example of the use of this directive is: An example of the use of this directive is:
+ +
@ -1592,9 +1589,17 @@ The port will be open only when a certificate and key is specified by the
[[ntsservercert]]*ntsservercert* _file_:: [[ntsservercert]]*ntsservercert* _file_::
This directive specifies a file containing a certificate in the PEM format This directive specifies a file containing a certificate in the PEM format
for *chronyd* to operate as an NTS server. for *chronyd* to operate as an NTS server. The file should also include
any intermediate certificates that the clients will need to validate the
server's certificate.
+ +
This directive can be used multiple times to specify multiple certificates. This directive can be used multiple times to specify multiple certificates for
different names of the server.
+
The files are loaded only once. *chronyd* needs to be restarted in order to
load a renewed certificate. The <<ntsdumpdir,*ntsdumpdir*>> and
<<dumpdir,*dumpdir*>> directives with the *-r* option of *chronyd* are
recommended for a near-seamless server operation.
[[ntsserverkey]]*ntsserverkey* _file_:: [[ntsserverkey]]*ntsserverkey* _file_::
This directive specifies a file containing a private key in the PEM format This directive specifies a file containing a private key in the PEM format
@ -1613,7 +1618,9 @@ process will be started and all NTS-KE requests will be handled by the main
[[maxntsconnections]]*maxntsconnections* _connections_:: [[maxntsconnections]]*maxntsconnections* _connections_::
This directive specifies the maximum number of concurrent NTS-KE connections This directive specifies the maximum number of concurrent NTS-KE connections
per process that the NTS server will accept. The default value is 100. per process that the NTS server will accept. The default value is 100. The
maximum practical value is half of the system *FD_SETSIZE* constant (usually
1024).
[[ntsdumpdir2]]*ntsdumpdir* _directory_:: [[ntsdumpdir2]]*ntsdumpdir* _directory_::
This directive specifies a directory where *chronyd* operating as an NTS server This directive specifies a directory where *chronyd* operating as an NTS server
@ -1645,7 +1652,7 @@ _/dev/urandom_ device. The server keeps two previous keys to give the clients
time to get new cookies encrypted by the latest key. The interval is measured time to get new cookies encrypted by the latest key. The interval is measured
as the server's operating time, i.e. the actual interval can be longer if as the server's operating time, i.e. the actual interval can be longer if
*chronyd* is not running continuously. The default interval is 604800 seconds *chronyd* is not running continuously. The default interval is 604800 seconds
(1 week). (1 week). The maximum value is 2^31-1 (68 years).
+ +
The automatic rotation of the keys can be disabled by setting *ntsrotate* to 0. The automatic rotation of the keys can be disabled by setting *ntsrotate* to 0.
In this case the keys are assumed to be managed externally. *chronyd* will not In this case the keys are assumed to be managed externally. *chronyd* will not
@ -2649,22 +2656,22 @@ This section shows how to configure *chronyd* for computers that never have
network connectivity to any computer which ultimately derives its time from a network connectivity to any computer which ultimately derives its time from a
reference clock. reference clock.
In this situation, one computer is selected to be the master timeserver. The In this situation, one computer is selected to be the primary timeserver. The
other computers are either direct clients of the master, or clients of clients. other computers are either direct clients of the server, or clients of clients.
The <<local,*local*>> directive enables a local reference mode, which allows The <<local,*local*>> directive enables a local reference mode, which allows
*chronyd* to appear synchronised even when it is not. *chronyd* to appear synchronised even when it is not.
The rate value in the master's drift file needs to be set to the average rate The rate value in the server's drift file needs to be set to the average rate
at which the master gains or loses time. *chronyd* includes support for this, at which the server gains or loses time. *chronyd* includes support for this,
in the form of the <<manual,*manual*>> directive and the in the form of the <<manual,*manual*>> directive and the
<<chronyc.adoc#settime,*settime*>> command in the *chronyc* program. <<chronyc.adoc#settime,*settime*>> command in the *chronyc* program.
If the master is rebooted, *chronyd* can re-read the drift rate from the drift If the server is rebooted, *chronyd* can re-read the drift rate from the drift
file. However, the master has no accurate estimate of the current time. To get file. However, the server has no accurate estimate of the current time. To get
around this, the system can be configured so that the master can initially set around this, the system can be configured so that the server can initially set
itself to a '`majority-vote`' of selected clients' times; this allows the itself to a '`majority-vote`' of selected clients' times; this allows the
clients to '`flywheel`' the master while it is rebooting. clients to '`flywheel`' the server while it is rebooting.
The <<smoothtime,*smoothtime*>> directive is useful when the clocks of the The <<smoothtime,*smoothtime*>> directive is useful when the clocks of the
clients need to stay close together when the local time is adjusted by the clients need to stay close together when the local time is adjusted by the
@ -2673,8 +2680,8 @@ activated by the <<chronyc.adoc#smoothtime,*smoothtime activate*>> command when
the local time is ready to be served. After that point, any adjustments will be the local time is ready to be served. After that point, any adjustments will be
smoothed out. smoothed out.
A typical configuration file for the master (called _master_) might be A typical configuration file for the server (called _ntp.local_) might be
(assuming the clients and the master are in the _192.168.165.x_ subnet): (assuming the clients and the server are in the _192.168.165.x_ subnet):
---- ----
initstepslew 1 client1 client3 client6 initstepslew 1 client1 client3 client6
@ -2686,11 +2693,11 @@ smoothtime 400 0.01
rtcsync rtcsync
---- ----
For the clients that have to resynchronise the master when it restarts, For the clients that have to resynchronise the server when it restarts,
the configuration file might be: the configuration file might be:
---- ----
server master iburst server ntp.local iburst
driftfile @CHRONYVARDIR@/drift driftfile @CHRONYVARDIR@/drift
allow 192.168.165.0/24 allow 192.168.165.0/24
makestep 1.0 3 makestep 1.0 3
@ -2700,22 +2707,22 @@ rtcsync
The rest of the clients would be the same, except that the *allow* directive is The rest of the clients would be the same, except that the *allow* directive is
not required. not required.
If there is no suitable computer to be designated as the master, or there is a If there is no suitable computer to be designated as the primary server, or
requirement to keep the clients synchronised even when it fails, the *orphan* there is a requirement to keep the clients synchronised even when it fails, the
option of the *local* directive enables a special mode where the master is *orphan* option of the *local* directive enables a special mode where the
selected from multiple computers automatically. They all need to use the same server is selected from multiple computers automatically. They all need to use
*local* configuration and poll one another. The server with the smallest the same *local* configuration and poll one another. The server with the
reference ID (which is based on its IP address) will take the role of the smallest reference ID (which is based on its IP address) will take the role of
master and others will be synchronised to it. When it fails, the server with the primary server and others will be synchronised to it. When it fails, the
the second smallest reference ID will take over and so on. server with the second smallest reference ID will take over and so on.
A configuration file for the first server might be (assuming there are three A configuration file for the first server might be (assuming there are three
servers called _master1_, _master2_, and _master3_): servers called _ntp1.local_, _ntp2.local_, and _ntp3.local_):
---- ----
initstepslew 1 master2 master3 initstepslew 1 ntp2.local ntp3.local
server master2 server ntp2.local
server master3 server ntp3.local
driftfile @CHRONYVARDIR@/drift driftfile @CHRONYVARDIR@/drift
local stratum 8 orphan local stratum 8 orphan
manual manual