// This file is part of chrony // // Copyright (C) Richard P. Curnow 1997-2003 // Copyright (C) Stephen Wadeley 2016 // Copyright (C) Miroslav Lichvar 2009-2017, 2019-2020 // // This program is free software; you can redistribute it and/or modify // it under the terms of version 2 of the GNU General Public License as // published by the Free Software Foundation. // // This program is distributed in the hope that it will be useful, but // WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU // General Public License for more details. // // You should have received a copy of the GNU General Public License along // with this program; if not, write to the Free Software Foundation, Inc., // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. = chronyc(1) :doctype: manpage :man manual: User manual :man source: chrony @CHRONY_VERSION@ == NAME chronyc - command-line interface for chrony daemon == SYNOPSIS *chronyc* [_OPTION_]... [_COMMAND_]... == DESCRIPTION *chronyc* is a command-line interface program which can be used to monitor *chronyd*'s performance and to change various operating parameters whilst it is 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 or to a file, the prompt will not be shown. 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 _@CHRONYRUNDIR@/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 do not affect the behaviour of *chronyd*, are allowed from the network: *activity*, *manual list*, *rtcdata*, *smoothing*, *sourcename*, *sources*, *sourcestats*, *tracking*, *waitsync*. The set of hosts from which *chronyd* will accept these commands can be configured with the <> directive in the *chronyd*'s configuration file or the <> command in *chronyc*. By 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 network, *chronyd* will respond with a '`Not authorised`' error, even if it is from localhost. Having full access to *chronyd* via *chronyc* is more or less equivalent to being able to modify the *chronyd*'s configuration file and restart it. == OPTIONS *-4*:: With this option hostnames will be resolved only to IPv4 addresses. *-6*:: With this option hostnames will be resolved only to IPv6 addresses. *-n*:: This option disables resolving of IP addresses to hostnames, e.g. to avoid slow DNS lookups. Long addresses will not be truncated to fit into the column. *-N*:: This option enables printing of the original names of NTP sources that were specified in the configuration file, or *chronyc* commands, and are internally used by *chronyd*. Without the *-n* and *-N* option, the names of NTP sources are obtained from reverse DNS lookups and can be different from the original names. *-c*:: This option enables printing of reports in a comma-separated values (CSV) format. Reverse DNS lookups will be disabled, time will be printed as number of seconds since the epoch, and values in seconds will not be converted to other units. *-d*:: This option enables printing of debugging messages if *chronyc* was compiled with debugging support. *-m*:: Normally, all arguments on the command line are interpreted as one command. With this option multiple commands can be specified. Each argument will be 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 connect over SSH to the other host first. + The default is to contact *chronyd* running on the same host where *chronyc* is being run. *-p* _port_:: This option allows the user to specify the UDP port number which the target *chronyd* is using for its monitoring connections. This defaults to 323; there would rarely be a need to change this. *-f* _file_:: This option is ignored and is provided only for compatibility. *-a*:: This option is ignored and is provided only for compatibility. *-v*, *--version*:: With this option *chronyc* displays its version number on the terminal and exits. *--help*:: With this option *chronyc* displays a help message on the terminal and exits. == COMMANDS This section describes each of the commands available within the *chronyc* program. === System clock [[tracking]]*tracking*:: The *tracking* command displays parameters about the system's clock performance. An example of the output is shown below. + ---- Reference ID : CB00710F (foo.example.net) Stratum : 3 Ref time (UTC) : Fri Jan 27 09:49:17 2017 System time : 0.000006523 seconds slow of NTP time Last offset : -0.000006747 seconds RMS offset : 0.000035822 seconds Frequency : 3.225 ppm slow Residual freq : -0.000 ppm Skew : 0.129 ppm Root delay : 0.013639022 seconds Root dispersion : 0.001100737 seconds Update interval : 64.2 seconds Leap status : Normal ---- + 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 is the first 32 bits of the MD5 sum of the address. + If the reference ID is _7F7F0101_ and there is no name or IP address, it means the computer is not synchronised to any external source and that you have the _local_ mode operating (via the <> command in *chronyc*, or the <> directive in the configuration file). + The reference ID is printed as a hexadecimal number. Note that in older versions it used to be printed in quad-dotted notation and could be confused with an IPv4 address. *Stratum*::: The stratum indicates how many hops away from a computer with an attached reference clock we are. Such a computer is a stratum-1 computer, so the computer in the example is two hops away (i.e. _foo.example.net_ is a stratum-2 and is synchronised from a stratum-1). *Ref time*::: 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 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 that there will be a period when the system clock (as read by other programs) will be different from *chronyd*'s estimate of the current true time (which it reports to NTP clients when it is operating as a server). The value reported on this line is the difference due to this effect. *Last offset*::: This is the estimated local offset on the last clock update. A positive value indicates the local time (as previously estimated true time) was ahead of the time sources. *RMS offset*::: This is a long-term average of the offset value. *Frequency*::: The '`frequency`' is the rate by which the system's clock would be wrong if *chronyd* was not correcting it. It is expressed in ppm (parts per million). For example, a value of 1 ppm would mean that when the system's clock thinks it has advanced 1 second, it has actually advanced by 1.000001 seconds relative to true time. *Residual freq*::: This shows the '`residual frequency`' for the currently selected reference source. This reflects any difference between what the measurements from the reference source indicate the frequency should be and the frequency currently being used. + The reason this is not always zero is that a smoothing procedure is applied to the frequency. Each time a measurement from the reference source is obtained and a new residual frequency computed, the estimated accuracy of this residual is compared with the estimated accuracy (see '`skew`' next) of the existing frequency value. A weighted average is 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 frequency. *Root delay*::: This is the total of the network path delays to the stratum-1 computer from which the computer is ultimately synchronised. *Root dispersion*::: This is the total dispersion accumulated through all the computers back to the stratum-1 computer from which the computer is ultimately synchronised. 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: + ---- clock_error <= |system_time_offset| + root_dispersion + (0.5 * root_delay) ---- *Update interval*::: This is the interval between the last two clock updates. *Leap status*::: This is the leap status, which can be _Normal_, _Insert second_, _Delete second_ or _Not synchronised_. [[makestep]]*makestep*:: *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 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 the command. The first form has no parameters. It tells *chronyd* to cancel any remaining correction that was being slewed and jump the system clock by the equivalent amount, making it correct immediately. + The second form configures the automatic stepping, similarly to the <> directive. It has two parameters, stepping threshold (in seconds) and number of future clock updates for which the threshold will be active. This can be used with the <> 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. + ---- makestep 0.1 1 burst 1/2 ---- + 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_:: This command has the same effect as the <> directive in the configuration file. [[waitsync]]*waitsync* [_max-tries_ [_max-correction_ [_max-skew_ [_interval_]]]]:: The *waitsync* command waits for *chronyd* to synchronise. + Up to four optional arguments can be specified. The first is the maximum number of tries before giving up and returning a non-zero error code. When 0 is specified, or there are no arguments, the number of tries will not be limited. + The second and third arguments are the maximum allowed remaining correction of the system clock and the maximum allowed skew (in ppm) as reported by the <> command in the *System time* and *Skew* fields. If not 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: + ---- waitsync 60 0.01 ---- + which will wait up to about 10 minutes (60 times 10 seconds) for *chronyd* to synchronise to a source and the remaining correction to be less than 10 milliseconds. === Time sources [[sources]]*sources* [*-a*] [*-v*]:: This command displays information about the current time sources that *chronyd* is accessing. + If the *-a* option is specified, all sources are displayed, including those that do not have a known address yet. Such sources have an identifier in the format _ID#XXXXXXXXXX_, which can be used in other commands expecting a source address. + The *-v* option enables a verbose output. In this case, extra caption lines are shown as a reminder of the meanings of the columns. + ---- MS Name/IP address Stratum Poll Reach LastRx Last sample =============================================================================== #* GPS0 0 4 377 11 -479ns[ -621ns] +/- 134ns ^? foo.example.net 2 6 377 23 -923us[ -924us] +/- 43ms ^+ bar.example.net 1 6 377 21 -2629us[-2619us] +/- 86ms ---- + The columns are as follows: + *M*::: This indicates the mode of the source. _^_ means a server, _=_ means a peer and _#_ indicates a locally connected reference clock. *S*::: This column indicates the selection state of the source. * _*_ indicates the best source which is currently selected for synchronisation. * _+_ indicates other sources selected for synchronisation, which are combined with the best source. * _-_ indicates a source which is considered to be selectable for synchronisation, but not currently selected. * _x_ indicates a source which *chronyd* thinks is a falseticker (i.e. its time is inconsistent with a majority of other sources, or sources specified with the *trust* option). * _~_ indicates a source whose time appears to have too much variability. * _?_ indicates a source which is not considered to be selectable for synchronisation for other reasons (e.g. unreachable, not synchronised, or does not have enough measurements). {blank}::: The <> command can be used to get more details about the selection state. *Name/IP address*::: 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 received sample. Stratum 1 indicates a computer with a locally attached reference clock. A computer that is synchronised to a stratum 1 computer is at stratum 2. A computer that is synchronised to a stratum 2 computer is at stratum 3, and so on. *Poll*::: This shows the rate at which the source is being polled, as a base-2 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 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 good sample (which is shown in the next column) was received from the source. Measurements that failed some tests are ignored. This is normally in seconds. The letters _m_, _h_, _d_ or _y_ indicate 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 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 ahead of the source. [[sourcestats]]*sourcestats* [*-a*] [*-v*]:: The *sourcestats* command displays information about the drift rate and offset estimation process for each of the sources currently being examined by *chronyd*. + If the *-a* option is specified, all sources are displayed, including those that do not have a known address yet. Such sources have an identifier in the format _ID#XXXXXXXXXX_, which can be used in other commands expecting a source address. + The *-v* option enables a verbose output. In this case, extra caption lines are shown as a reminder of the meanings of the columns. + An example report is: + ---- Name/IP Address NP NR Span Frequency Freq Skew Offset Std Dev =============================================================================== 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 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 regression through these points. *NR*::: This is the number of runs of residuals having the same sign following the last regression. If this number starts to become too small relative to the number of samples, it indicates that a straight line is no longer a good fit to the data. If the number of runs is too low, *chronyd* discards older samples and re-runs the regression until the number of runs becomes acceptable. *Span*::: This is the interval between the oldest and newest samples. If no unit is shown the value is in seconds. In the example, the interval is 46 minutes. *Frequency*::: This is the estimated residual frequency for the server, in parts per million. In this case, the computer's clock is estimated to be running 1 part in 10^9 slow relative to the server. *Freq Skew*::: This is the estimated error bounds on *Freq* (again in parts per million). *Offset*::: This is the estimated offset of the source. *Std Dev*::: This is the estimated sample standard deviation. [[selectdata]]*selectdata* [*-a*] [*-v*]:: The *selectdata* command displays information specific to the selection of time sources. If the *-a* option is specified, all sources are displayed, including those that do not have a known address yet. With the *-v* option, extra caption lines are shown as a reminder of the meanings of the columns. + An example of the output is shown below. + ---- S Name/IP Address Auth COpts EOpts Last Score Interval Leap ======================================================================= D foo.example.net Y ----- --TR- 4 1.0 -61ms +62ms N * bar.example.net N ----- ----- 0 1.0 -6846us +7305us N + baz.example.net N ----- ----- 10 1.0 -7381us +7355us N ---- + The columns are as follows: + *S*::: This column indicates the state of the source after the last source selection. It is similar to the state reported by the *sources* command, but more states are reported. {blank}::: The following states indicate the source is not considered selectable for synchronisation: * _N_ - has the *noselect* option. * _M_ - does not have enough measurements. * _d_ - has a root distance larger than the maximum distance (configured by the <> directive). * _~_ - has a jitter larger than the maximum jitter (configured by the <> directive). * _w_ - waits for other sources to get out of the _M_ state. * _S_ - has older measurements than other sources. * _O_ - has a stratum equal or larger than the orphan stratum (configured by the <> directive). * _T_ - does not fully agree with sources that have the *trust* option. * _x_ - does not agree with other sources (falseticker). {blank}::: The following states indicate the source is considered selectable, but it is not currently used for synchronisation: * _W_ - waits for other sources to be selectable (required by the <> directive, or the *require* option of another source). * _P_ - another selectable source is preferred due to the *prefer* option. * _U_ - waits for a new measurement (after selecting a different best source). * _D_ - has, or recently had, a root distance which is too large to be combined with other sources (configured by the <> directive). {blank}::: The following states indicate the source is used for synchronisation of the local clock: * _+_ - combined with the best source. * _*_ - selected as the best source to update the reference data (e.g. root delay, root dispersion). *Name/IP address*::: This column shows the name or IP address of the source if it is an NTP server, or the reference ID if it is a reference clock. *Auth*::: This column indicites whether an authentication mechanism is enabled for the source. _Y_ means yes and _N_ means no. *COpts*::: This column displays the configured selection options of the source. * _N_ indicates the *noselect* option. * _P_ indicates the *prefer* option. * _T_ indicates the *trust* option. * _R_ indicates the *require* option. *EOpts*::: This column displays the current effective selection options of the source, which can be different from the configured options due to the authentication selection mode (configured by the <> directive). The symbols are the same as in the *COpts* column. *Last*::: This column displays how long ago was the last measurement of the source made when the selection was performed. *Score*::: This column displays the current score against the source in the _*_ state. The scoring system avoids frequent reselection when multiple sources have a similar root distance. A value larger than 1 indicates this source was better than the _*_ source in recent selections. If the score reaches 10, the best source will be reselected and the scores will be reset to 1. *Interval*::: This column displays the lower and upper endpoint of the interval which was expected to contain the true offset of the local clock considering the root distance at the time of the selection. *Leap*::: This column displays the current leap status of the source. * _N_ indicates the normal status (no leap second). * _+_ indicates that a leap second will be inserted at the end of the month. * _-_ indicates that a leap second will be deleted at the end of the month. * _?_ indicates the unknown status (i.e. no valid measurement was made). [[reselect]]*reselect*:: 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. + The *reselect* command can be used to force *chronyd* to reselect the best synchronisation source. [[reselectdist]]*reselectdist* _distance_:: The *reselectdist* command sets the reselection distance. It is equivalent to the <> directive in the configuration file. === NTP sources [[activity]]*activity*:: 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 and peers in 5 states: + *online*::: the server or peer is currently online (i.e. assumed by *chronyd* to be reachable) *offline*::: 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 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 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 or peer was not resolved to an address yet; this source is not visible in the *sources* and *sourcestats* reports. [[authdata]]*authdata* [*-a*]:: The *authdata* command displays information specific to authentication of NTP sources. If the *-a* option is specified, all sources are displayed, including those that do not have a known address yet. An example of the output is shown below. + ---- Name/IP address Mode KeyID Type KLen Last Atmp NAK Cook CLen ========================================================================= foo.example.net NTS 1 15 256 135m 0 0 8 100 bar.example.net SK 30 13 128 - 0 0 0 0 baz.example.net - 0 0 0 - 0 0 0 0 ---- + The columns are as follows: + *Name/IP address*::: This column shows the name or the IP address of the source. *Mode*::: This column shows which mechanism authenticates NTP packets received from the source. _NTS_ means Network Time Security, _SK_ means a symmetric key, and _-_ means authentication is disabled. *KeyID*::: This column shows an identifier of the key used for authentication. With a symmetric key, it is the ID from the <>. With NTS, it is a number starting at zero and incremented by one with each successful key establishment using the NTS-KE protocol, i.e. it shows how many times the key establishment was performed with this source. *Type*::: This columns shows an identifier of the algorithm used for authentication. With a symmetric key, it is the hash function or cipher specified in the key file. With NTS, it is an authenticated encryption with associated data (AEAD) algorithm, which is negotiated in the NTS-KE protocol. The following values can be reported: * 1: MD5 * 2: SHA1 * 3: SHA256 * 4: SHA384 * 5: SHA512 * 6: SHA3-224 * 7: SHA3-256 * 8: SHA3-384 * 9: SHA3-512 * 10: TIGER * 11: WHIRLPOOL * 13: AES128 * 14: AES256 * 15: AEAD-AES-SIV-CMAC-256 *KLen*::: This column shows the length of the key in bits. *Last*::: This column shows how long ago the last successful key establishment was performed. It is in seconds, or letters _m_, _h_, _d_ or _y_ indicate minutes, hours, days, or years. *Atmp*::: This column shows the number of attempts to perform the key establishment since the last successful key establishment. A number larger than 1 indicates a problem with the network or server. *NAK*::: This column shows whether an NTS NAK was received since the last request. A NAK indicates that authentication failed on the server side due to *chronyd* using a cookie which is no longer valid and that it needs to perform the key establishment again in order to get new cookies. *Cook*::: This column shows the number of NTS cookies that *chronyd* currently has. If the key establishment was successful, a number smaller than 8 indicates a problem with the network or server. *CLen*::: This column shows the length in bytes of the NTS cookie which will be used in the next request. [[ntpdata]]*ntpdata* [_address_]:: The *ntpdata* command displays the last valid measurement and other NTP-specific information about the specified NTP source, or all NTP sources (with a known address) if no address was specified. An example of the output is shown below. + ---- Remote address : 203.0.113.15 (CB00710F) Remote port : 123 Local address : 203.0.113.74 (CB00714A) Leap status : Normal Version : 4 Mode : Server Stratum : 1 Poll interval : 10 (1024 seconds) Precision : -24 (0.000000060 seconds) Root delay : 0.000015 seconds Root dispersion : 0.000015 seconds Reference ID : 47505300 (GPS) Reference time : Fri Nov 25 15:22:12 2016 Offset : -0.000060878 seconds Peer delay : 0.000175634 seconds Peer dispersion : 0.000000681 seconds Response time : 0.000053050 seconds Jitter asymmetry: +0.00 NTP tests : 111 111 1111 Interleaved : No Authenticated : No TX timestamping : Kernel RX timestamping : Kernel Total TX : 24 Total RX : 24 Total valid RX : 24 ---- + The fields are explained as follows: + *Remote address*::: The IP address of the NTP server or peer, and the corresponding reference ID. *Remote port*::: The UDP port number to which the request was sent. The standard NTP port is 123. *Local address*::: The local IP address which received the response, and the corresponding reference ID. *Leap status*::: *Version*::: *Mode*::: *Stratum*::: *Poll interval*::: *Precision*::: *Root delay*::: *Root dispersion*::: *Reference ID*::: *Reference time*::: The NTP values from the last valid response. *Offset*::: *Peer delay*::: *Peer dispersion*::: The measured values. *Response time*::: The time the server or peer spent in processing of the request and waiting before sending the response. *Jitter asymmetry*::: The estimated asymmetry of network jitter on the path to the source. The asymmetry can be between -0.5 and 0.5. A negative value means the delay of packets sent to the source is more variable than the delay of packets sent from the source back. *NTP tests*::: Results of RFC 5905 tests 1 through 3, 5 through 7, and tests for maximum delay, delay ratio, delay dev ratio, and synchronisation loop. *Interleaved*::: This shows if the response was in the interleaved mode. *Authenticated*::: This shows if the response was authenticated. *TX timestamping*::: The source of the local transmit timestamp. Valid values are _Daemon_, _Kernel_, and _Hardware_. *RX timestamping*::: The source of the local receive timestamp. *Total TX*::: The number of packets sent to the source. *Total RX*::: The number of all packets received from the source. *Total valid RX*::: The number of valid packets received from the source. [[add_peer]]*add peer* _name_ [_option_]...:: The *add peer* command allows a new NTP peer to be added whilst *chronyd* is running. + Following the words *add peer*, the syntax of the following parameters and options is identical to that for the <> directive in the configuration file. + An example of using this command is shown below. + ---- add peer foo.example.net minpoll 6 maxpoll 10 key 25 ---- [[add_pool]]*add pool* _name_ [_option_]...:: The *add pool* command allows a pool of NTP servers to be added whilst *chronyd* is running. + Following the words *add pool*, the syntax of the following parameters and options is identical to that for the <> directive in the configuration file. + An example of using this command is shown below: + ---- add pool foo.example.net maxsources 3 iburst ---- [[add_server]]*add server* _name_ [_option_]...:: The *add server* command allows a new NTP server to be added whilst *chronyd* is running. + Following the words *add server*, the syntax of the following parameters and options is identical to that for the <> directive in the configuration file. + An example of using this command is shown below: + ---- add server foo.example.net minpoll 6 maxpoll 10 key 25 ---- [[delete]]*delete* _address_:: The *delete* command allows an NTP server or peer to be removed from the current set of sources. [[burst]] *burst* _good_/_max_ [_mask_/_masked-address_]:: *burst* _good_/_max_ [_masked-address_/_masked-bits_]:: *burst* _good_/_max_ [_address_]:: The *burst* command tells *chronyd* to make a set of measurements to each of its NTP sources over a short duration (rather than the usual periodic measurements that it makes). After such a burst, *chronyd* will revert to the previous state for each source. This might be either online, if the source was being periodically measured in the normal way, or offline, if the source had been indicated as being offline. (A source can be switched between the online and offline states with the <> and <> commands.) + The _mask_ and _masked-address_ arguments are optional, in which case *chronyd* will initiate a burst for all of its currently defined sources. + The arguments have the following meaning and format: + _good_::: This defines the number of good measurements that *chronyd* will want to obtain from each source. A measurement is good if it passes certain tests, for example, the round trip time to the source must be acceptable. (This allows *chronyd* to reject measurements that are likely to be bogus.) _max_::: This defines the maximum number of measurements that *chronyd* will attempt to make, even if the required number of good measurements has not been obtained. _mask_::: This is an IP address with which the IP address of each of *chronyd*'s sources is to be masked. _masked-address_::: This is an IP address. If the masked IP address of a source matches this value then the burst command is applied to that source. _masked-bits_::: This can be used with _masked-address_ for CIDR notation, which is a shorter alternative to the form with mask. _address_::: This is an IP address or a hostname. The burst command is applied only to that source. {blank}:: + 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: + ---- burst 2/10 ---- + 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: + ---- burst 2/10 255.255.0.0/1.2.0.0 burst 2/10 2001:db8:789a::/48 ---- + In the first case, the two out of ten sampling will only be applied to sources 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: + ---- burst 2/10 foo.example.net ---- [[maxdelay]]*maxdelay* _address_ _delay_:: This allows the *maxdelay* option for one of the sources to be modified, in the same way as specifying the *maxdelay* option for the <> directive in the configuration file. [[maxdelaydevratio]]*maxdelaydevratio* _address_ _ratio_:: This allows the *maxdelaydevratio* option for one of the sources to be modified, in the same way as specifying the *maxdelaydevratio* option for the <> directive in the configuration file. [[maxdelayratio]]*maxdelayratio* _address_ _ratio_:: This allows the *maxdelayratio* option for one of the sources to be modified, in the same way as specifying the *maxdelayratio* option for the <> directive in the configuration file. [[maxpoll]]*maxpoll* _address_ _maxpoll_:: The *maxpoll* command is used to modify the maximum polling interval for one of the current set of sources. It is equivalent to the *maxpoll* option in the <> directive in the configuration file. + Note that the new maximum polling interval only takes effect after the next measurement has been made. [[minpoll]]*minpoll* _address_ _minpoll_:: The *minpoll* command is used to modify the minimum polling interval for one of the current set of sources. It is equivalent to the *minpoll* option in the <> directive in the configuration file. + Note that the new minimum polling interval only takes effect after the next measurement has been made. [[minstratum]]*minstratum* _address_ _minstratum_:: The *minstratum* command is used to modify the minimum stratum for one of the current set of sources. It is equivalent to the *minstratum* option in the <> directive in the configuration file. [[offline]] *offline* [_address_]:: *offline* [_masked-address_/_masked-bits_]:: *offline* [_mask_/_masked-address_]:: The *offline* command is used to warn *chronyd* that the network connection to a particular host or hosts is about to be lost, e.g. on computers with intermittent connection to their time sources. + Another case where *offline* could be used is where a computer serves time to a 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 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 (including sources that do not have a known address yet). The second form allows an IP address mask and a masked 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. + ---- offline offline 255.255.255.0/1.2.3.0 offline 2001:db8:789a::/48 offline foo.example.net ---- + 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 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 equivalent to: + ---- offline 0.0.0.0/0.0.0.0 offline ::/0 ---- [[online]] *online* [_address_]:: *online* [_masked-address_/_masked-bits_]:: *online* [_mask_/_masked-address_]:: The *online* command is opposite in function to the <> command. It is used to advise *chronyd* that network connectivity to a particular source or sources has been restored. + The syntax is identical to that of the <> command. [[onoffline]] *onoffline*:: The *onoffline* command tells *chronyd* to switch all sources that have a known address to the online or offline status according to the current network configuration. A source is considered online if it is possible to send requests to it, i.e. a network route to the source is present. [[polltarget]]*polltarget* _address_ _polltarget_:: The *polltarget* command is used to modify the poll target for one of the current set of sources. It is equivalent to the *polltarget* option in the <> directive in the configuration file. [[refresh]]*refresh*:: The *refresh* command can be used to force *chronyd* to resolve the names of 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 can still be useful to replace them immediately and not wait until they are marked as unreachable. [[reload]]*reload* *sources*:: The *reload sources* command causes *chronyd* to re-read all _*.sources_ files from the directories specified by the <> directive. [[sourcename]]*sourcename* _address_:: The *sourcename* command prints the original hostname or address that was specified for an NTP source in the configuration file, or the *add* command. This command is an alternative to the *-N* option, which can be useful in scripts. + Note that different NTP sources can share the same name, e.g. servers from a pool. === Manual time input [[manual]] *manual* *on*:: *manual* *off*:: *manual* *delete* _index_:: *manual* *list*:: *manual* *reset*:: The manual command enables and disables use of the <> command, and is used to modify the behaviour of the manual clock driver. + The *on* form of the command enables use of the *settime* command. + The *off* form of the command disables use of the *settime* command. + The *list* form of the command lists all the samples currently stored in *chronyd*. The output is illustrated below. + ---- 210 n_samples = 1 # Date Time(UTC) Slewed Original Residual ==================================================== 0 27Jan99 22:09:20 0.00 0.97 0.00 ---- + The columns are as as follows: + . The sample index (used for the *manual delete* command). . The date and time of the sample. . The system clock error when the timestamp was entered, adjusted to allow for changes made to the system clock since. . The system clock error when the timestamp was entered, as it originally was (without allowing for changes to the system clock since). . The regression residual at this point, in seconds. This allows '`outliers`' to be easily spotted, so that they can be deleted using the *manual delete* command. {blank}:: + The *delete* form of the command deletes a single sample. The parameter is the 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 they have entered a very poor timestamp. + The *reset* form of the command deletes all samples at once. The system clock 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 can be configured either with the <> directive in the configuration file, or with the <> command of *chronyc*.) + It should be noted that the computer's sense of time will only be as accurate as the reference you use for providing this input (e.g. your watch), as well as how well you can time the press of the return key. + Providing your computer's time zone is set up properly, you will be able to enter a local time (rather than UTC). + The response to a successful *settime* command indicates the amount that the computer's clock was wrong. It should be apparent from this if you have entered the time wrongly, e.g. with the wrong time zone. + The rate of drift of the system clock is estimated by a regression process using the entered measurement and all previous measurements entered during the 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 <> command, where the intercept is used to set the 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: + ---- settime 16:30 settime 16:30:05 settime Nov 21, 2015 16:30:05 ---- + For a full description of getdate, see the getdate documentation (bundled, for example, with the source for GNU tar). === NTP access [[accheck]]*accheck* _address_:: This command allows you to check whether client NTP access is allowed from a particular host. + Examples of use, showing a named host and a numeric IP address, are as follows: + ---- accheck foo.example.net accheck 1.2.3.4 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 *chronyd*'s configuration file. [[clients]]*clients* [*-p* _packets_] [*-k*] [*-r*]:: This command shows a list of clients that have accessed the server, through the NTP, command, or NTS-KE port. It does not include accesses over the Unix domain command socket. + The *-p* option specifies the minimum number of received NTP or command packets, or accepted NTS-KE connections, needed to include a client in the list. The default value is 0, i.e. all clients are reported. With the *-k* option the last four columns will show the NTS-KE accesses instead of command accesses. If the *-r* option is specified, *chronyd* will reset the counters of received and dropped packets or connections after reporting the current values. + An example of the output is: + ---- Hostname NTP Drop Int IntL Last Cmd Drop Int Last =============================================================================== localhost 2 0 2 - 133 15 0 -1 7 foo.example.net 12 0 6 - 23 0 0 - - ---- + Each row shows the data for a single host. Only hosts that have passed the host access checks (set with the <>, <>, <> and <> commands or configuration file directives) are logged. The intervals are displayed as a power of 2 in seconds. + The columns are as follows: + . The hostname of the client. . The number of NTP packets received from the client. . The number of NTP packets dropped to limit the response rate. . The average interval between NTP packets. . The average interval between NTP packets after limiting the response rate. . Time since the last NTP packet was received . The number of command packets or NTS-KE connections received/accepted from the client. . The number of command packets or NTS-KE connections dropped to limit the response rate. . The average interval between command packets or NTS-KE connections. . Time since the last command packet or NTS-KE connection was received/accepted. [[serverstats]]*serverstats*:: The *serverstats* command displays how many valid NTP and command requests, and NTS-KE connections, *chronyd* operating as a server received from clients, and how many of them were dropped due to rate limiting. It also displays how many client log records were dropped due to the memory limit configured by the <> directive and how many of the NTP requests (from those which were not dropped) were authenticated. An example of the output is shown below. + ---- NTP packets received : 1598 NTP packets dropped : 8 Command packets received : 19 Command packets dropped : 0 Client log records dropped : 0 NTS-KE connections accepted: 3 NTS-KE connections dropped : 0 Authenticated NTP packets : 189 ---- [[allow]]*allow* [*all*] [_subnet_]:: The effect of the allow command is identical to the <> directive in the configuration file. + The syntax is illustrated in the following examples: + ---- allow foo.example.net allow all 1.2 allow 3.4.5 allow 6.7.8/22 allow 6.7.8.9/22 allow 2001:db8:789a::/48 allow 0/0 allow ::/0 allow allow all ---- [[deny]]*deny* [*all*] [_subnet_]:: The effect of the allow command is identical to the <> directive in the configuration file. + The syntax is illustrated in the following examples: + ---- deny foo.example.net deny all 1.2 deny 3.4.5 deny 6.7.8/22 deny 6.7.8.9/22 deny 2001:db8:789a::/48 deny 0/0 deny ::/0 deny deny all ---- [[local]] *local* [_option_]...:: *local* *off*:: The *local* command allows *chronyd* to be told that it is to appear as a reference source, even if it is not itself properly synchronised to an external source. (This can be used on isolated networks, to allow one computer to be a master time server with the other computers slaving to it.) + The first form enables the local reference mode on the host. The syntax is identical to the <> directive in the configuration file. + The second form disables the local reference mode. [[smoothing]]*smoothing*:: The *smoothing* command displays the current state of the NTP server time smoothing, which can be enabled with the <> directive. An example of the output is shown below. + ---- Active : Yes Offset : +1.000268817 seconds Frequency : -0.142859 ppm Wander : -0.010000 ppm per second Last update : 17.8 seconds ago Remaining time : 19988.4 seconds ---- + The fields are explained as follows: + *Active*::: This shows if the server time smoothing is currently active. Possible values are _Yes_ and _No_. If the *leaponly* option is included in the *smoothtime* directive, _(leap second only)_ will be shown on the line. *Offset*::: This is the current offset applied to the time sent to NTP clients. Positive value means the clients are getting time that's ahead of true time. *Frequency*::: The current frequency offset of the served time. Negative value means the time observed by clients is running slower than true time. *Wander*::: 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 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 frequency if there were no more updates. [[smoothtime]] *smoothtime* *activate*:: *smoothtime* *reset*:: The *smoothtime* command can be used to activate or reset the server time smoothing process if it is configured with the <> directive. === Monitoring access [[cmdaccheck]]*cmdaccheck* _address_:: This command is similar to the <> command, except that it is used to check whether monitoring access is permitted from a named host. + Examples of use are as follows: + ---- cmdaccheck foo.example.net cmdaccheck 1.2.3.4 cmdaccheck 2001:db8::1 ---- [[cmdallow]]*cmdallow* [*all*] [_subnet_]:: This is similar to the <> command, except that it is used to allow particular hosts or subnets to use *chronyc* to monitor with *chronyd* on the current host. [[cmddeny]]*cmddeny* [*all*] [_subnet_]:: This is similar to the <> command, except that it is used to allow particular hosts or subnets to use *chronyc* to monitor *chronyd* on the current host. === Real-time clock (RTC) [[rtcdata]]*rtcdata*:: The *rtcdata* command displays the current RTC parameters. + An example output is shown below. + ---- RTC ref time (GMT) : Sat May 30 07:25:56 2015 Number of samples : 10 Number of runs : 5 Sample span period : 549 RTC is fast by : -1.632736 seconds RTC gains time at : -107.623 ppm ---- + 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 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 indicates that the measurements are not well approximated by a linear model, and that the algorithm will tend to delete the older measurements to improve 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 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 might (or might not) want to use the <> 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.) *RTC gains time at*::: This is the amount of time gained (positive) or lost (negative) by the real time clock for each second that it ticks. It is measured in parts per million. So if the value shown was +1, suppose the RTC was exactly right when it crosses a particular second boundary. Then it would be 1 microsecond fast when it crosses its next second boundary. [[trimrtc]]*trimrtc*:: The *trimrtc* command is used to correct the system's real-time clock (RTC) to the main system clock. It has no effect if the error between the two clocks is 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 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 the RTC and the system clock (i.e. the remaining fraction of a second error). . Save the RTC parameters to the RTC file (specified with the <> directive in the configuration file). {blank}:: + The last step is done as a precaution against the computer suffering a power failure before either the daemon exits or the <> command is issued. + *chronyd* will still work perfectly well both whilst operating and across machine reboots even if the *trimrtc* command is never used (and the RTC is allowed to drift away from true time). The *trimrtc* command is provided as a method by which it can be corrected, in a manner compatible with *chronyd* using it to maintain accurate time across machine reboots. + The *trimrtc* command can be executed automatically by *chronyd* with the <> directive in the configuration file. [[writertc]]*writertc*:: The *writertc* command writes the currently estimated error and gain or loss rate parameters for the RTC to the RTC file (specified with the <> directive). This information is also written automatically when *chronyd* is killed (by the SIGHUP, SIGINT, SIGQUIT or SIGTERM signals) or when the <> command is issued. === Other daemon commands [[cyclelogs]]*cyclelogs*:: The *cyclelogs* command causes all of *chronyd*'s open log files to be closed and re-opened. This allows them to be renamed so that they can be periodically purged. An example of how to do this is shown below. + ---- # mv /var/log/chrony/measurements.log /var/log/chrony/measurements1.log # chronyc cyclelogs # rm /var/log/chrony/measurements1.log ---- [[dump]]*dump*:: The *dump* command causes *chronyd* to write its current history of measurements for each of its sources to dump files in the directory specified in the configuration file by the <> directive and also write server NTS keys and client NTS cookies to the directory specified by the <> directive. Note that *chronyd* does this automatically when it exits. This command is mainly useful for inspection whilst *chronyd* is running. [[rekey]]*rekey*:: The *rekey* command causes *chronyd* to re-read the key file specified in the configuration file by the <> directive. It also re-reads the server NTS keys if <> is specified and <> is disabled in the configuration file. [[reset]]*reset* *sources*:: The *reset sources* command causes *chronyd* to drop all measurements and switch to the unsynchronised state. This command can help *chronyd* with recovery when the measurements are known to be no longer valid or accurate, e.g. due to moving the computer to a different network, or resuming the computer from a low-power state (which resets the system clock). *chronyd* will drop the measurements automatically when it detects the clock has made an unexpected jump, but the detection is not completely reliable. [[shutdown]]*shutdown*:: The *shutdown* command causes *chronyd* to exit. This is equivalent to sending the process the SIGTERM signal. === Client commands [[dns]]*dns* _option_:: The *dns* command configures how hostnames and IP addresses are resolved in *chronyc*. IP addresses can be resolved to hostnames when printing results of <>, <>, <> and <> commands. Hostnames are resolved in commands that take an address as argument. + There are five options: + *dns -n*::: Disables resolving IP addresses to hostnames. Raw IP addresses will be displayed. *dns +n*::: Enables resolving IP addresses to hostnames. This is the default unless *chronyc* was started with *-n* option. *dns -4*::: Resolves hostnames only to IPv4 addresses. *dns -6*::: Resolves hostnames only to IPv6 addresses. *dns -46*::: Resolves hostnames to both address families. This is the default behaviour unless *chronyc* was started with the *-4* or *-6* option. [[timeout]]*timeout* _timeout_:: The *timeout* command sets the initial timeout for *chronyc* requests in milliseconds. If no response is received from *chronyd*, the timeout is doubled and the request is resent. The maximum number of retries is configured with the <> command. + By default, the timeout is 1000 milliseconds. [[retries]]*retries* _retries_:: The *retries* command sets the maximum number of retries for *chronyc* requests before giving up. The response timeout is controlled by the <> command. + The default is 2. [[keygen]]*keygen* [_id_ [_type_ [_bits_]]]:: The *keygen* command generates a key that can be added to the key file (specified with the <> directive) to allow NTP authentication between server and client, or peers. The key is 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* or *peer* directives in the configuration file. The second argument is the name of the hash function or cipher (by default SHA1, or MD5 if SHA1 is not available). The third argument is the length of the key in bits if a hash function was selected, between 80 and 4096 bits (by default 160 bits). + An example is: + ---- keygen 73 SHA1 256 ---- + 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. A different key should be generated for each client or peer. + An example using the AES128 cipher is: + ---- keygen 151 AES128 ---- [[exit]]*exit*:: [[quit]]*quit*:: The *exit* and *quit* commands exit from *chronyc* and return the user to the shell. [[help]]*help*:: The *help* command displays a summary of the commands and their arguments. == SEE ALSO <>, <> == BUGS For instructions on how to report bugs, please visit https://chrony.tuxfamily.org/. == AUTHORS chrony was written by Richard Curnow, Miroslav Lichvar, and others.