1// This file is part of chrony 2// 3// Copyright (C) Richard P. Curnow 1997-2003 4// Copyright (C) Stephen Wadeley 2016 5// Copyright (C) Miroslav Lichvar 2009-2017, 2019-2020 6// 7// This program is free software; you can redistribute it and/or modify 8// it under the terms of version 2 of the GNU General Public License as 9// published by the Free Software Foundation. 10// 11// This program is distributed in the hope that it will be useful, but 12// WITHOUT ANY WARRANTY; without even the implied warranty of 13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14// General Public License for more details. 15// 16// You should have received a copy of the GNU General Public License along 17// with this program; if not, write to the Free Software Foundation, Inc., 18// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 19 20= chronyc(1) 21:doctype: manpage 22:man manual: User manual 23:man source: chrony @CHRONY_VERSION@ 24 25== NAME 26 27chronyc - command-line interface for chrony daemon 28 29== SYNOPSIS 30 31*chronyc* [_OPTION_]... [_COMMAND_]... 32 33== DESCRIPTION 34 35*chronyc* is a command-line interface program which can be used to monitor 36*chronyd*'s performance and to change various operating parameters whilst it is 37running. 38 39If no commands are specified on the command line, *chronyc* will expect input 40from the user. The prompt _chronyc>_ will be displayed when it is being run 41from a terminal. If *chronyc*'s input or output are redirected from or to a file, 42the prompt will not be shown. 43 44There are two ways *chronyc* can access *chronyd*. One is the Internet 45Protocol (IPv4 or IPv6) and the other is a Unix domain socket, which is 46accessible locally by the root or _chrony_ user. By default, *chronyc* first 47tries to connect to the Unix domain socket. The compiled-in default path is 48_@CHRONYRUNDIR@/chronyd.sock_. If that fails (e.g. because *chronyc* is 49running under a non-root user), it will try to connect to 127.0.0.1 and then 50::1. 51 52Only the following monitoring commands, which do not affect the behaviour of 53*chronyd*, are allowed from the network: *activity*, *manual list*, 54*rtcdata*, *smoothing*, *sourcename*, *sources*, *sourcestats*, *tracking*, 55*waitsync*. The 56set of hosts from which *chronyd* will accept these commands can be configured 57with the <<chrony.conf.adoc#cmdallow,*cmdallow*>> directive in the *chronyd*'s 58configuration file or the <<cmdallow,*cmdallow*>> command in *chronyc*. By 59default, the commands are accepted only from localhost (127.0.0.1 or ::1). 60 61All other commands are allowed only through the Unix domain socket. When sent 62over the network, *chronyd* will respond with a '`Not authorised`' error, even 63if it is from localhost. 64 65Having full access to *chronyd* via *chronyc* is more or less equivalent to 66being able to modify the *chronyd*'s configuration file and restart it. 67 68== OPTIONS 69 70*-4*:: 71With this option hostnames will be resolved only to IPv4 addresses. 72 73*-6*:: 74With this option hostnames will be resolved only to IPv6 addresses. 75 76*-n*:: 77This option disables resolving of IP addresses to hostnames, e.g. to avoid slow 78DNS lookups. Long addresses will not be truncated to fit into the column. 79 80*-N*:: 81This option enables printing of original hostnames or IP addresses of NTP 82sources that were specified in the configuration file, or *chronyc* commands. 83Without the *-n* and *-N* option, the printed hostnames are obtained from 84reverse DNS lookups and can be different from the specified hostnames. 85 86*-c*:: 87This option enables printing of reports in a comma-separated values (CSV) 88format. Reverse DNS lookups will be disabled, time will be printed as number of 89seconds since the epoch, and values in seconds will not be converted to other 90units. 91 92*-d*:: 93This option enables printing of debugging messages if *chronyc* was compiled 94with debugging support. 95 96*-m*:: 97Normally, all arguments on the command line are interpreted as one command. 98With this option multiple commands can be specified. Each argument will be 99interpreted as a whole command. 100 101*-h* _host_:: 102This option allows the user to specify which host (or comma-separated list of 103addresses) running the *chronyd* program is to be contacted. This allows for 104remote monitoring, without having to connect over SSH to the other host first. 105+ 106The default is to contact *chronyd* running on the same host where 107*chronyc* is being run. 108 109*-p* _port_:: 110This option allows the user to specify the UDP port number which the target 111*chronyd* is using for its monitoring connections. This defaults to 323; there 112would rarely be a need to change this. 113 114*-f* _file_:: 115This option is ignored and is provided only for compatibility. 116 117*-a*:: 118This option is ignored and is provided only for compatibility. 119 120*-v*, *--version*:: 121With this option *chronyc* displays its version number on the terminal and 122exits. 123 124*--help*:: 125With this option *chronyc* displays a help message on the terminal and 126exits. 127 128== COMMANDS 129 130This section describes each of the commands available within the *chronyc* 131program. 132 133=== System clock 134 135[[tracking]]*tracking*:: 136The *tracking* command displays parameters about the system's clock 137performance. An example of the output is shown below. 138+ 139---- 140Reference ID : CB00710F (foo.example.net) 141Stratum : 3 142Ref time (UTC) : Fri Jan 27 09:49:17 2017 143System time : 0.000006523 seconds slow of NTP time 144Last offset : -0.000006747 seconds 145RMS offset : 0.000035822 seconds 146Frequency : 3.225 ppm slow 147Residual freq : -0.000 ppm 148Skew : 0.129 ppm 149Root delay : 0.013639022 seconds 150Root dispersion : 0.001100737 seconds 151Update interval : 64.2 seconds 152Leap status : Normal 153---- 154+ 155The fields are explained as follows: 156+ 157*Reference ID*::: 158This is the reference ID and name (or IP address) of the server to which the 159computer is currently synchronised. For IPv4 addresses, the reference ID is 160equal to the address and for IPv6 addresses it is the first 32 bits of the MD5 161sum of the address. 162+ 163If the reference ID is _7F7F0101_ and there is no name or IP address, it means 164the computer is not synchronised to any external source and that you have the 165_local_ mode operating (via the <<local,*local*>> command in *chronyc*, or the 166<<chrony.conf.adoc#local,*local*>> directive in the configuration file). 167+ 168The reference ID is printed as a hexadecimal number. Note that in older 169versions it used to be printed in quad-dotted notation and could be confused 170with an IPv4 address. 171*Stratum*::: 172The stratum indicates how many hops away from a computer with an attached 173reference clock we are. Such a computer is a stratum-1 computer, so the 174computer in the example is two hops away (i.e. _foo.example.net_ is a 175stratum-2 and is synchronised from a stratum-1). 176*Ref time*::: 177This is the time (UTC) at which the last measurement from the reference 178source was processed. 179*System time*::: 180In normal operation, *chronyd* by default never steps the system clock, because 181any jump in the time can have adverse consequences for certain application 182programs. Instead, any error in the system clock is corrected by slightly 183speeding up or slowing down the system clock until the error has been removed, 184and then returning to the system clock's normal speed. A consequence of this is 185that there will be a period when the system clock (as read by other programs) 186will be different from *chronyd*'s estimate of the current true time (which it 187reports to NTP clients when it is operating as a server). The value reported 188on this line is the difference due to this effect. 189*Last offset*::: 190This is the estimated local offset on the last clock update. A positive value 191indicates the local time (as previously estimated true time) was ahead of the 192time sources. 193*RMS offset*::: 194This is a long-term average of the offset value. 195*Frequency*::: 196The '`frequency`' is the rate by which the system's clock would be wrong if 197*chronyd* was not correcting it. It is expressed in ppm (parts per million). 198For example, a value of 1 ppm would mean that when the system's clock thinks it 199has advanced 1 second, it has actually advanced by 1.000001 seconds relative to 200true time. 201*Residual freq*::: 202This shows the '`residual frequency`' for the currently selected reference 203source. This reflects any difference between what the measurements from the 204reference source indicate the frequency should be and the frequency currently 205being used. 206+ 207The reason this is not always zero is that a smoothing procedure is 208applied to the frequency. Each time a measurement from the reference 209source is obtained and a new residual frequency computed, the estimated 210accuracy of this residual is compared with the estimated accuracy (see 211'`skew`' next) of the existing frequency value. A weighted average is 212computed for the new frequency, with weights depending on these accuracies. 213If the measurements from the reference source follow a consistent trend, the 214residual will be driven to zero over time. 215*Skew*::: 216This is the estimated error bound on the frequency. 217*Root delay*::: 218This is the total of the network path delays to the stratum-1 computer from 219which the computer is ultimately synchronised. 220*Root dispersion*::: 221This is the total dispersion accumulated through all the computers back to 222the stratum-1 computer from which the computer is ultimately synchronised. 223Dispersion is due to system clock resolution, statistical measurement 224variations, etc. 225+ 226An absolute bound on the computer's clock accuracy (assuming the stratum-1 227computer is correct) is given by: 228+ 229---- 230clock_error <= |system_time_offset| + root_dispersion + (0.5 * root_delay) 231---- 232*Update interval*::: 233This is the interval between the last two clock updates. 234*Leap status*::: 235This is the leap status, which can be _Normal_, _Insert second_, _Delete 236second_ or _Not synchronised_. 237 238[[makestep]]*makestep*:: 239*makestep* _threshold_ _limit_:: 240Normally *chronyd* will cause the system to gradually correct any time offset, 241by slowing down or speeding up the clock as required. In certain situations, 242the system clock might be so far adrift that this slewing process would take a 243very long time to correct the system clock. 244+ 245The *makestep* command can be used in this situation. There are two forms of 246the command. The first form has no parameters. It tells *chronyd* to cancel any 247remaining correction that was being slewed and jump the system clock by the 248equivalent amount, making it correct immediately. 249+ 250The second form configures the automatic stepping, similarly to the 251<<chrony.conf.adoc#makestep,*makestep*>> directive. It has two parameters, 252stepping threshold (in seconds) and number of future clock updates for which 253the threshold will be active. This can be used with the <<burst,*burst*>> 254command to quickly make a new measurement and correct the clock by stepping if 255needed, without waiting for *chronyd* to complete the measurement and update 256the clock. 257+ 258---- 259makestep 0.1 1 260burst 1/2 261---- 262+ 263BE WARNED: Certain software will be seriously affected by such jumps in the 264system time. (That is the reason why *chronyd* uses slewing normally.) 265 266[[maxupdateskew]]*maxupdateskew* _skew-in-ppm_:: 267This command has the same effect as the 268<<chrony.conf.adoc#maxupdateskew,*maxupdateskew*>> directive in the 269configuration file. 270 271[[waitsync]]*waitsync* [_max-tries_ [_max-correction_ [_max-skew_ [_interval_]]]]:: 272The *waitsync* command waits for *chronyd* to synchronise. 273+ 274Up to four optional arguments can be specified. The first is the maximum number 275of tries before giving up and returning a non-zero error code. When 0 is 276specified, or there are no arguments, the number of tries will not be limited. 277+ 278The second and third arguments are the maximum allowed remaining correction of 279the system clock and the maximum allowed skew (in ppm) as reported by the 280<<tracking,*tracking*>> command in the *System time* and *Skew* fields. If not 281specified or zero, the value will not be checked. 282+ 283The fourth argument is the interval specified in seconds in which the check is 284repeated. The interval is 10 seconds by default. 285+ 286An example is: 287+ 288---- 289waitsync 60 0.01 290---- 291+ 292which will wait up to about 10 minutes (60 times 10 seconds) for *chronyd* to 293synchronise to a source and the remaining correction to be less than 10 294milliseconds. 295 296=== Time sources 297 298[[sources]]*sources* [*-a*] [*-v*]:: 299This command displays information about the current time sources that *chronyd* 300is accessing. 301+ 302If the *-a* option is specified, all sources are displayed, including those that 303do not have a known address yet. Such sources have an identifier in the format 304_ID#XXXXXXXXXX_, which can be used in other commands expecting a source address. 305+ 306The *-v* option enables a verbose output. In this case, 307extra caption lines are shown as a reminder of the meanings of the columns. 308+ 309---- 310MS Name/IP address Stratum Poll Reach LastRx Last sample 311=============================================================================== 312#* GPS0 0 4 377 11 -479ns[ -621ns] +/- 134ns 313^? foo.example.net 2 6 377 23 -923us[ -924us] +/- 43ms 314^+ bar.example.net 1 6 377 21 -2629us[-2619us] +/- 86ms 315---- 316+ 317The columns are as follows: 318+ 319*M*::: 320This indicates the mode of the source. _^_ means a server, _=_ means a peer 321and _#_ indicates a locally connected reference clock. 322*S*::: 323This column indicates the selection state of the source. 324* _*_ indicates the best source which is currently selected for 325 synchronisation. 326* _+_ indicates other sources selected for synchronisation, which are combined 327 with the best source. 328* _-_ indicates a source which is considered to be selectable for 329 synchronisation, but not currently selected. 330* _x_ indicates a source which *chronyd* thinks is a falseticker (i.e. its 331 time is inconsistent with a majority of other sources, or sources specified 332 with the *trust* option). 333* _~_ indicates a source whose time appears to have too much variability. 334* _?_ indicates a source which is not considered to be selectable for 335 synchronisation for other reasons (e.g. unreachable, not synchronised, or 336 does not have enough measurements). 337{blank}::: 338The <<selectdata,*selectdata*>> command can be used to get more details about 339the selection state. 340*Name/IP address*::: 341This shows the name or the IP address of the source, or reference ID for reference 342clocks. 343*Stratum*::: 344This shows the stratum of the source, as reported in its most recently 345received sample. Stratum 1 indicates a computer with a locally attached 346reference clock. A computer that is synchronised to a stratum 1 computer is 347at stratum 2. A computer that is synchronised to a stratum 2 computer is at 348stratum 3, and so on. 349*Poll*::: 350This shows the rate at which the source is being polled, as a base-2 351logarithm of the interval in seconds. Thus, a value of 6 would indicate that 352a measurement is being made every 64 seconds. *chronyd* automatically varies 353the polling rate in response to prevailing conditions. 354*Reach*::: 355This shows the source's reachability register printed as an octal number. The 356register has 8 bits and is updated on every received or missed packet from 357the source. A value of 377 indicates that a valid reply was received for all 358from the last eight transmissions. 359*LastRx*::: 360This column shows how long ago the last good sample (which is shown in the next 361column) was received from the source. Measurements that failed some tests are 362ignored. This is normally in seconds. The letters _m_, _h_, _d_ or _y_ indicate 363minutes, hours, days, or years. 364*Last sample*::: 365This column shows the offset between the local clock and the source at the 366last measurement. The number in the square brackets shows the actual measured 367offset. This can be suffixed by _ns_ (indicating nanoseconds), _us_ 368(indicating microseconds), _ms_ (indicating milliseconds), or _s_ (indicating 369seconds). The number to the left of the square brackets shows the original 370measurement, adjusted to allow for any slews applied to the local clock 371since. The number following the _+/-_ indicator shows the margin of error in 372the measurement. Positive offsets indicate that the local clock is ahead of 373the source. 374 375[[sourcestats]]*sourcestats* [*-a*] [*-v*]:: 376The *sourcestats* command displays information about the drift rate and offset 377estimation process for each of the sources currently being examined by 378*chronyd*. 379+ 380If the *-a* option is specified, all sources are displayed, including those that 381do not have a known address yet. Such sources have an identifier in the format 382_ID#XXXXXXXXXX_, which can be used in other commands expecting a source address. 383+ 384The *-v* option enables a verbose output. In this case, 385extra caption lines are shown as a reminder of the meanings of the columns. 386+ 387An example report is: 388+ 389---- 390Name/IP Address NP NR Span Frequency Freq Skew Offset Std Dev 391=============================================================================== 392foo.example.net 11 5 46m -0.001 0.045 1us 25us 393---- 394+ 395The columns are as follows: 396+ 397*Name/IP Address*::: 398This is the name or IP address of the NTP server (or peer) or reference ID of the 399reference clock to which the rest of the line relates. 400*NP*::: 401This is the number of sample points currently being retained for the server. 402The drift rate and current offset are estimated by performing a linear 403regression through these points. 404*NR*::: 405This is the number of runs of residuals having the same sign following the 406last regression. If this number starts to become too small relative to the 407number of samples, it indicates that a straight line is no longer a good fit 408to the data. If the number of runs is too low, *chronyd* discards older 409samples and re-runs the regression until the number of runs becomes 410acceptable. 411*Span*::: 412This is the interval between the oldest and newest samples. If no unit is 413shown the value is in seconds. In the example, the interval is 46 minutes. 414*Frequency*::: 415This is the estimated residual frequency for the server, in parts per 416million. In this case, the computer's clock is estimated to be running 1 part 417in 10^9 slow relative to the server. 418*Freq Skew*::: 419This is the estimated error bounds on *Freq* (again in parts per million). 420*Offset*::: 421This is the estimated offset of the source. 422*Std Dev*::: 423This is the estimated sample standard deviation. 424 425[[selectdata]]*selectdata* [*-a*] [*-v*]:: 426The *selectdata* command displays information specific to the selection of time 427sources. If the *-a* option is specified, all sources are displayed, including 428those that do not have a known address yet. With the *-v* option, extra caption 429lines are shown as a reminder of the meanings of the columns. 430+ 431An example of the output is shown below. 432+ 433---- 434S Name/IP Address Auth COpts EOpts Last Score Interval Leap 435======================================================================= 436D foo.example.net Y ----- --TR- 4 1.0 -61ms +62ms N 437* bar.example.net N ----- ----- 0 1.0 -6846us +7305us N 438+ baz.example.net N ----- ----- 10 1.0 -7381us +7355us N 439---- 440+ 441The columns are as follows: 442+ 443*S*::: 444This column indicates the state of the source after the last source selection. 445It is similar to the state reported by the *sources* command, but more 446states are reported. 447{blank}::: 448The following states indicate the source is not considered selectable for 449synchronisation: 450* _N_ - has the *noselect* option. 451* _M_ - does not have enough measurements. 452* _d_ - has a root distance larger than the maximum distance (configured by the 453 <<chrony.conf.adoc#maxdistance,*maxdistance*>> directive). 454* _~_ - has a jitter larger than the maximum jitter (configured by the 455 <<chrony.conf.adoc#maxjitter,*maxjitter*>> directive). 456* _w_ - waits for other sources to get out of the _M_ state. 457* _S_ - has older measurements than other sources. 458* _O_ - has a stratum equal or larger than the orphan stratum (configured by 459 the <<chrony.conf.adoc#local,*local*>> directive). 460* _T_ - does not fully agree with sources that have the *trust* option. 461* _x_ - does not agree with other sources (falseticker). 462{blank}::: 463The following states indicate the source is considered selectable, but it is 464not currently used for synchronisation: 465* _W_ - waits for other sources to be selectable (required by the 466 <<chrony.conf.adoc#minsources,*minsources*>> directive, or 467 the *require* option of another source). 468* _P_ - another selectable source is preferred due to the *prefer* option. 469* _U_ - waits for a new measurement (after selecting a different best source). 470* _D_ - has, or recently had, a root distance which is too large to be combined 471 with other sources (configured by the 472 <<chrony.conf.adoc#combinelimit,*combinelimit*>> directive). 473{blank}::: 474The following states indicate the source is used for synchronisation of the 475local clock: 476* _+_ - combined with the best source. 477* _*_ - selected as the best source to update the reference data (e.g. root 478 delay, root dispersion). 479*Name/IP address*::: 480This column shows the name or IP address of the source if it is an NTP server, 481or the reference ID if it is a reference clock. 482*Auth*::: 483This column indicites whether an authentication mechanism is enabled for the 484source. _Y_ means yes and _N_ means no. 485*COpts*::: 486This column displays the configured selection options of the source. 487* _N_ indicates the *noselect* option. 488* _P_ indicates the *prefer* option. 489* _T_ indicates the *trust* option. 490* _R_ indicates the *require* option. 491*EOpts*::: 492This column displays the current effective selection options of the source, 493which can be different from the configured options due to the authentication 494selection mode (configured by the 495<<chrony.conf.adoc#authselmode,*authselmode*>> directive). The symbols are the 496same as in the *COpts* column. 497*Last*::: 498This column displays how long ago was the last measurement of the source made 499when the selection was performed. 500*Score*::: 501This column displays the current score against the source in the _*_ state. The 502scoring system avoids frequent reselection when multiple sources have a similar 503root distance. A value larger than 1 indicates this source was better than the 504_*_ source in recent selections. If the score reaches 10, the best source will 505be reselected and the scores will be reset to 1. 506*Interval*::: 507This column displays the lower and upper endpoint of the interval which was 508expected to contain the true offset of the local clock considering the root 509distance at the time of the selection. 510*Leap*::: 511This column displays the current leap status of the source. 512* _N_ indicates the normal status (no leap second). 513* _+_ indicates that a leap second will be inserted at the end of the month. 514* _-_ indicates that a leap second will be deleted at the end of the month. 515* _?_ indicates the unknown status (i.e. no valid measurement was made). 516 517[[reselect]]*reselect*:: 518To avoid excessive switching between sources, *chronyd* can stay synchronised 519to a source even when it is not currently the best one among the available 520sources. 521+ 522The *reselect* command can be used to force *chronyd* to reselect the best 523synchronisation source. 524 525[[reselectdist]]*reselectdist* _distance_:: 526The *reselectdist* command sets the reselection distance. It is equivalent to 527the <<chrony.conf.adoc#reselectdist,*reselectdist*>> directive in the 528configuration file. 529 530=== NTP sources 531 532[[activity]]*activity*:: 533This command reports the number of servers and peers that are online and 534offline. If the *auto_offline* option is used in specifying some of the servers 535or peers, the *activity* command can be useful for detecting when all of them 536have entered the offline state after the network link has been disconnected. 537+ 538The report shows the number of servers and peers in 5 states: 539+ 540*online*::: 541the server or peer is currently online (i.e. assumed by *chronyd* to be reachable) 542*offline*::: 543the server or peer is currently offline (i.e. assumed by *chronyd* to be 544unreachable, and no measurements from it will be attempted.) 545*burst_online*::: 546a burst command has been initiated for the server or peer and is being 547performed; after the burst is complete, the server or peer will be returned to 548the online state. 549*burst_offline*::: 550a burst command has been initiated for the server or peer and is being 551performed; after the burst is complete, the server or peer will be returned to 552the offline state. 553*unresolved*::: 554the name of the server or peer was not resolved to an address yet; this source is 555not visible in the *sources* and *sourcestats* reports. 556 557[[authdata]]*authdata* [*-a*]:: 558The *authdata* command displays information specific to authentication of NTP 559sources. If the *-a* option is specified, all sources are displayed, including 560those that do not have a known address yet. An example of the output is 561shown below. 562+ 563---- 564Name/IP address Mode KeyID Type KLen Last Atmp NAK Cook CLen 565========================================================================= 566foo.example.net NTS 1 15 256 135m 0 0 8 100 567bar.example.net SK 30 13 128 - 0 0 0 0 568baz.example.net - 0 0 0 - 0 0 0 0 569---- 570+ 571The columns are as follows: 572+ 573*Name/IP address*::: 574This column shows the name or the IP address of the source. 575*Mode*::: 576This column shows which mechanism authenticates NTP packets received from the 577source. _NTS_ means Network Time Security, _SK_ means a symmetric key, and _-_ 578means authentication is disabled. 579*KeyID*::: 580This column shows an identifier of the key used for authentication. With a 581symmetric key, it is the ID from the <<chrony.conf.adoc#keyfile,key file>>. 582With NTS, it is a number starting at zero and incremented by one with each 583successful key establishment using the NTS-KE protocol, i.e. it shows how many 584times the key establishment was performed with this source. 585*Type*::: 586This columns shows an identifier of the algorithm used for authentication. 587With a symmetric key, it is the hash function or cipher specified in the key 588file. With NTS, it is an authenticated encryption with associated data (AEAD) 589algorithm, which is negotiated in the NTS-KE protocol. The following values can 590be reported: 591* 1: MD5 592* 2: SHA1 593* 3: SHA256 594* 4: SHA384 595* 5: SHA512 596* 6: SHA3-224 597* 7: SHA3-256 598* 8: SHA3-384 599* 9: SHA3-512 600* 10: TIGER 601* 11: WHIRLPOOL 602* 13: AES128 603* 14: AES256 604* 15: AEAD-AES-SIV-CMAC-256 605*KLen*::: 606This column shows the length of the key in bits. 607*Last*::: 608This column shows how long ago the last successful key establishment was 609performed. It is in seconds, or letters _m_, _h_, _d_ or _y_ indicate minutes, 610hours, days, or years. 611*Atmp*::: 612This column shows the number of attempts to perform the key establishment since 613the last successful key establishment. A number larger than 1 indicates a 614problem with the network or server. 615*NAK*::: 616This column shows whether an NTS NAK was received since the last request. 617A NAK indicates that authentication failed on the server side due to 618*chronyd* using a cookie which is no longer valid and that it needs to perform 619the key establishment again in order to get new cookies. 620*Cook*::: 621This column shows the number of NTS cookies that *chronyd* currently has. If 622the key establishment was successful, a number smaller than 8 indicates a 623problem with the network or server. 624*CLen*::: 625This column shows the length in bytes of the NTS cookie which will be used in 626the next request. 627 628[[ntpdata]]*ntpdata* [_address_]:: 629The *ntpdata* command displays the last valid measurement and other 630NTP-specific information about the specified NTP source, or all NTP sources 631(with a known address) if no address was specified. An example of the output is 632shown below. 633+ 634---- 635Remote address : 203.0.113.15 (CB00710F) 636Remote port : 123 637Local address : 203.0.113.74 (CB00714A) 638Leap status : Normal 639Version : 4 640Mode : Server 641Stratum : 1 642Poll interval : 10 (1024 seconds) 643Precision : -24 (0.000000060 seconds) 644Root delay : 0.000015 seconds 645Root dispersion : 0.000015 seconds 646Reference ID : 47505300 (GPS) 647Reference time : Fri Nov 25 15:22:12 2016 648Offset : -0.000060878 seconds 649Peer delay : 0.000175634 seconds 650Peer dispersion : 0.000000681 seconds 651Response time : 0.000053050 seconds 652Jitter asymmetry: +0.00 653NTP tests : 111 111 1111 654Interleaved : No 655Authenticated : No 656TX timestamping : Kernel 657RX timestamping : Kernel 658Total TX : 24 659Total RX : 24 660Total valid RX : 24 661---- 662+ 663The fields are explained as follows: 664+ 665*Remote address*::: 666The IP address of the NTP server or peer, and the corresponding reference ID. 667*Remote port*::: 668The UDP port number to which the request was sent. The standard NTP port is 669123. 670*Local address*::: 671The local IP address which received the response, and the corresponding 672reference ID. 673*Leap status*::: 674*Version*::: 675*Mode*::: 676*Stratum*::: 677*Poll interval*::: 678*Precision*::: 679*Root delay*::: 680*Root dispersion*::: 681*Reference ID*::: 682*Reference time*::: 683The NTP values from the last valid response. 684*Offset*::: 685*Peer delay*::: 686*Peer dispersion*::: 687The measured values. 688*Response time*::: 689The time the server or peer spent in processing of the request and waiting 690before sending the response. 691*Jitter asymmetry*::: 692The estimated asymmetry of network jitter on the path to the source. The 693asymmetry can be between -0.5 and 0.5. A negative value means the delay of 694packets sent to the source is more variable than the delay of packets sent 695from the source back. 696*NTP tests*::: 697Results of RFC 5905 tests 1 through 3, 5 through 7, and tests for maximum 698delay, delay ratio, delay dev ratio, and synchronisation loop. 699*Interleaved*::: 700This shows if the response was in the interleaved mode. 701*Authenticated*::: 702This shows if the response was authenticated. 703*TX timestamping*::: 704The source of the local transmit timestamp. Valid values are _Daemon_, 705_Kernel_, and _Hardware_. 706*RX timestamping*::: 707The source of the local receive timestamp. 708*Total TX*::: 709The number of packets sent to the source. 710*Total RX*::: 711The number of all packets received from the source. 712*Total valid RX*::: 713The number of valid packets received from the source. 714 715[[add_peer]]*add peer* _name_ [_option_]...:: 716The *add peer* command allows a new NTP peer to be added whilst 717*chronyd* is running. 718+ 719Following the words *add peer*, the syntax of the following 720parameters and options is identical to that for the 721<<chrony.conf.adoc#peer,*peer*>> directive in the configuration file. 722+ 723An example of using this command is shown below. 724+ 725---- 726add peer foo.example.net minpoll 6 maxpoll 10 key 25 727---- 728 729[[add_pool]]*add pool* _name_ [_option_]...:: 730The *add pool* command allows a pool of NTP servers to be added whilst 731*chronyd* is running. 732+ 733Following the words *add pool*, the syntax of the following parameters and 734options is identical to that for the <<chrony.conf.adoc#pool,*pool*>> 735directive in the configuration file. 736+ 737An example of using this command is shown below: 738+ 739---- 740add pool foo.example.net maxsources 3 iburst 741---- 742 743[[add_server]]*add server* _name_ [_option_]...:: 744The *add server* command allows a new NTP server to be added whilst 745*chronyd* is running. 746+ 747Following the words *add server*, the syntax of the following parameters and 748options is identical to that for the <<chrony.conf.adoc#server,*server*>> 749directive in the configuration file. 750+ 751An example of using this command is shown below: 752+ 753---- 754add server foo.example.net minpoll 6 maxpoll 10 key 25 755---- 756 757[[delete]]*delete* _address_:: 758The *delete* command allows an NTP server or peer to be removed 759from the current set of sources. 760 761[[burst]] 762*burst* _good_/_max_ [_mask_/_masked-address_]:: 763*burst* _good_/_max_ [_masked-address_/_masked-bits_]:: 764*burst* _good_/_max_ [_address_]:: 765The *burst* command tells *chronyd* to make a set of measurements to each of 766its NTP sources over a short duration (rather than the usual periodic 767measurements that it makes). After such a burst, *chronyd* will revert to the 768previous state for each source. This might be either online, if the source was 769being periodically measured in the normal way, or offline, if the source had 770been indicated as being offline. (A source can be switched between the online 771and offline states with the <<online,*online*>> and <<offline,*offline*>> 772commands.) 773+ 774The _mask_ and _masked-address_ arguments are optional, in which case *chronyd* 775will initiate a burst for all of its currently defined sources. 776+ 777The arguments have the following meaning and format: 778+ 779_good_::: 780This defines the number of good measurements that *chronyd* will want to 781obtain from each source. A measurement is good if it passes certain tests, 782for example, the round trip time to the source must be acceptable. (This 783allows *chronyd* to reject measurements that are likely to be bogus.) 784_max_::: 785This defines the maximum number of measurements that *chronyd* will attempt 786to make, even if the required number of good measurements has not been 787obtained. 788_mask_::: 789This is an IP address with which the IP address of each of *chronyd*'s 790sources is to be masked. 791_masked-address_::: 792This is an IP address. If the masked IP address of a source matches this 793value then the burst command is applied to that source. 794_masked-bits_::: 795This can be used with _masked-address_ for CIDR notation, which is a shorter 796alternative to the form with mask. 797_address_::: 798This is an IP address or a hostname. The burst command is applied only to 799that source. 800{blank}:: 801+ 802If no _mask_ or _masked-address_ arguments are provided, every source will be 803matched. 804+ 805An example of the two-argument form of the command is: 806+ 807---- 808burst 2/10 809---- 810+ 811This will cause *chronyd* to attempt to get two good measurements from each 812source, stopping after two have been obtained, but in no event will it try more 813than ten probes to the source. 814+ 815Examples of the four-argument form of the command are: 816+ 817---- 818burst 2/10 255.255.0.0/1.2.0.0 819burst 2/10 2001:db8:789a::/48 820---- 821+ 822In the first case, the two out of ten sampling will only be applied to sources 823whose IPv4 addresses are of the form _1.2.x.y_, where _x_ and _y_ are 824arbitrary. In the second case, the sampling will be applied to sources whose 825IPv6 addresses have first 48 bits equal to _2001:db8:789a_. 826+ 827Example of the three-argument form of the command is: 828+ 829---- 830burst 2/10 foo.example.net 831---- 832 833[[maxdelay]]*maxdelay* _address_ _delay_:: 834This allows the *maxdelay* option for one of the sources to be modified, in the 835same way as specifying the *maxdelay* option for the 836<<chrony.conf.adoc#server,*server*>> directive in the configuration file. 837 838[[maxdelaydevratio]]*maxdelaydevratio* _address_ _ratio_:: 839This allows the *maxdelaydevratio* option for one of the sources to be 840modified, in the same way as specifying the *maxdelaydevratio* option for the 841<<chrony.conf.adoc#server,*server*>> directive in the configuration file. 842 843[[maxdelayratio]]*maxdelayratio* _address_ _ratio_:: 844This allows the *maxdelayratio* option for one of the sources to be modified, 845in the same way as specifying the *maxdelayratio* option for the 846<<chrony.conf.adoc#server,*server*>> directive in the configuration file. 847 848[[maxpoll]]*maxpoll* _address_ _maxpoll_:: 849The *maxpoll* command is used to modify the maximum polling interval for one of 850the current set of sources. It is equivalent to the *maxpoll* option in the 851<<chrony.conf.adoc#server,*server*>> directive in the configuration file. 852+ 853Note that the new maximum polling interval only takes effect after the next 854measurement has been made. 855 856[[minpoll]]*minpoll* _address_ _minpoll_:: 857The *minpoll* command is used to modify the minimum polling interval for one of 858the current set of sources. It is equivalent to the *minpoll* option in the 859<<chrony.conf.adoc#server,*server*>> directive in the configuration file. 860+ 861Note that the new minimum polling interval only takes effect after the next 862measurement has been made. 863 864[[minstratum]]*minstratum* _address_ _minstratum_:: 865The *minstratum* command is used to modify the minimum stratum for one of the 866current set of sources. It is equivalent to the *minstratum* option in the 867<<chrony.conf.adoc#server,*server*>> directive in the configuration file. 868 869[[offline]] 870*offline* [_address_]:: 871*offline* [_masked-address_/_masked-bits_]:: 872*offline* [_mask_/_masked-address_]:: 873The *offline* command is used to warn *chronyd* that the network connection to 874a particular host or hosts is about to be lost, e.g. on computers with 875intermittent connection to their time sources. 876+ 877Another case where *offline* could be used is where a computer serves time to a 878local group of computers, and has a permanent connection to true time servers 879outside the organisation. However, the external connection is heavily loaded at 880certain times of the day and the measurements obtained are less reliable at 881those times. In this case, it is probably most useful to determine the 882gain or loss rate during the quiet periods and let the whole network coast through 883the loaded periods. The *offline* and *online* commands can be used to achieve 884this. 885+ 886There are four forms of the *offline* command. The first form is a wildcard, 887meaning all sources (including sources that do not have a known address yet). 888The second form allows an IP address mask and a masked 889address to be specified. The third form uses CIDR notation. The fourth form 890uses an IP address or a hostname. These forms are illustrated below. 891+ 892---- 893offline 894offline 255.255.255.0/1.2.3.0 895offline 2001:db8:789a::/48 896offline foo.example.net 897---- 898+ 899The second form means that the *offline* command is to be applied to any source 900whose IPv4 address is in the _1.2.3_ subnet. (The host's address is logically 901and-ed with the mask, and if the result matches the _masked-address_ the host 902is processed.) The third form means that the command is to be applied to all 903sources whose IPv6 addresses have their first 48 bits equal to _2001:db8:789a_. The 904fourth form means that the command is to be applied only to that one source. 905+ 906The wildcard form of the address is equivalent to: 907+ 908---- 909offline 0.0.0.0/0.0.0.0 910offline ::/0 911---- 912 913[[online]] 914*online* [_address_]:: 915*online* [_masked-address_/_masked-bits_]:: 916*online* [_mask_/_masked-address_]:: 917The *online* command is opposite in function to the <<offline,*offline*>> 918command. It is used to advise *chronyd* that network connectivity to a 919particular source or sources has been restored. 920+ 921The syntax is identical to that of the <<offline,*offline*>> command. 922 923[[onoffline]] 924*onoffline*:: 925The *onoffline* command tells *chronyd* to switch all sources that have a known 926address to the online or 927offline status according to the current network configuration. A source is 928considered online if it is possible to send requests to it, i.e. a network 929route to the source is present. 930 931[[polltarget]]*polltarget* _address_ _polltarget_:: 932The *polltarget* command is used to modify the poll target for one of the 933current set of sources. It is equivalent to the *polltarget* option in the 934<<chrony.conf.adoc#server,*server*>> directive in the configuration file. 935 936[[refresh]]*refresh*:: 937The *refresh* command can be used to force *chronyd* to resolve the names of 938configured sources to IP addresses again, e.g. after suspending and resuming 939the machine in a different network. 940+ 941Sources that stop responding will be replaced with newly resolved addresses 942automatically after 8 polling intervals, but this command can still be useful 943to replace them immediately and not wait until they are marked as unreachable. 944 945[[reload]]*reload* *sources*:: 946The *reload sources* command causes *chronyd* to re-read all _*.sources_ files 947from the directories specified by the 948<<chrony.conf.adoc#sourcedir,*sourcedir*>> directive. 949 950[[sourcename]]*sourcename* _address_:: 951The *sourcename* command prints the original hostname or address that was 952specified for an NTP source in the configuration file, or the *add* command. 953This command is an alternative to the *-N* option, which can be useful in 954scripts. 955+ 956Note that different NTP sources can share the same name, e.g. servers from a 957pool. 958 959=== Manual time input 960 961[[manual]] 962*manual* *on*:: 963*manual* *off*:: 964*manual* *delete* _index_:: 965*manual* *list*:: 966*manual* *reset*:: 967The manual command enables and disables use of the <<settime,*settime*>> 968command, and is used to modify the behaviour of the manual clock driver. 969+ 970The *on* form of the command enables use of the *settime* command. 971+ 972The *off* form of the command disables use of the *settime* command. 973+ 974The *list* form of the command lists all the samples currently stored in 975*chronyd*. The output is illustrated below. 976+ 977---- 978210 n_samples = 1 979# Date Time(UTC) Slewed Original Residual 980==================================================== 981 0 27Jan99 22:09:20 0.00 0.97 0.00 982---- 983+ 984The columns are as as follows: 985+ 986. The sample index (used for the *manual delete* command). 987. The date and time of the sample. 988. The system clock error when the timestamp was entered, adjusted to allow 989 for changes made to the system clock since. 990. The system clock error when the timestamp was entered, as it originally was 991 (without allowing for changes to the system clock since). 992. The regression residual at this point, in seconds. This allows '`outliers`' 993 to be easily spotted, so that they can be deleted using the *manual delete* 994 command. 995{blank}:: 996+ 997The *delete* form of the command deletes a single sample. The parameter is the 998index of the sample, as shown in the first column of the output from *manual 999list*. Following deletion of the data point, the current error and drift rate 1000are re-estimated from the remaining data points and the system clock trimmed if 1001necessary. This option is intended to allow '`outliers`' to be discarded, i.e. 1002samples where the administrator realises they have entered a very poor 1003timestamp. 1004+ 1005The *reset* form of the command deletes all samples at once. The system clock 1006is left running as it was before the command was entered. 1007 1008[[settime]]*settime* _time_:: 1009The *settime* command allows the current time to be entered manually, if this 1010option has been configured into *chronyd*. (It can be configured either with 1011the <<chrony.conf.adoc#manual,*manual*>> directive in the configuration file, 1012or with the <<manual,*manual*>> command of *chronyc*.) 1013+ 1014It should be noted that the computer's sense of time will only be as accurate 1015as the reference you use for providing this input (e.g. your watch), as well as 1016how well you can time the press of the return key. 1017+ 1018Providing your computer's time zone is set up properly, you will be able to 1019enter a local time (rather than UTC). 1020+ 1021The response to a successful *settime* command indicates the amount that the 1022computer's clock was wrong. It should be apparent from this if you have entered 1023the time wrongly, e.g. with the wrong time zone. 1024+ 1025The rate of drift of the system clock is estimated by a regression process 1026using the entered measurement and all previous measurements entered during the 1027present run of *chronyd*. However, the entered measurement is used for 1028adjusting the current clock offset (rather than the estimated intercept from 1029the regression, which is ignored). Contrast what happens with the 1030<<manual,*manual delete*>> command, where the intercept is used to set the 1031current offset (since there is no measurement that has just been entered in 1032that case). 1033+ 1034The time is parsed by the public domain _getdate_ algorithm. Consequently, you 1035can only specify time to the nearest second. 1036+ 1037Examples of inputs that are valid are shown below: 1038+ 1039---- 1040settime 16:30 1041settime 16:30:05 1042settime Nov 21, 2015 16:30:05 1043---- 1044+ 1045For a full description of getdate, see the getdate documentation 1046(bundled, for example, with the source for GNU tar). 1047 1048=== NTP access 1049 1050[[accheck]]*accheck* _address_:: 1051This command allows you to check whether client NTP access is allowed from a 1052particular host. 1053+ 1054Examples of use, showing a named host and a numeric IP address, are as follows: 1055+ 1056---- 1057accheck foo.example.net 1058accheck 1.2.3.4 1059accheck 2001:db8::1 1060---- 1061+ 1062This command can be used to examine the effect of a series of *allow*, *allow 1063all*, *deny*, and *deny all* commands specified either via *chronyc*, or in 1064*chronyd*'s configuration file. 1065 1066[[clients]]*clients* [*-p* _packets_] [*-k*] [*-r*]:: 1067This command shows a list of clients that have accessed the server, through 1068the NTP, command, or NTS-KE port. It does not include accesses over the Unix 1069domain command socket. 1070+ 1071The *-p* option specifies the minimum number of received NTP or command 1072packets, or accepted NTS-KE connections, needed to include a client in the 1073list. The default value is 0, i.e. all clients are reported. With the *-k* 1074option the last four columns will show the NTS-KE accesses instead of command 1075accesses. If the *-r* option is specified, *chronyd* will reset the counters of 1076received and dropped packets or connections after reporting the current values. 1077+ 1078An example of the output is: 1079+ 1080---- 1081Hostname NTP Drop Int IntL Last Cmd Drop Int Last 1082=============================================================================== 1083localhost 2 0 2 - 133 15 0 -1 7 1084foo.example.net 12 0 6 - 23 0 0 - - 1085---- 1086+ 1087Each row shows the data for a single host. Only hosts that have passed the host 1088access checks (set with the <<allow,*allow*>>, <<deny,*deny*>>, 1089<<cmdallow,*cmdallow*>> and <<cmddeny,*cmddeny*>> commands or configuration 1090file directives) are logged. The intervals are displayed as a power of 2 in 1091seconds. 1092+ 1093The columns are as follows: 1094+ 1095. The hostname of the client. 1096. The number of NTP packets received from the client. 1097. The number of NTP packets dropped to limit the response rate. 1098. The average interval between NTP packets. 1099. The average interval between NTP packets after limiting the response rate. 1100. Time since the last NTP packet was received 1101. The number of command packets or NTS-KE connections received/accepted from 1102 the client. 1103. The number of command packets or NTS-KE connections dropped to limit the 1104 response rate. 1105. The average interval between command packets or NTS-KE connections. 1106. Time since the last command packet or NTS-KE connection was 1107 received/accepted. 1108 1109[[serverstats]]*serverstats*:: 1110The *serverstats* command displays NTP and command server statistics. 1111+ 1112An example of the output is shown below. 1113+ 1114---- 1115NTP packets received : 1598 1116NTP packets dropped : 8 1117Command packets received : 19 1118Command packets dropped : 0 1119Client log records dropped : 0 1120NTS-KE connections accepted: 3 1121NTS-KE connections dropped : 0 1122Authenticated NTP packets : 189 1123Interleaved NTP packets : 43 1124NTP timestamps held : 44 1125NTP timestamp span : 120 1126---- 1127+ 1128The fields have the following meaning: 1129+ 1130*NTP packets received*::: 1131The number of valid NTP requests received by the server. 1132*NTP packets dropped*::: 1133The number of NTP requests dropped by the server due to rate limiting 1134(configured by the <<chrony.conf.adoc#ratelimit,*ratelimit*>> directive). 1135*Command packets received*::: 1136The number of command requests received by the server. 1137*Command packets dropped*::: 1138The number of command requests dropped by the server due to rate limiting 1139(configured by the <<chrony.conf.adoc#cmdratelimit,*cmdratelimit*>> directive). 1140*Client log records dropped*::: 1141The number of client log records dropped by the server to limit the memory use 1142(configured by the <<chrony.conf.adoc#clientloglimit,*clientloglimit*>> 1143directive). 1144*NTS-KE connections accepted*::: 1145The number of NTS-KE connections accepted by the server. 1146*NTS-KE connections dropped*::: 1147The number of NTS-KE connections dropped by the server due to rate limiting 1148(configured by the <<chrony.conf.adoc#ntsratelimit,*ntsratelimit*>> directive). 1149*Authenticated NTP packets*::: 1150The number of received NTP requests that were authenticated (with a symmetric 1151key or NTS). 1152*Interleaved NTP packets*::: 1153The number of received NTP requests that were detected to be in the interleaved 1154mode. 1155*NTP timestamps held*::: 1156The number of pairs of receive and transmit timestamps that the server is 1157currently holding in memory for clients using the interleaved mode. 1158*NTP timestamp span*::: 1159The interval (in seconds) covered by the currently held NTP timestamps. 1160{blank}:: 1161+ 1162Note that the numbers reported by this overflow to zero after 4294967295 1163(32-bit values). 1164 1165[[allow]]*allow* [*all*] [_subnet_]:: 1166The effect of the allow command is identical to the 1167<<chrony.conf.adoc#allow,*allow*>> directive in the configuration file. 1168+ 1169The syntax is illustrated in the following examples: 1170+ 1171---- 1172allow 1.2.3.4 1173allow all 3.4.5.0/24 1174allow 2001:db8:789a::/48 1175allow 0/0 1176allow ::/0 1177allow 1178allow all 1179---- 1180 1181[[deny]]*deny* [*all*] [_subnet_]:: 1182The effect of the allow command is identical to the 1183<<chrony.conf.adoc#deny,*deny*>> directive in the configuration file. 1184+ 1185The syntax is illustrated in the following examples: 1186+ 1187---- 1188deny 1.2.3.4 1189deny all 3.4.5.0/24 1190deny 2001:db8:789a::/48 1191deny 0/0 1192deny ::/0 1193deny 1194deny all 1195---- 1196 1197[[local]] 1198*local* [_option_]...:: 1199*local* *off*:: 1200The *local* command allows *chronyd* to be told that it is to appear as a 1201reference source, even if it is not itself properly synchronised to an external 1202source. (This can be used on isolated networks, to allow one computer to be a 1203master time server with the other computers slaving to it.) 1204+ 1205The first form enables the local reference mode on the host. The syntax is 1206identical to the <<chrony.conf.adoc#local,*local*>> directive in the 1207configuration file. 1208+ 1209The second form disables the local reference mode. 1210 1211[[smoothing]]*smoothing*:: 1212The *smoothing* command displays the current state of the NTP server time 1213smoothing, which can be enabled with the 1214<<chrony.conf.adoc#smoothtime,*smoothtime*>> directive. An example of the 1215output is shown below. 1216+ 1217---- 1218Active : Yes 1219Offset : +1.000268817 seconds 1220Frequency : -0.142859 ppm 1221Wander : -0.010000 ppm per second 1222Last update : 17.8 seconds ago 1223Remaining time : 19988.4 seconds 1224---- 1225+ 1226The fields are explained as follows: 1227+ 1228*Active*::: 1229This shows if the server time smoothing is currently active. Possible values 1230are _Yes_ and _No_. If the *leaponly* option is included in the *smoothtime* 1231directive, _(leap second only)_ will be shown on the line. 1232*Offset*::: 1233This is the current offset applied to the time sent to NTP clients. Positive 1234value means the clients are getting time that's ahead of true time. 1235*Frequency*::: 1236The current frequency offset of the served time. Negative value means the 1237time observed by clients is running slower than true time. 1238*Wander*::: 1239The current frequency wander of the served time. Negative value means the 1240time observed by clients is slowing down. 1241*Last update*::: 1242This field shows how long ago the time smoothing process was updated, e.g. 1243*chronyd* accumulated a new measurement. 1244*Remaining time*::: 1245The time it would take for the smoothing process to get to zero offset and 1246frequency if there were no more updates. 1247 1248[[smoothtime]] 1249*smoothtime* *activate*:: 1250*smoothtime* *reset*:: 1251The *smoothtime* command can be used to activate or reset the server time 1252smoothing process if it is configured with the 1253<<chrony.conf.adoc#smoothtime,*smoothtime*>> directive. 1254 1255=== Monitoring access 1256 1257[[cmdaccheck]]*cmdaccheck* _address_:: 1258This command is similar to the <<accheck,*accheck*>> command, except that it is 1259used to check whether monitoring access is permitted from a named host. 1260+ 1261Examples of use are as follows: 1262+ 1263---- 1264cmdaccheck foo.example.net 1265cmdaccheck 1.2.3.4 1266cmdaccheck 2001:db8::1 1267---- 1268 1269[[cmdallow]]*cmdallow* [*all*] [_subnet_]:: 1270This is similar to the <<allow,*allow*>> command, except that it is used to 1271allow particular hosts or subnets to use *chronyc* to monitor with *chronyd* on 1272the current host. 1273 1274[[cmddeny]]*cmddeny* [*all*] [_subnet_]:: 1275This is similar to the <<deny,*deny*>> command, except that it is used to allow 1276particular hosts or subnets to use *chronyc* to monitor *chronyd* on the 1277current host. 1278 1279=== Real-time clock (RTC) 1280 1281[[rtcdata]]*rtcdata*:: 1282The *rtcdata* command displays the current RTC parameters. 1283+ 1284An example output is shown below. 1285+ 1286---- 1287RTC ref time (GMT) : Sat May 30 07:25:56 2015 1288Number of samples : 10 1289Number of runs : 5 1290Sample span period : 549 1291RTC is fast by : -1.632736 seconds 1292RTC gains time at : -107.623 ppm 1293---- 1294+ 1295The fields have the following meaning: 1296+ 1297*RTC ref time (GMT)*::: 1298This is the RTC reading the last time its error was measured. 1299*Number of samples*::: 1300This is the number of previous measurements being used to determine the RTC 1301gain or loss rate. 1302*Number of runs*::: 1303This is the number of runs of residuals of the same sign following the 1304regression fit for (RTC error) versus (RTC time). A value which is small 1305indicates that the measurements are not well approximated by a linear model, 1306and that the algorithm will tend to delete the older measurements to improve 1307the fit. 1308*Sample span period*::: 1309This is the period that the measurements span (from the oldest to the 1310newest). Without a unit the value is in seconds; suffixes _m_ for minutes, 1311_h_ for hours, _d_ for days or _y_ for years can be used. 1312*RTC is fast by*::: 1313This is the estimate of how many seconds fast the RTC when it thought 1314the time was at the reference time (above). If this value is large, you 1315might (or might not) want to use the <<trimrtc,*trimrtc*>> command to bring the 1316RTC into line with the system clock. (Note, a large error will not affect 1317*chronyd*'s operation, unless it becomes so big as to start causing rounding 1318errors.) 1319*RTC gains time at*::: 1320This is the amount of time gained (positive) or lost (negative) by the real 1321time clock for each second that it ticks. It is measured in parts per 1322million. So if the value shown was +1, suppose the RTC was exactly right when 1323it crosses a particular second boundary. Then it would be 1 microsecond fast 1324when it crosses its next second boundary. 1325 1326[[trimrtc]]*trimrtc*:: 1327The *trimrtc* command is used to correct the system's real-time clock (RTC) to 1328the main system clock. It has no effect if the error between the two clocks is 1329currently estimated at less than a second. 1330+ 1331The command takes no arguments. It performs the following steps (if the RTC is 1332more than 1 second away from the system clock): 1333+ 1334. Remember the currently estimated gain or loss rate of the RTC and flush the 1335 previous measurements. 1336. Step the real-time clock to bring it within a second of the system clock. 1337. Make several measurements to accurately determine the new offset between 1338 the RTC and the system clock (i.e. the remaining fraction of a second 1339 error). 1340. Save the RTC parameters to the RTC file (specified with the 1341 <<chrony.conf.adoc#rtcfile,*rtcfile*>> directive in the configuration file). 1342{blank}:: 1343+ 1344The last step is done as a precaution against the computer suffering a power 1345failure before either the daemon exits or the <<writertc,*writertc*>> command 1346is issued. 1347+ 1348*chronyd* will still work perfectly well both whilst operating and across 1349machine reboots even if the *trimrtc* command is never used (and the RTC is 1350allowed to drift away from true time). The *trimrtc* command is provided as a 1351method by which it can be corrected, in a manner compatible with *chronyd* 1352using it to maintain accurate time across machine reboots. 1353+ 1354The *trimrtc* command can be executed automatically by *chronyd* with the 1355<<chrony.conf.adoc#rtcautotrim,*rtcautotrim*>> directive in the configuration 1356file. 1357 1358[[writertc]]*writertc*:: 1359The *writertc* command writes the currently estimated error and gain or loss rate 1360parameters for the RTC to the RTC file (specified with the 1361<<chrony.conf.adoc#rtcfile,*rtcfile*>> directive). This information is also 1362written automatically when *chronyd* is killed (by the SIGHUP, SIGINT, SIGQUIT 1363or SIGTERM signals) or when the <<trimrtc,*trimrtc*>> command is issued. 1364 1365=== Other daemon commands 1366 1367[[cyclelogs]]*cyclelogs*:: 1368The *cyclelogs* command causes all of *chronyd*'s open log files to be closed 1369and re-opened. This allows them to be renamed so that they can be periodically 1370purged. An example of how to do this is shown below. 1371+ 1372---- 1373# mv /var/log/chrony/measurements.log /var/log/chrony/measurements1.log 1374# chronyc cyclelogs 1375# rm /var/log/chrony/measurements1.log 1376---- 1377 1378[[dump]]*dump*:: 1379The *dump* command causes *chronyd* to write its current history of 1380measurements for each of its sources to dump files in the directory specified 1381in the configuration file by the <<chrony.conf.adoc#dumpdir,*dumpdir*>> 1382directive and also write server NTS keys and client NTS cookies to the 1383directory specified by the <<chrony.conf.adoc#ntsdumpdir1,*ntsdumpdir*>> 1384directive. Note that *chronyd* does this automatically when it exits. This 1385command is mainly useful for inspection whilst *chronyd* is running. 1386 1387[[rekey]]*rekey*:: 1388The *rekey* command causes *chronyd* to re-read the key file specified in the 1389configuration file by the <<chrony.conf.adoc#keyfile,*keyfile*>> directive. It 1390also re-reads the server NTS keys if 1391<<chrony.conf.adoc#ntsdumpdir2,*ntsdumpdir*>> is specified and 1392<<chrony.conf.adoc#ntsrotate,automatic rotation>> is disabled in the 1393configuration file. 1394 1395[[reset]]*reset* *sources*:: 1396The *reset sources* command causes *chronyd* to drop all measurements and 1397switch to the unsynchronised state. This command can help *chronyd* with 1398recovery when the measurements are known to be no longer valid or accurate, 1399e.g. due to moving the computer to a different network, or resuming the 1400computer from a low-power state (which resets the system clock). *chronyd* will 1401drop the measurements automatically when it detects the clock has made an 1402unexpected jump, but the detection is not completely reliable. 1403 1404[[shutdown]]*shutdown*:: 1405The *shutdown* command causes *chronyd* to exit. This is equivalent to sending 1406the process the SIGTERM signal. 1407 1408=== Client commands 1409 1410[[dns]]*dns* _option_:: 1411The *dns* command configures how hostnames and IP addresses are resolved in 1412*chronyc*. IP addresses can be resolved to hostnames when printing results of 1413<<sources,*sources*>>, <<sourcestats,*sourcestats*>>, <<tracking,*tracking*>> 1414and <<clients,*clients*>> commands. Hostnames are resolved in commands that 1415take an address as argument. 1416+ 1417There are five options: 1418+ 1419*dns -n*::: 1420Disables resolving IP addresses to hostnames. Raw IP addresses will be 1421displayed. 1422*dns +n*::: 1423Enables resolving IP addresses to hostnames. This is the default unless 1424*chronyc* was started with *-n* option. 1425*dns -4*::: 1426Resolves hostnames only to IPv4 addresses. 1427*dns -6*::: 1428Resolves hostnames only to IPv6 addresses. 1429*dns -46*::: 1430Resolves hostnames to both address families. This is the default behaviour 1431unless *chronyc* was started with the *-4* or *-6* option. 1432 1433[[timeout]]*timeout* _timeout_:: 1434The *timeout* command sets the initial timeout for *chronyc* requests in 1435milliseconds. If no response is received from *chronyd*, the timeout is doubled 1436and the request is resent. The maximum number of retries is configured with the 1437<<retries,*retries*>> command. 1438+ 1439By default, the timeout is 1000 milliseconds. 1440 1441[[retries]]*retries* _retries_:: 1442The *retries* command sets the maximum number of retries for *chronyc* requests 1443before giving up. The response timeout is controlled by the 1444<<timeout,*timeout*>> command. 1445+ 1446The default is 2. 1447 1448[[keygen]]*keygen* [_id_ [_type_ [_bits_]]]:: 1449The *keygen* command generates a key that can be added to the 1450key file (specified with the <<chrony.conf.adoc#keyfile,*keyfile*>> directive) 1451to allow NTP authentication between server and client, or peers. The key is 1452generated from the _/dev/urandom_ device and it is printed to standard output. 1453+ 1454The command has three optional arguments. The first argument is the key number 1455(by default 1), which will be specified with the *key* option of the *server* 1456or *peer* directives in the configuration file. The second argument is the name 1457of the hash function or cipher (by default SHA1, or MD5 if SHA1 is not 1458available). The third argument is the length of the key in bits if a hash 1459function was selected, between 80 and 4096 bits (by default 160 bits). 1460+ 1461An example is: 1462+ 1463---- 1464keygen 73 SHA1 256 1465---- 1466+ 1467which generates a 256-bit SHA1 key with number 73. The printed line should 1468then be securely transferred and added to the key files on both server and 1469client, or peers. A different key should be generated for each client or peer. 1470+ 1471An example using the AES128 cipher is: 1472+ 1473---- 1474keygen 151 AES128 1475---- 1476 1477[[exit]]*exit*:: 1478[[quit]]*quit*:: 1479The *exit* and *quit* commands exit from *chronyc* and return the user to the shell. 1480 1481[[help]]*help*:: 1482The *help* command displays a summary of the commands and their arguments. 1483 1484== SEE ALSO 1485 1486<<chrony.conf.adoc#,*chrony.conf(5)*>>, <<chronyd.adoc#,*chronyd(8)*>> 1487 1488== BUGS 1489 1490For instructions on how to report bugs, please visit 1491https://chrony.tuxfamily.org/. 1492 1493== AUTHORS 1494 1495chrony was written by Richard Curnow, Miroslav Lichvar, and others. 1496