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

doc: improve chronyc man page

Browse source 
- fix redundant words, word order, articles, consistency, typos
- avoid slashes, contractions, `may`, dashes in running text
- add Oxford commas
- use colon before examples
This commit is contained in:
Stephen Wadeley 2016-06-05 21:01:48 +02:00 committed by Miroslav Lichvar
parent e2422023c4
commit 89ac745184
1 changed files with 74 additions and 74 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

148
doc/chronyc.adoc
View file

@ -37,10 +37,10 @@ running.
If no commands are specified on the command line, *chronyc* will expect input
from the user. The prompt _chronyc>_ will be displayed when it is being run
from a terminal. If *chronyc*'s input or output are redirected from/to a file,
from a terminal. If *chronyc*'s input or output are redirected from or to a file,
the prompt is not shown.
There are two ways how *chronyc* can access *chronyd*. One is the Internet
There are two ways *chronyc* can access *chronyd*. One is the Internet
Protocol (IPv4 or IPv6) and the other is a Unix domain socket, which is
accessible locally by the root or _chrony_ user. By default, *chronyc* first
tries to connect to the Unix domain socket. The compiled-in default path is
@ -48,18 +48,18 @@ _@CHRONYSOCKDIR@/chronyd.sock_. If that fails (e.g. because *chronyc* is
running under a non-root user), it will try to connect to 127.0.0.1 and then
::1.
Only the following monitoring commands, which don't affect the behaviour of
*chronyd*, are allowed from the internet: *activity*, *manual list*,
Only the following monitoring commands, which do not affect the behaviour of
*chronyd*, are allowed from the network: *activity*, *manual list*,
*rtcdata*, *smoothing*, *sources*, *sourcestats*, *tracking*, *waitsync*. The
set of hosts from which *chronyd* will accept these commands can be configured
with the <<chrony.conf.adoc#cmdallow,*cmdallow*>> directive in the *chronyd*'s
configuration file or the <<cmdallow,*cmdallow*>> command in *chronyc*. By
default, the commands are accepted only from the localhost (127.0.0.1 or ::1).
default, the commands are accepted only from localhost (127.0.0.1 or ::1).
All other commands are allowed only through the Unix domain socket. When sent
over the internet, *chronyd* will respond with a '`Not authorised`' error, even
if it's from the localhost. In chrony versions before 2.2 they were allowed
from the internet if they were authenticated with a password, but that is no
over the network, *chronyd* will respond with a '`Not authorised`' error, even
if it is from localhost. In chrony versions before 2.2 they were allowed
from the network if they were authenticated with a password, but that is no
longer supported.
Having full access to *chronyd* via *chronyc* is more or less equivalent to
@ -85,7 +85,7 @@ to other units.
*-d*::
This option enables printing of debugging messages if *chronyc* was compiled
with debugging support).
with debugging support.
*-m*::
Normally, all arguments on the command line are interpreted as one command.
@ -95,9 +95,9 @@ interpreted as a whole command.
*-h* _host_::
This option allows the user to specify which host (or comma-separated list of
addresses) running the *chronyd* program is to be contacted. This allows for
remote monitoring, without having to ssh to the other host first.
remote monitoring, without having to connect over SSH to the other host first.
+
The default is to contact *chronyd* running on the same host as that where
The default is to contact *chronyd* running on the same host where
*chronyc* is being run.
*-p* _port_::
@ -147,7 +147,7 @@ The fields are explained as follows:
*Reference ID*:::
This is the reference ID and name (or IP address) of the server to which the
computer is currently synchronised. For IPv4 addresses, the reference ID is
equal to the address and for IPv6 addresses it's the first 32 bits of the MD5
equal to the address and for IPv6 addresses it is the first 32 bits of the MD5
sum of the address.
+
If it is _127.127.1.1_ it means the computer is not synchronised to any
@ -164,7 +164,7 @@ This is the time (UTC) at which the last measurement from the reference
source was processed.
*System time*:::
In normal operation, *chronyd* by default never steps the system clock, because
any jump in the timescale can have adverse consequences for certain application
any jump in the time can have adverse consequences for certain application
programs. Instead, any error in the system clock is corrected by slightly
speeding up or slowing down the system clock until the error has been removed,
and then returning to the system clock's normal speed. A consequence of this is
@ -184,7 +184,7 @@ has advanced 1 second, it has actually advanced by 1.000001 seconds relative to
true time.
+
As you can see in the example, the clock in the computer is not a very
good one - it would gain about 30 seconds per day if it wasn't corrected!
good one; it would gain about 30 seconds per day if it was not corrected!
*Residual freq*:::
This shows the '`residual frequency`' for the currently selected reference
source. This reflects any difference between what the measurements from the
@ -200,7 +200,7 @@ computed for the new frequency, with weights depending on these accuracies.
If the measurements from the reference source follow a consistent trend, the
residual will be driven to zero over time.
*Skew*:::
This is the estimated error bound on the the frequency.
This is the estimated error bound on the frequency.
*Root delay*:::
This is the total of the network path delays to the stratum-1 computer from
which the computer is ultimately synchronised.
@ -211,7 +211,7 @@ Dispersion is due to system clock resolution, statistical measurement
variations, etc.
+
An absolute bound on the computer's clock accuracy (assuming the stratum-1
computer is correct) is given by
computer is correct) is given by:
+
----
clock_error <= root_dispersion + (0.5 * |root_delay|)
@ -226,7 +226,7 @@ second_ or _Not synchronised_.
*makestep* _threshold_ _limit_::
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,
the system clock may be so far adrift that this slewing process would take a
the system clock might be so far adrift that this slewing process would take a
very long time to correct the system clock.
+
The *makestep* command can be used in this situation. There are two forms of
@ -237,7 +237,7 @@ equivalent amount, making it correct immediately.
The second form configures the automatic stepping, similarly to the
<<chrony.conf.adoc#makestep,*makestep*>> directive. It has two parameters,
stepping threshold (in seconds) and number of future clock updates for which
will be the threshold active. This can be used with the <<burst,*burst*>>
the threshold will be active. This can be used with the <<burst,*burst*>>
command to quickly make a new measurement and correct the clock by stepping if
needed, without waiting for *chronyd* to complete the measurement and update
the clock.
@ -247,7 +247,7 @@ makestep 0.1 1
burst 1/2
----
+
BE WARNED - certain software will be seriously affected by such jumps to the
BE WARNED: Certain software will be seriously affected by such jumps in the
system time. (That is the reason why *chronyd* uses slewing normally.)
[[maxupdateskew]]*maxupdateskew* _skew-in-ppm_::
@ -270,7 +270,7 @@ specified or zero, the value will not be checked.
The fourth argument is the interval specified in seconds in which the check is
repeated. The interval is 10 seconds by default.
+
An example is
An example is:
+
----
waitsync 60 0.01
@ -311,13 +311,13 @@ This column indicates the state of the source.
* _-_ indicates acceptable sources which are excluded by the combining
algorithm.
* _?_ indicates sources to which connectivity has been lost or whose packets
don't pass all tests. It's also shown at start-up, until at least 3 samples
do not pass all tests. It is also shown at start-up, until at least 3 samples
have been gathered from it.
* _x_ indicates a clock which *chronyd* thinks is a falseticker (i.e. its
time is inconsistent with a majority of other sources).
* _~_ indicates a source whose time appears to have too much variability.
*Name/IP address*:::
This shows the name or the IP address of the source, or refid for reference
This shows the name or the IP address of the source, or reference ID for reference
clocks.
*Stratum*:::
This shows the stratum of the source, as reported in its most recently
@ -331,23 +331,23 @@ logarithm of the interval in seconds. Thus, a value of 6 would indicate that
a measurement is being made every 64 seconds. *chronyd* automatically varies
the polling rate in response to prevailing conditions.
*Reach*:::
This shows the source's reachability register printed as octal number. The
This shows the source's reachability register printed as an octal number. The
register has 8 bits and is updated on every received or missed packet from
the source. A value of 377 indicates that a valid reply was received for all
from the last eight transmissions.
*LastRx*:::
This column shows how long ago the last sample was received from the source.
This is normally in seconds. The letters _m_, _h_, _d_ or _y_ indicate
minutes, hours, days or years.
minutes, hours, days, or years.
*Last sample*:::
This column shows the offset between the local clock and the source at the
last measurement. The number in the square brackets shows the actual measured
offset. This may be suffixed by _ns_ (indicating nanoseconds), _us_
offset. This can be suffixed by _ns_ (indicating nanoseconds), _us_
(indicating microseconds), _ms_ (indicating milliseconds), or _s_ (indicating
seconds). The number to the left of the square brackets shows the original
measurement, adjusted to allow for any slews applied to the local clock
since. The number following the _+/-_ indicator shows the margin of error in
the measurement. Positive offsets indicate that the local clock is fast of
the measurement. Positive offsets indicate that the local clock is ahead of
the source.
[[sourcestats]]*sourcestats* [*-v*]::
@ -358,7 +358,7 @@ estimation process for each of the sources currently being examined by
The optional argument *-v* can be specified, meaning _verbose_. In this case,
extra caption lines are shown as a reminder of the meanings of the columns.
+
An example report is
An example report is:
+
----
210 Number of sources = 1
@ -370,8 +370,8 @@ foo.example.net 11 5 46m -0.001 0.045 1us 25us
The columns are as follows:
+
*Name/IP Address*:::
This is the name or IP address of the NTP server (or peer) or refid of the
refclock to which the rest of the line relates.
This is the name or IP address of the NTP server (or peer) or reference ID of the
reference clock to which the rest of the line relates.
*NP*:::
This is the number of sample points currently being retained for the server.
The drift rate and current offset are estimated by performing a linear
@ -398,7 +398,7 @@ This is the estimated offset of the source.
This is the estimated sample standard deviation.
[[reselect]]*reselect*::
To avoid excessive switching between sources, *chronyd* may stay synchronised
To avoid excessive switching between sources, *chronyd* can stay synchronised
to a source even when it is not currently the best one among the available
sources.
+
@ -413,28 +413,28 @@ configuration file.
=== NTP sources
[[activity]]*activity*::
This command reports the number of servers/peers that are online and offline.
If the auto_offline option is used in specifying some of the servers/peers, the
*activity* command may be useful for detecting when all of them have entered
the offline state after the network link has been disconnected.
This command reports the number of servers and peers that are online and
offline. If the *auto_offline* option is used in specifying some of the servers
or peers, the *activity* command can be useful for detecting when all of them
have entered the offline state after the network link has been disconnected.
+
The report shows the number of servers/peers in 5 states:
The report shows the number of servers and peers in 5 states:
+
*online*:::
the server/peer is currently online (i.e. assumed by chronyd to be reachable)
the server or peer is currently online (i.e. assumed by *chronyd* to be reachable)
*offline*:::
the server/peer is currently offline (i.e. assumed by chronyd to be
the server or peer is currently offline (i.e. assumed by *chronyd* to be
unreachable, and no measurements from it will be attempted.)
*burst_online*:::
a burst command has been initiated for the server/peer and is being
performed; after the burst is complete, the server/peer will be returned to
a burst command has been initiated for the server or peer and is being
performed; after the burst is complete, the server or peer will be returned to
the online state.
*burst_offline*:::
a burst command has been initiated for the server/peer and is being
performed; after the burst is complete, the server/peer will be returned to
a burst command has been initiated for the server or peer and is being
performed; after the burst is complete, the server or peer will be returned to
the offline state.
*unresolved*:::
the name of the server/peer wasn't resolved to an address yet; this server is
the name of the server or peer was not resolved to an address yet; this source is
not visible in the *sources* and *sourcestats* reports.
[[add_peer]]*add peer* _address_ [_option_]...::
@ -463,7 +463,7 @@ directive in the configuration file.
The following server options can be set in the command: *port*, *minpoll*,
*maxpoll*, *presend*, *maxdelayratio*, *maxdelay*, *key*.
+
An example of using this command is shown below.
An example of using this command is shown below:
+
----
add server foo.example.net minpoll 6 maxpoll 10 key 25
@ -517,7 +517,7 @@ that source.
If no _mask_ or _masked-address_ arguments are provided, every source will be
matched.
+
An example of the two-argument form of the command is
An example of the two-argument form of the command is:
+
----
burst 2/10
@ -527,7 +527,7 @@ This will cause *chronyd* to attempt to get two good measurements from each
source, stopping after two have been obtained, but in no event will it try more
than ten probes to the source.
+
Examples of the four-argument form of the command are
Examples of the four-argument form of the command are:
+
----
burst 2/10 255.255.0.0/1.2.0.0
@ -539,7 +539,7 @@ whose IPv4 addresses are of the form _1.2.x.y_, where _x_ and _y_ are
arbitrary. In the second case, the sampling will be applied to sources whose
IPv6 addresses have first 48 bits equal to _2001:db8:789a_.
+
Example of the three-argument form of the command is
Example of the three-argument form of the command is:
+
----
burst 2/10 foo.example.net
@ -594,13 +594,13 @@ local group of computers, and has a permanent connection to true time servers
outside the organisation. However, the external connection is heavily loaded at
certain times of the day and the measurements obtained are less reliable at
those times. In this case, it is probably most useful to determine the
gain/loss rate during the quiet periods and let the whole network coast through
gain or loss rate during the quiet periods and let the whole network coast through
the loaded periods. The *offline* and *online* commands can be used to achieve
this.
+
There are four forms of the *offline* command. The first form is a wildcard,
meaning all sources. The second form allows an IP address mask and a masked
address to be specified. The third form uses the CIDR notation. The fourth form
address to be specified. The third form uses CIDR notation. The fourth form
uses an IP address or a hostname. These forms are illustrated below.
+
----
@ -614,10 +614,10 @@ The second form means that the *offline* command is to be applied to any source
whose IPv4 address is in the _1.2.3_ subnet. (The host's address is logically
and-ed with the mask, and if the result matches the _masked-address_ the host
is processed.) The third form means that the command is to be applied to all
sources whose IPv6 addresses have first 48 bits equal to _2001:db8:789a_. The
sources whose IPv6 addresses have their first 48 bits equal to _2001:db8:789a_. The
fourth form means that the command is to be applied only to that one source.
+
The wildcard form of the address is actually equivalent to
The wildcard form of the address is equivalent to:
+
----
offline 0.0.0.0/0.0.0.0
@ -645,7 +645,7 @@ configured sources to IP addresses again, e.g. after suspending and resuming
the machine in a different network.
+
Sources that stop responding will be replaced with newly resolved addresses
automatically after 8 polling intervals, but this command may still be useful
automatically after 8 polling intervals, but this command can still be useful
to replace them immediately and not wait until they are marked as unreachable.
=== Manual time input
@ -673,7 +673,7 @@ The *list* form of the command lists all the samples currently stored in
0 27Jan99 22:09:20 0.00 0.97 0.00
----
+
The columns as as follows:
The columns are as as follows:
+
. The sample index (used for the *manual delete* command).
. The date and time of the sample.
@ -691,7 +691,7 @@ index of the sample, as shown in the first column of the output from *manual
list*. Following deletion of the data point, the current error and drift rate
are re-estimated from the remaining data points and the system clock trimmed if
necessary. This option is intended to allow '`outliers`' to be discarded, i.e.
samples where the administrator realises s/he has entered a very poor
samples where the administrator realises they have entered a very poor
timestamp.
+
The *reset* form of the command deletes all samples at once. The system clock
@ -699,7 +699,7 @@ is left running as it was before the command was entered.
[[settime]]*settime* _time_::
The *settime* command allows the current time to be entered manually, if this
option has been configured into *chronyd*. (It may be configured either with
option has been configured into *chronyd*. (It can be configured either with
the <<chrony.conf.adoc#manual,*manual*>> directive in the configuration file,
or with the <<manual,*manual*>> command of *chronyc*.)
+
@ -720,13 +720,13 @@ present run of *chronyd*. However, the entered measurement is used for
adjusting the current clock offset (rather than the estimated intercept from
the regression, which is ignored). Contrast what happens with the
<<manual,*manual delete*>> command, where the intercept is used to set the
current offset (since there is no measurement that has just been typed in in
current offset (since there is no measurement that has just been entered in
that case).
+
The time is parsed by the public domain _getdate_ algorithm. Consequently, you
can only specify time to the nearest second.
+
Examples of inputs that are valid are shown below.
Examples of inputs that are valid are shown below:
+
----
settime 16:30
@ -734,7 +734,7 @@ settime 16:30:05
settime Nov 21, 2015 16:30:05
----
+
For a full description of getdate, get hold of the getdate documentation
For a full description of getdate, see the getdate documentation
(bundled, for example, with the source for GNU tar).
=== NTP access
@ -752,15 +752,15 @@ accheck 2001:db8::1
----
+
This command can be used to examine the effect of a series of *allow*, *allow
all*, *deny* and *deny all* commands specified either via *chronyc*, or in
all*, *deny*, and *deny all* commands specified either via *chronyc*, or in
*chronyd*'s configuration file.
[[clients]]*clients*::
This command shows a list of clients that have accessed the server, through
either the NTP or command/monitoring ports. It doesn't include accesses over
the Unix domain comamnd socket. There are no arguments.
either the NTP or command ports. It does not include accesses over
the Unix domain command socket. There are no arguments.
+
An example of the output is
An example of the output is:
+
----
Hostname NTP Drop Int IntL Last Cmd Drop Int Last
@ -889,7 +889,7 @@ time observed by clients is running slower than true time.
The current frequency wander of the served time. Negative value means the
time observed by clients is slowing down.
*Last update*:::
This field shows how long ago was the time smoothing process updated, e.g.
This field shows how long ago the time smoothing process was updated, e.g.
*chronyd* accumulated a new measurement.
*Remaining time*:::
The time it would take for the smoothing process to get to zero offset and
@ -942,13 +942,13 @@ RTC is fast by : -1.632736 seconds
RTC gains time at : -107.623 ppm
----
+
The fields have the following meaning
The fields have the following meaning:
+
*RTC ref time (GMT)*:::
This is the RTC reading the last time its error was measured.
*Number of samples*:::
This is the number of previous measurements being used to determine the RTC
gain/loss rate.
gain or loss rate.
*Number of runs*:::
This is the number of runs of residuals of the same sign following the
regression fit for (RTC error) versus (RTC time). A value which is small
@ -958,11 +958,11 @@ the fit.
*Sample span period*:::
This is the period that the measurements span (from the oldest to the
newest). Without a unit the value is in seconds; suffixes _m_ for minutes,
_h_ for hours, _d_ for days or _y_ for years may be used.
_h_ for hours, _d_ for days or _y_ for years can be used.
*RTC is fast by*:::
This is the estimate of how many seconds fast the RTC when it thought
the time was at the reference time (above). If this value is large, you
may (or may not) want to use the <<trimrtc,*trimrtc*>> command to bring the
might (or might not) want to use the <<trimrtc,*trimrtc*>> command to bring the
RTC into line with the system clock. (Note, a large error will not affect
*chronyd*'s operation, unless it becomes so big as to start causing rounding
errors.)
@ -981,7 +981,7 @@ currently estimated at less than a second.
The command takes no arguments. It performs the following steps (if the RTC is
more than 1 second away from the system clock):
+
. Remember the currently estimated gain/loss rate of the RTC and flush the
. Remember the currently estimated gain or loss rate of the RTC and flush the
previous measurements.
. Step the real-time clock to bring it within a second of the system clock.
. Make several measurements to accurately determine the new offset between
@ -1006,7 +1006,7 @@ The *trimrtc* command can be executed automatically by *chronyd* with the
file.
[[writertc]]*writertc*::
The *writertc* command writes the currently estimated error and gain/loss rate
The *writertc* command writes the currently estimated error and gain or loss rate
parameters for the RTC to the RTC file (specified with the
<<chrony.conf.adoc#rtcfile,*rtcfile*>> directive). This information is also
written automatically when *chronyd* is killed (by the SIGHUP, SIGINT, SIGQUIT
@ -1037,7 +1037,7 @@ The *dump* command is somewhat equivalent to the
<<chrony.conf.adoc#dumponexit,*dumponexit*>> directive in the configuration
file.
+
To use the *dump*, you probably want to configure the name of the
To use the *dump* command, you might want to configure the name of the
directory into which the dump files will be written. This can only be
done in the configuration file with the <<chrony.conf.adoc#dumpdir,*dumpdir*>>
directive.
@ -1045,7 +1045,7 @@ directive.
=== Client commands
[[dns]]*dns* _option_::
The *dns* command configures how are hostnames and IP addresses resolved in
The *dns* command configures how hostnames and IP addresses are resolved in
*chronyc*. IP addresses can be resolved to hostnames when printing results of
<<sources,*sources*>>, <<sourcestats,*sourcestats*>>, <<tracking,*tracking*>>
and <<clients,*clients*>> commands. Hostnames are resolved in commands that
@ -1086,7 +1086,7 @@ The default is 2.
The *keygen* command generates a key that can be added to the
key file (specified with the <<chrony.conf.adoc#keyfile,*keyfile*>> directive)
to allow NTP authentication between server and client, or peers. The key is
generated from the _/dev/urandom_ device and it's printed to standard output.
generated from the _/dev/urandom_ device and it is printed to standard output.
+
The command has three optional arguments. The first argument is the key number
(by default 1), which will be specified with the *key* option of the *server*
@ -1095,13 +1095,13 @@ function (by default SHA1 or MD5 if SHA1 is not available) and the third
argument is the number of bits the key should have, between 80 and 4096 bits
(by default 160 bits).
+
An example is
An example is:
+
----
keygen 73 SHA1 256
----
+
which generates a 256-bit SHA-1 key with number 73. The printed line would
which generates a 256-bit SHA1 key with number 73. The printed line should
then be securely transferred and added to the key files on both server and
client, or peers.
@ -1123,4 +1123,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.