1CHRONYC(1)                        User manual                       CHRONYC(1)
2
3
4

NAME

6       chronyc - command-line interface for chrony daemon
7

SYNOPSIS

9       chronyc [OPTION]... [COMMAND]...
10

DESCRIPTION

12       chronyc is a command-line interface program which can be used to
13       monitor chronyd’s performance and to change various operating
14       parameters whilst it is running.
15
16       If no commands are specified on the command line, chronyc will expect
17       input from the user. The prompt chronyc> will be displayed when it is
18       being run from a terminal. If chronyc’s input or output are redirected
19       from or to a file, the prompt is not shown.
20
21       There are two ways chronyc can access chronyd. One is the Internet
22       Protocol (IPv4 or IPv6) and the other is a Unix domain socket, which is
23       accessible locally by the root or chrony user. By default, chronyc
24       first tries to connect to the Unix domain socket. The compiled-in
25       default path is /var/run/chrony/chronyd.sock. If that fails (e.g.
26       because chronyc is running under a non-root user), it will try to
27       connect to 127.0.0.1 and then ::1.
28
29       Only the following monitoring commands, which do not affect the
30       behaviour of chronyd, are allowed from the network: activity, manual
31       list, rtcdata, smoothing, sources, sourcestats, tracking, waitsync. The
32       set of hosts from which chronyd will accept these commands can be
33       configured with the cmdallow directive in the chronyd’s configuration
34       file or the cmdallow command in chronyc. By default, the commands are
35       accepted only from localhost (127.0.0.1 or ::1).
36
37       All other commands are allowed only through the Unix domain socket.
38       When sent over the network, chronyd will respond with a ‘Not
39       authorised’ error, even if it is from localhost. In chrony versions
40       before 2.2 they were allowed from the network if they were
41       authenticated with a password, but that is no longer supported.
42
43       Having full access to chronyd via chronyc is more or less equivalent to
44       being able to modify the chronyd’s configuration file and restart it.
45

OPTIONS

47       -4
48           With this option hostnames will be resolved only to IPv4 addresses.
49
50       -6
51           With this option hostnames will be resolved only to IPv6 addresses.
52
53       -n
54           This option disables resolving of IP addresses to hostnames, e.g.
55           to avoid slow DNS lookups. Long addresses will not be truncated to
56           fit into the column.
57
58       -c
59           This option enables printing of reports in a comma-separated values
60           (CSV) format. IP addresses will not be resolved to hostnames, time
61           will be printed as number of seconds since the epoch and values in
62           seconds will not be converted to other units.
63
64       -d
65           This option enables printing of debugging messages if chronyc was
66           compiled with debugging support.
67
68       -m
69           Normally, all arguments on the command line are interpreted as one
70           command. With this option multiple commands can be specified. Each
71           argument will be interpreted as a whole command.
72
73       -h host
74           This option allows the user to specify which host (or
75           comma-separated list of addresses) running the chronyd program is
76           to be contacted. This allows for remote monitoring, without having
77           to connect over SSH to the other host first.
78
79           The default is to contact chronyd running on the same host where
80           chronyc is being run.
81
82       -p port
83           This option allows the user to specify the UDP port number which
84           the target chronyd is using for its monitoring connections. This
85           defaults to 323; there would rarely be a need to change this.
86
87       -f file
88           This option is ignored and is provided only for compatibility.
89
90       -a
91           This option is ignored and is provided only for compatibility.
92
93       -v
94           With this option chronyc displays its version number on the
95           terminal and exits.
96

COMMANDS

98       This section describes each of the commands available within the
99       chronyc program.
100
101   System clock
102       tracking
103           The tracking command displays parameters about the system’s clock
104           performance. An example of the output is shown below.
105
106               Reference ID    : CB00710F (foo.example.net)
107               Stratum         : 3
108               Ref time (UTC)  : Fri Jan 27 09:49:17 2017
109               System time     : 0.000006523 seconds slow of NTP time
110               Last offset     : -0.000006747 seconds
111               RMS offset      : 0.000035822 seconds
112               Frequency       : 3.225 ppm slow
113               Residual freq   : -0.000 ppm
114               Skew            : 0.129 ppm
115               Root delay      : 0.013639022 seconds
116               Root dispersion : 0.001100737 seconds
117               Update interval : 64.2 seconds
118               Leap status     : Normal
119
120           The fields are explained as follows:
121
122           Reference ID
123               This is the reference ID and name (or IP address) of the server
124               to which the computer is currently synchronised. For IPv4
125               addresses, the reference ID is equal to the address and for
126               IPv6 addresses it is the first 32 bits of the MD5 sum of the
127               address.
128
129               If the reference ID is 7F7F0101 and there is no name or IP
130               address, it means the computer is not synchronised to any
131               external source and that you have the local mode operating (via
132               the local command in chronyc, or the local directive in the
133               configuration file).
134
135               The reference ID is printed as a hexadecimal number. Note that
136               in older versions it used to be printed in quad-dotted notation
137               and could be confused with an IPv4 address.
138
139           Stratum
140               The stratum indicates how many hops away from a computer with
141               an attached reference clock we are. Such a computer is a
142               stratum-1 computer, so the computer in the example is two hops
143               away (i.e. foo.example.net is a stratum-2 and is synchronised
144               from a stratum-1).
145
146           Ref time
147               This is the time (UTC) at which the last measurement from the
148               reference source was processed.
149
150           System time
151               In normal operation, chronyd by default never steps the system
152               clock, because any jump in the time can have adverse
153               consequences for certain application programs. Instead, any
154               error in the system clock is corrected by slightly speeding up
155               or slowing down the system clock until the error has been
156               removed, and then returning to the system clock’s normal speed.
157               A consequence of this is that there will be a period when the
158               system clock (as read by other programs) will be different from
159               chronyd’s estimate of the current true time (which it reports
160               to NTP clients when it is operating in server mode). The value
161               reported on this line is the difference due to this effect.
162
163           Last offset
164               This is the estimated local offset on the last clock update.
165
166           RMS offset
167               This is a long-term average of the offset value.
168
169           Frequency
170               The ‘frequency’ is the rate by which the system’s clock would
171               be wrong if chronyd was not correcting it. It is expressed in
172               ppm (parts per million). For example, a value of 1 ppm would
173               mean that when the system’s clock thinks it has advanced 1
174               second, it has actually advanced by 1.000001 seconds relative
175               to true time.
176
177           Residual freq
178               This shows the ‘residual frequency’ for the currently selected
179               reference source. This reflects any difference between what the
180               measurements from the reference source indicate the frequency
181               should be and the frequency currently being used.
182
183               The reason this is not always zero is that a smoothing
184               procedure is applied to the frequency. Each time a measurement
185               from the reference source is obtained and a new residual
186               frequency computed, the estimated accuracy of this residual is
187               compared with the estimated accuracy (see ‘skew’ next) of the
188               existing frequency value. A weighted average is computed for
189               the new frequency, with weights depending on these accuracies.
190               If the measurements from the reference source follow a
191               consistent trend, the residual will be driven to zero over
192               time.
193
194           Skew
195               This is the estimated error bound on the frequency.
196
197           Root delay
198               This is the total of the network path delays to the stratum-1
199               computer from which the computer is ultimately synchronised.
200
201           Root dispersion
202               This is the total dispersion accumulated through all the
203               computers back to the stratum-1 computer from which the
204               computer is ultimately synchronised. Dispersion is due to
205               system clock resolution, statistical measurement variations,
206               etc.
207
208               An absolute bound on the computer’s clock accuracy (assuming
209               the stratum-1 computer is correct) is given by:
210
211                   clock_error <= |system_time_offset| + root_dispersion + (0.5 * root_delay)
212
213           Update interval
214               This is the interval between the last two clock updates.
215
216           Leap status
217               This is the leap status, which can be Normal, Insert second,
218               Delete second or Not synchronised.
219
220       makestep, makestep threshold limit
221           Normally chronyd will cause the system to gradually correct any
222           time offset, by slowing down or speeding up the clock as required.
223           In certain situations, the system clock might be so far adrift that
224           this slewing process would take a very long time to correct the
225           system clock.
226
227           The makestep command can be used in this situation. There are two
228           forms of the command. The first form has no parameters. It tells
229           chronyd to cancel any remaining correction that was being slewed
230           and jump the system clock by the equivalent amount, making it
231           correct immediately.
232
233           The second form configures the automatic stepping, similarly to the
234           makestep directive. It has two parameters, stepping threshold (in
235           seconds) and number of future clock updates for which the threshold
236           will be active. This can be used with the burst command to quickly
237           make a new measurement and correct the clock by stepping if needed,
238           without waiting for chronyd to complete the measurement and update
239           the clock.
240
241               makestep 0.1 1
242               burst 1/2
243
244           BE WARNED: Certain software will be seriously affected by such
245           jumps in the system time. (That is the reason why chronyd uses
246           slewing normally.)
247
248       maxupdateskew skew-in-ppm
249           This command has the same effect as the maxupdateskew directive in
250           the configuration file.
251
252       waitsync [max-tries [max-correction [max-skew [interval]]]]
253           The waitsync command waits for chronyd to synchronise.
254
255           Up to four optional arguments can be specified. The first is the
256           maximum number of tries before giving up and returning a non-zero
257           error code. When 0 is specified, or there are no arguments, the
258           number of tries will not be limited.
259
260           The second and third arguments are the maximum allowed remaining
261           correction of the system clock and the maximum allowed skew (in
262           ppm) as reported by the tracking command in the System time and
263           Skew fields. If not specified or zero, the value will not be
264           checked.
265
266           The fourth argument is the interval specified in seconds in which
267           the check is repeated. The interval is 10 seconds by default.
268
269           An example is:
270
271               waitsync 60 0.01
272
273           which will wait up to about 10 minutes (60 times 10 seconds) for
274           chronyd to synchronise to a source and the remaining correction to
275           be less than 10 milliseconds.
276
277   Time sources
278       sources [-v]
279           This command displays information about the current time sources
280           that chronyd is accessing.
281
282           The optional argument -v can be specified, meaning verbose. In this
283           case, extra caption lines are shown as a reminder of the meanings
284           of the columns.
285
286               210 Number of sources = 3
287               MS Name/IP address         Stratum Poll Reach LastRx Last sample
288               ===============================================================================
289               #* GPS0                          0   4   377    11   -479ns[ -621ns] +/-  134ns
290               ^? foo.example.net               2   6   377    23   -923us[ -924us] +/-   43ms
291               ^+ bar.example.net               1   6   377    21  -2629us[-2619us] +/-   86ms
292
293           The columns are as follows:
294
295           M
296               This indicates the mode of the source. ^ means a server, =
297               means a peer and # indicates a locally connected reference
298               clock.
299
300           S
301               This column indicates the state of the source.
302
303               ·   * indicates the source to which chronyd is currently
304                   synchronised.
305
306               ·   + indicates acceptable sources which are combined with the
307                   selected source.
308
309               ·   - indicates acceptable sources which are excluded by the
310                   combining algorithm.
311
312               ·   ? indicates sources to which connectivity has been lost or
313                   whose packets do not pass all tests. It is also shown at
314                   start-up, until at least 3 samples have been gathered from
315                   it.
316
317               ·   x indicates a clock which chronyd thinks is a falseticker
318                   (i.e. its time is inconsistent with a majority of other
319                   sources).
320
321               ·   ~ indicates a source whose time appears to have too much
322                   variability.
323
324           Name/IP address
325               This shows the name or the IP address of the source, or
326               reference ID for reference clocks.
327
328           Stratum
329               This shows the stratum of the source, as reported in its most
330               recently received sample. Stratum 1 indicates a computer with a
331               locally attached reference clock. A computer that is
332               synchronised to a stratum 1 computer is at stratum 2. A
333               computer that is synchronised to a stratum 2 computer is at
334               stratum 3, and so on.
335
336           Poll
337               This shows the rate at which the source is being polled, as a
338               base-2 logarithm of the interval in seconds. Thus, a value of 6
339               would indicate that a measurement is being made every 64
340               seconds. chronyd automatically varies the polling rate in
341               response to prevailing conditions.
342
343           Reach
344               This shows the source’s reachability register printed as an
345               octal number. The register has 8 bits and is updated on every
346               received or missed packet from the source. A value of 377
347               indicates that a valid reply was received for all from the last
348               eight transmissions.
349
350           LastRx
351               This column shows how long ago the last good sample (which is
352               shown in the next column) was received from the source.
353               Measurements that failed some tests are ignored. This is
354               normally in seconds. The letters m, h, d or y indicate minutes,
355               hours, days, or years.
356
357           Last sample
358               This column shows the offset between the local clock and the
359               source at the last measurement. The number in the square
360               brackets shows the actual measured offset. This can be suffixed
361               by ns (indicating nanoseconds), us (indicating microseconds),
362               ms (indicating milliseconds), or s (indicating seconds). The
363               number to the left of the square brackets shows the original
364               measurement, adjusted to allow for any slews applied to the
365               local clock since. The number following the +/- indicator shows
366               the margin of error in the measurement. Positive offsets
367               indicate that the local clock is ahead of the source.
368
369       sourcestats [-v]
370           The sourcestats command displays information about the drift rate
371           and offset estimation process for each of the sources currently
372           being examined by chronyd.
373
374           The optional argument -v can be specified, meaning verbose. In this
375           case, extra caption lines are shown as a reminder of the meanings
376           of the columns.
377
378           An example report is:
379
380               210 Number of sources = 1
381               Name/IP Address            NP  NR  Span  Frequency  Freq Skew  Offset  Std Dev
382               ===============================================================================
383               foo.example.net            11   5   46m     -0.001      0.045      1us    25us
384
385           The columns are as follows:
386
387           Name/IP Address
388               This is the name or IP address of the NTP server (or peer) or
389               reference ID of the reference clock to which the rest of the
390               line relates.
391
392           NP
393               This is the number of sample points currently being retained
394               for the server. The drift rate and current offset are estimated
395               by performing a linear regression through these points.
396
397           NR
398               This is the number of runs of residuals having the same sign
399               following the last regression. If this number starts to become
400               too small relative to the number of samples, it indicates that
401               a straight line is no longer a good fit to the data. If the
402               number of runs is too low, chronyd discards older samples and
403               re-runs the regression until the number of runs becomes
404               acceptable.
405
406           Span
407               This is the interval between the oldest and newest samples. If
408               no unit is shown the value is in seconds. In the example, the
409               interval is 46 minutes.
410
411           Frequency
412               This is the estimated residual frequency for the server, in
413               parts per million. In this case, the computer’s clock is
414               estimated to be running 1 part in 10^9 slow relative to the
415               server.
416
417           Freq Skew
418               This is the estimated error bounds on Freq (again in parts per
419               million).
420
421           Offset
422               This is the estimated offset of the source.
423
424           Std Dev
425               This is the estimated sample standard deviation.
426
427       reselect
428           To avoid excessive switching between sources, chronyd can stay
429           synchronised to a source even when it is not currently the best one
430           among the available sources.
431
432           The reselect command can be used to force chronyd to reselect the
433           best synchronisation source.
434
435       reselectdist distance
436           The reselectdist command sets the reselection distance. It is
437           equivalent to the reselectdist directive in the configuration file.
438
439   NTP sources
440       activity
441           This command reports the number of servers and peers that are
442           online and offline. If the auto_offline option is used in
443           specifying some of the servers or peers, the activity command can
444           be useful for detecting when all of them have entered the offline
445           state after the network link has been disconnected.
446
447           The report shows the number of servers and peers in 5 states:
448
449           online
450               the server or peer is currently online (i.e. assumed by chronyd
451               to be reachable)
452
453           offline
454               the server or peer is currently offline (i.e. assumed by
455               chronyd to be unreachable, and no measurements from it will be
456               attempted.)
457
458           burst_online
459               a burst command has been initiated for the server or peer and
460               is being performed; after the burst is complete, the server or
461               peer will be returned to the online state.
462
463           burst_offline
464               a burst command has been initiated for the server or peer and
465               is being performed; after the burst is complete, the server or
466               peer will be returned to the offline state.
467
468           unresolved
469               the name of the server or peer was not resolved to an address
470               yet; this source is not visible in the sources and sourcestats
471               reports.
472
473       ntpdata [address]
474           The ntpdata command displays the last valid measurement and other
475           NTP-specific information about the specified NTP source, or all NTP
476           sources if no address was specified. An example of the output is
477           shown below.
478
479               Remote address  : 203.0.113.15 (CB00710F)
480               Remote port     : 123
481               Local address   : 203.0.113.74 (CB00714A)
482               Leap status     : Normal
483               Version         : 4
484               Mode            : Server
485               Stratum         : 1
486               Poll interval   : 10 (1024 seconds)
487               Precision       : -24 (0.000000060 seconds)
488               Root delay      : 0.000015 seconds
489               Root dispersion : 0.000015 seconds
490               Reference ID    : 47505300 (GPS)
491               Reference time  : Fri Nov 25 15:22:12 2016
492               Offset          : -0.000060878 seconds
493               Peer delay      : 0.000175634 seconds
494               Peer dispersion : 0.000000681 seconds
495               Response time   : 0.000053050 seconds
496               Jitter asymmetry: +0.00
497               NTP tests       : 111 111 1111
498               Interleaved     : No
499               Authenticated   : No
500               TX timestamping : Kernel
501               RX timestamping : Kernel
502               Total TX        : 24
503               Total RX        : 24
504               Total valid RX  : 24
505
506           The fields are explained as follows:
507
508           Remote address
509               The IP address of the NTP server or peer, and the corresponding
510               reference ID.
511
512           Remote port
513               The UDP port number to which the request was sent. The standard
514               NTP port is 123.
515
516           Local address
517               The local IP address which received the response, and the
518               corresponding reference ID.
519
520           Leap status, Version, Mode, Stratum, Poll interval, Precision, Root
521           delay, Root dispersion, Reference ID, Reference time
522               The NTP values from the last valid response.
523
524           Offset, Peer delay, Peer dispersion
525               The measured values.
526
527           Response time
528               The time the server or peer spent in processing of the request
529               and waiting before sending the response.
530
531           Jitter asymmetry
532               The estimated asymmetry of network jitter on the path to the
533               source. The asymmetry can be between -0.5 and 0.5. A negative
534               value means the delay of packets sent to the source is more
535               variable than the delay of packets sent from the source back.
536
537           NTP tests
538               Results of RFC 5905 tests 1 through 3, 5 through 7, and tests
539               for maximum delay, delay ratio, delay dev ratio, and
540               synchronisation loop.
541
542           Interleaved
543               This shows if the response was in the interleaved mode.
544
545           Authenticated
546               This shows if the response was authenticated.
547
548           TX timestamping
549               The source of the local transmit timestamp. Valid values are
550               Daemon, Kernel, and Hardware.
551
552           RX timestamping
553               The source of the local receive timestamp.
554
555           Total TX
556               The number of packets sent to the source.
557
558           Total RX
559               The number of all packets received from the source.
560
561           Total valid RX
562               The number of valid packets received from the source.
563
564       add peer address [option]...
565           The add peer command allows a new NTP peer to be added whilst
566           chronyd is running.
567
568           Following the words add peer, the syntax of the following
569           parameters and options is similar to that for the peer directive in
570           the configuration file. The following peer options can be set in
571           the command: port, minpoll, maxpoll, presend, maxdelayratio,
572           maxdelay, key.
573
574           An example of using this command is shown below.
575
576               add peer foo.example.net minpoll 6 maxpoll 10 key 25
577
578       add server address [option]...
579           The add server command allows a new NTP server to be added whilst
580           chronyd is running.
581
582           Following the words add server, the syntax of the following
583           parameters and options is similar to that for the server directive
584           in the configuration file. The following server options can be set
585           in the command: port, minpoll, maxpoll, presend, maxdelayratio,
586           maxdelay, key.
587
588           An example of using this command is shown below:
589
590               add server foo.example.net minpoll 6 maxpoll 10 key 25
591
592       delete address
593           The delete command allows an NTP server or peer to be removed from
594           the current set of sources.
595
596       burst good/max [mask/masked-address], burst good/max
597       [masked-address/masked-bits], burst good/max [address]
598           The burst command tells chronyd to make a set of measurements to
599           each of its NTP sources over a short duration (rather than the
600           usual periodic measurements that it makes). After such a burst,
601           chronyd will revert to the previous state for each source. This
602           might be either online, if the source was being periodically
603           measured in the normal way, or offline, if the source had been
604           indicated as being offline. (A source can be switched between the
605           online and offline states with the online and offline commands.)
606
607           The mask and masked-address arguments are optional, in which case
608           chronyd will initiate a burst for all of its currently defined
609           sources.
610
611           The arguments have the following meaning and format:
612
613           good
614               This defines the number of good measurements that chronyd will
615               want to obtain from each source. A measurement is good if it
616               passes certain tests, for example, the round trip time to the
617               source must be acceptable. (This allows chronyd to reject
618               measurements that are likely to be bogus.)
619
620           max
621               This defines the maximum number of measurements that chronyd
622               will attempt to make, even if the required number of good
623               measurements has not been obtained.
624
625           mask
626               This is an IP address with which the IP address of each of
627               chronyd’s sources is to be masked.
628
629           masked-address
630               This is an IP address. If the masked IP address of a source
631               matches this value then the burst command is applied to that
632               source.
633
634           masked-bits
635               This can be used with masked-address for CIDR notation, which
636               is a shorter alternative to the form with mask.
637
638           address
639               This is an IP address or a hostname. The burst command is
640               applied only to that source.
641
642
643
644           If no mask or masked-address arguments are provided, every source
645           will be matched.
646
647           An example of the two-argument form of the command is:
648
649               burst 2/10
650
651           This will cause chronyd to attempt to get two good measurements
652           from each source, stopping after two have been obtained, but in no
653           event will it try more than ten probes to the source.
654
655           Examples of the four-argument form of the command are:
656
657               burst 2/10 255.255.0.0/1.2.0.0
658               burst 2/10 2001:db8:789a::/48
659
660           In the first case, the two out of ten sampling will only be applied
661           to sources whose IPv4 addresses are of the form 1.2.x.y, where x
662           and y are arbitrary. In the second case, the sampling will be
663           applied to sources whose IPv6 addresses have first 48 bits equal to
664           2001:db8:789a.
665
666           Example of the three-argument form of the command is:
667
668               burst 2/10 foo.example.net
669
670       maxdelay address delay
671           This allows the maxdelay option for one of the sources to be
672           modified, in the same way as specifying the maxdelay option for the
673           server directive in the configuration file.
674
675       maxdelaydevratio address ratio
676           This allows the maxdelaydevratio option for one of the sources to
677           be modified, in the same way as specifying the maxdelaydevratio
678           option for the server directive in the configuration file.
679
680       maxdelayratio address ratio
681           This allows the maxdelayratio option for one of the sources to be
682           modified, in the same way as specifying the maxdelayratio option
683           for the server directive in the configuration file.
684
685       maxpoll address maxpoll
686           The maxpoll command is used to modify the maximum polling interval
687           for one of the current set of sources. It is equivalent to the
688           maxpoll option in the server directive in the configuration file.
689
690           Note that the new maximum polling interval only takes effect after
691           the next measurement has been made.
692
693       minpoll address minpoll
694           The minpoll command is used to modify the minimum polling interval
695           for one of the current set of sources. It is equivalent to the
696           minpoll option in the server directive in the configuration file.
697
698           Note that the new minimum polling interval only takes effect after
699           the next measurement has been made.
700
701       minstratum address minstratum
702           The minstratum command is used to modify the minimum stratum for
703           one of the current set of sources. It is equivalent to the
704           minstratum option in the server directive in the configuration
705           file.
706
707       offline [address], offline [masked-address/masked-bits], offline
708       [mask/masked-address]
709           The offline command is used to warn chronyd that the network
710           connection to a particular host or hosts is about to be lost, e.g.
711           on computers with intermittent connection to their time sources.
712
713           Another case where offline could be used is where a computer serves
714           time to a local group of computers, and has a permanent connection
715           to true time servers outside the organisation. However, the
716           external connection is heavily loaded at certain times of the day
717           and the measurements obtained are less reliable at those times. In
718           this case, it is probably most useful to determine the gain or loss
719           rate during the quiet periods and let the whole network coast
720           through the loaded periods. The offline and online commands can be
721           used to achieve this.
722
723           There are four forms of the offline command. The first form is a
724           wildcard, meaning all sources. The second form allows an IP address
725           mask and a masked address to be specified. The third form uses CIDR
726           notation. The fourth form uses an IP address or a hostname. These
727           forms are illustrated below.
728
729               offline
730               offline 255.255.255.0/1.2.3.0
731               offline 2001:db8:789a::/48
732               offline foo.example.net
733
734           The second form means that the offline command is to be applied to
735           any source whose IPv4 address is in the 1.2.3 subnet. (The host’s
736           address is logically and-ed with the mask, and if the result
737           matches the masked-address the host is processed.) The third form
738           means that the command is to be applied to all sources whose IPv6
739           addresses have their first 48 bits equal to 2001:db8:789a. The
740           fourth form means that the command is to be applied only to that
741           one source.
742
743           The wildcard form of the address is equivalent to:
744
745               offline 0.0.0.0/0.0.0.0
746               offline ::/0
747
748       online [address], online [masked-address/masked-bits], online
749       [mask/masked-address]
750           The online command is opposite in function to the offline command.
751           It is used to advise chronyd that network connectivity to a
752           particular source or sources has been restored.
753
754           The syntax is identical to that of the offline command.
755
756       onoffline
757           The onoffline command tells chronyd to switch all sources to the
758           online or offline status according to the current network
759           configuration. A source is considered online if it is possible to
760           send requests to it, i.e. a route to the network is present.
761
762       polltarget address polltarget
763           The polltarget command is used to modify the poll target for one of
764           the current set of sources. It is equivalent to the polltarget
765           option in the server directive in the configuration file.
766
767       refresh
768           The refresh command can be used to force chronyd to resolve the
769           names of configured sources to IP addresses again, e.g. after
770           suspending and resuming the machine in a different network.
771
772           Sources that stop responding will be replaced with newly resolved
773           addresses automatically after 8 polling intervals, but this command
774           can still be useful to replace them immediately and not wait until
775           they are marked as unreachable.
776
777   Manual time input
778       manual on, manual off, manual delete index, manual list, manual reset
779           The manual command enables and disables use of the settime command,
780           and is used to modify the behaviour of the manual clock driver.
781
782           The on form of the command enables use of the settime command.
783
784           The off form of the command disables use of the settime command.
785
786           The list form of the command lists all the samples currently stored
787           in chronyd. The output is illustrated below.
788
789               210 n_samples = 1
790               #    Date  Time(UTC)    Slewed   Original   Residual
791               ====================================================
792                0 27Jan99 22:09:20       0.00       0.97       0.00
793
794           The columns are as as follows:
795
796            1. The sample index (used for the manual delete command).
797
798            2. The date and time of the sample.
799
800            3. The system clock error when the timestamp was entered, adjusted
801               to allow for changes made to the system clock since.
802
803            4. The system clock error when the timestamp was entered, as it
804               originally was (without allowing for changes to the system
805               clock since).
806
807            5. The regression residual at this point, in seconds. This allows
808               ‘outliers’ to be easily spotted, so that they can be deleted
809               using the manual delete command.
810
811
812
813           The delete form of the command deletes a single sample. The
814           parameter is the index of the sample, as shown in the first column
815           of the output from manual list. Following deletion of the data
816           point, the current error and drift rate are re-estimated from the
817           remaining data points and the system clock trimmed if necessary.
818           This option is intended to allow ‘outliers’ to be discarded, i.e.
819           samples where the administrator realises they have entered a very
820           poor timestamp.
821
822           The reset form of the command deletes all samples at once. The
823           system clock is left running as it was before the command was
824           entered.
825
826       settime time
827           The settime command allows the current time to be entered manually,
828           if this option has been configured into chronyd. (It can be
829           configured either with the manual directive in the configuration
830           file, or with the manual command of chronyc.)
831
832           It should be noted that the computer’s sense of time will only be
833           as accurate as the reference you use for providing this input (e.g.
834           your watch), as well as how well you can time the press of the
835           return key.
836
837           Providing your computer’s time zone is set up properly, you will be
838           able to enter a local time (rather than UTC).
839
840           The response to a successful settime command indicates the amount
841           that the computer’s clock was wrong. It should be apparent from
842           this if you have entered the time wrongly, e.g. with the wrong time
843           zone.
844
845           The rate of drift of the system clock is estimated by a regression
846           process using the entered measurement and all previous measurements
847           entered during the present run of chronyd. However, the entered
848           measurement is used for adjusting the current clock offset (rather
849           than the estimated intercept from the regression, which is
850           ignored). Contrast what happens with the manual delete command,
851           where the intercept is used to set the current offset (since there
852           is no measurement that has just been entered in that case).
853
854           The time is parsed by the public domain getdate algorithm.
855           Consequently, you can only specify time to the nearest second.
856
857           Examples of inputs that are valid are shown below:
858
859               settime 16:30
860               settime 16:30:05
861               settime Nov 21, 2015 16:30:05
862
863           For a full description of getdate, see the getdate documentation
864           (bundled, for example, with the source for GNU tar).
865
866   NTP access
867       accheck address
868           This command allows you to check whether client NTP access is
869           allowed from a particular host.
870
871           Examples of use, showing a named host and a numeric IP address, are
872           as follows:
873
874               accheck foo.example.net
875               accheck 1.2.3.4
876               accheck 2001:db8::1
877
878           This command can be used to examine the effect of a series of
879           allow, allow all, deny, and deny all commands specified either via
880           chronyc, or in chronyd’s configuration file.
881
882       clients
883           This command shows a list of clients that have accessed the server,
884           through either the NTP or command ports. It does not include
885           accesses over the Unix domain command socket. There are no
886           arguments.
887
888           An example of the output is:
889
890               Hostname                      NTP   Drop Int IntL Last     Cmd   Drop Int  Last
891               ===============================================================================
892               localhost                       2      0   2   -   133      15      0  -1     7
893               foo.example.net                12      0   6   -    23       0      0   -     -
894
895           Each row shows the data for a single host. Only hosts that have
896           passed the host access checks (set with the allow, deny, cmdallow
897           and cmddeny commands or configuration file directives) are logged.
898           The intervals are displayed as a power of 2 in seconds.
899
900           The columns are as follows:
901
902            1. The hostname of the client.
903
904            2. The number of NTP packets received from the client.
905
906            3. The number of NTP packets dropped to limit the response rate.
907
908            4. The average interval between NTP packets.
909
910            5. The average interval between NTP packets after limiting the
911               response rate.
912
913            6. Time since the last NTP packet was received
914
915            7. The number of command packets received from the client.
916
917            8. The number of command packets dropped to limit the response
918               rate.
919
920            9. The average interval between command packets.
921
922            10. Time since the last command packet was received.
923
924       serverstats
925           The serverstats command displays how many valid NTP and command
926           requests chronyd as a server received from clients, how many of
927           them were dropped to limit the response rate as configured by the
928           ratelimit and cmdratelimit directives, and how many client log
929           records were dropped due to the memory limit configured by the
930           clientloglimit directive. An example of the output is shown below.
931
932               NTP packets received       : 1598
933               NTP packets dropped        : 8
934               Command packets received   : 19
935               Command packets dropped    : 0
936               Client log records dropped : 0
937
938       allow [all] [subnet]
939           The effect of the allow command is identical to the allow directive
940           in the configuration file.
941
942           The syntax is illustrated in the following examples:
943
944               allow foo.example.net
945               allow all 1.2
946               allow 3.4.5
947               allow 6.7.8/22
948               allow 6.7.8.9/22
949               allow 2001:db8:789a::/48
950               allow 0/0
951               allow ::/0
952               allow
953               allow all
954
955       deny [all] [subnet]
956           The effect of the allow command is identical to the deny directive
957           in the configuration file.
958
959           The syntax is illustrated in the following examples:
960
961               deny foo.example.net
962               deny all 1.2
963               deny 3.4.5
964               deny 6.7.8/22
965               deny 6.7.8.9/22
966               deny 2001:db8:789a::/48
967               deny 0/0
968               deny ::/0
969               deny
970               deny all
971
972       local [option]..., local off
973           The local command allows chronyd to be told that it is to appear as
974           a reference source, even if it is not itself properly synchronised
975           to an external source. (This can be used on isolated networks, to
976           allow one computer to be a master time server with the other
977           computers slaving to it.)
978
979           The first form enables the local reference mode on the host. The
980           syntax is identical to the local directive in the configuration
981           file.
982
983           The second form disables the local reference mode.
984
985       smoothing
986           The smoothing command displays the current state of the NTP server
987           time smoothing, which can be enabled with the smoothtime directive.
988           An example of the output is shown below.
989
990               Active         : Yes
991               Offset         : +1.000268817 seconds
992               Frequency      : -0.142859 ppm
993               Wander         : -0.010000 ppm per second
994               Last update    : 17.8 seconds ago
995               Remaining time : 19988.4 seconds
996
997           The fields are explained as follows:
998
999           Active
1000               This shows if the server time smoothing is currently active.
1001               Possible values are Yes and No. If the leaponly option is
1002               included in the smoothtime directive, (leap second only) will
1003               be shown on the line.
1004
1005           Offset
1006               This is the current offset applied to the time sent to NTP
1007               clients. Positive value means the clients are getting time
1008               that’s ahead of true time.
1009
1010           Frequency
1011               The current frequency offset of the served time. Negative value
1012               means the time observed by clients is running slower than true
1013               time.
1014
1015           Wander
1016               The current frequency wander of the served time. Negative value
1017               means the time observed by clients is slowing down.
1018
1019           Last update
1020               This field shows how long ago the time smoothing process was
1021               updated, e.g. chronyd accumulated a new measurement.
1022
1023           Remaining time
1024               The time it would take for the smoothing process to get to zero
1025               offset and frequency if there were no more updates.
1026
1027       smoothtime activate, smoothtime reset
1028           The smoothtime command can be used to activate or reset the server
1029           time smoothing process if it is configured with the smoothtime
1030           directive.
1031
1032   Monitoring access
1033       cmdaccheck address
1034           This command is similar to the accheck command, except that it is
1035           used to check whether monitoring access is permitted from a named
1036           host.
1037
1038           Examples of use are as follows:
1039
1040               cmdaccheck foo.example.net
1041               cmdaccheck 1.2.3.4
1042               cmdaccheck 2001:db8::1
1043
1044       cmdallow [all] [subnet]
1045           This is similar to the allow command, except that it is used to
1046           allow particular hosts or subnets to use chronyc to monitor with
1047           chronyd on the current host.
1048
1049       cmddeny [all] [subnet]
1050           This is similar to the deny command, except that it is used to
1051           allow particular hosts or subnets to use chronyc to monitor chronyd
1052           on the current host.
1053
1054   Real-time clock (RTC)
1055       rtcdata
1056           The rtcdata command displays the current RTC parameters.
1057
1058           An example output is shown below.
1059
1060               RTC ref time (GMT) : Sat May 30 07:25:56 2015
1061               Number of samples  : 10
1062               Number of runs     : 5
1063               Sample span period :  549
1064               RTC is fast by     :    -1.632736 seconds
1065               RTC gains time at  :  -107.623 ppm
1066
1067           The fields have the following meaning:
1068
1069           RTC ref time (GMT)
1070               This is the RTC reading the last time its error was measured.
1071
1072           Number of samples
1073               This is the number of previous measurements being used to
1074               determine the RTC gain or loss rate.
1075
1076           Number of runs
1077               This is the number of runs of residuals of the same sign
1078               following the regression fit for (RTC error) versus (RTC time).
1079               A value which is small indicates that the measurements are not
1080               well approximated by a linear model, and that the algorithm
1081               will tend to delete the older measurements to improve the fit.
1082
1083           Sample span period
1084               This is the period that the measurements span (from the oldest
1085               to the newest). Without a unit the value is in seconds;
1086               suffixes m for minutes, h for hours, d for days or y for years
1087               can be used.
1088
1089           RTC is fast by
1090               This is the estimate of how many seconds fast the RTC when it
1091               thought the time was at the reference time (above). If this
1092               value is large, you might (or might not) want to use the
1093               trimrtc command to bring the RTC into line with the system
1094               clock. (Note, a large error will not affect chronyd’s
1095               operation, unless it becomes so big as to start causing
1096               rounding errors.)
1097
1098           RTC gains time at
1099               This is the amount of time gained (positive) or lost (negative)
1100               by the real time clock for each second that it ticks. It is
1101               measured in parts per million. So if the value shown was +1,
1102               suppose the RTC was exactly right when it crosses a particular
1103               second boundary. Then it would be 1 microsecond fast when it
1104               crosses its next second boundary.
1105
1106       trimrtc
1107           The trimrtc command is used to correct the system’s real-time clock
1108           (RTC) to the main system clock. It has no effect if the error
1109           between the two clocks is currently estimated at less than a
1110           second.
1111
1112           The command takes no arguments. It performs the following steps (if
1113           the RTC is more than 1 second away from the system clock):
1114
1115            1. Remember the currently estimated gain or loss rate of the RTC
1116               and flush the previous measurements.
1117
1118            2. Step the real-time clock to bring it within a second of the
1119               system clock.
1120
1121            3. Make several measurements to accurately determine the new
1122               offset between the RTC and the system clock (i.e. the remaining
1123               fraction of a second error).
1124
1125            4. Save the RTC parameters to the RTC file (specified with the
1126               rtcfile directive in the configuration file).
1127
1128
1129
1130           The last step is done as a precaution against the computer
1131           suffering a power failure before either the daemon exits or the
1132           writertc command is issued.
1133
1134           chronyd will still work perfectly well both whilst operating and
1135           across machine reboots even if the trimrtc command is never used
1136           (and the RTC is allowed to drift away from true time). The trimrtc
1137           command is provided as a method by which it can be corrected, in a
1138           manner compatible with chronyd using it to maintain accurate time
1139           across machine reboots.
1140
1141           The trimrtc command can be executed automatically by chronyd with
1142           the rtcautotrim directive in the configuration file.
1143
1144       writertc
1145           The writertc command writes the currently estimated error and gain
1146           or loss rate parameters for the RTC to the RTC file (specified with
1147           the rtcfile directive). This information is also written
1148           automatically when chronyd is killed (by the SIGHUP, SIGINT,
1149           SIGQUIT or SIGTERM signals) or when the trimrtc command is issued.
1150
1151   Other daemon commands
1152       cyclelogs
1153           The cyclelogs command causes all of chronyd’s open log files to be
1154           closed and re-opened. This allows them to be renamed so that they
1155           can be periodically purged. An example of how to do this is shown
1156           below.
1157
1158               # mv /var/log/chrony/measurements.log /var/log/chrony/measurements1.log
1159               # chronyc cyclelogs
1160               # ls -l /var/log/chrony
1161               -rw-r--r--   1 root     root            0 Jun  8 18:17 measurements.log
1162               -rw-r--r--   1 root     root        12345 Jun  8 18:17 measurements1.log
1163               # rm -f measurements1.log
1164
1165       dump
1166           The dump command causes chronyd to write its current history of
1167           measurements for each of its sources to dump files in the directory
1168           specified in the configuration file by the dumpdir directive. Note
1169           that chronyd does this automatically when it exits. This command is
1170           mainly useful for inspection of the history whilst chronyd is
1171           running.
1172
1173       rekey
1174           The rekey command causes chronyd to re-read the key file specified
1175           in the configuration file by the keyfile directive.
1176
1177       shutdown
1178           The shutdown command causes chronyd to exit. This is equivalent to
1179           sending the process the SIGTERM signal.
1180
1181   Client commands
1182       dns option
1183           The dns command configures how hostnames and IP addresses are
1184           resolved in chronyc. IP addresses can be resolved to hostnames when
1185           printing results of sources, sourcestats, tracking and clients
1186           commands. Hostnames are resolved in commands that take an address
1187           as argument.
1188
1189           There are five options:
1190
1191           dns -n
1192               Disables resolving IP addresses to hostnames. Raw IP addresses
1193               will be displayed.
1194
1195           dns +n
1196               Enables resolving IP addresses to hostnames. This is the
1197               default unless chronyc was started with -n option.
1198
1199           dns -4
1200               Resolves hostnames only to IPv4 addresses.
1201
1202           dns -6
1203               Resolves hostnames only to IPv6 addresses.
1204
1205           dns -46
1206               Resolves hostnames to both address families. This is the
1207               default behaviour unless chronyc was started with the -4 or -6
1208               option.
1209
1210       timeout timeout
1211           The timeout command sets the initial timeout for chronyc requests
1212           in milliseconds. If no response is received from chronyd, the
1213           timeout is doubled and the request is resent. The maximum number of
1214           retries is configured with the retries command.
1215
1216           By default, the timeout is 1000 milliseconds.
1217
1218       retries retries
1219           The retries command sets the maximum number of retries for chronyc
1220           requests before giving up. The response timeout is controlled by
1221           the timeout command.
1222
1223           The default is 2.
1224
1225       keygen [id [type [bits]]]
1226           The keygen command generates a key that can be added to the key
1227           file (specified with the keyfile directive) to allow NTP
1228           authentication between server and client, or peers. The key is
1229           generated from the /dev/urandom device and it is printed to
1230           standard output.
1231
1232           The command has three optional arguments. The first argument is the
1233           key number (by default 1), which will be specified with the key
1234           option of the server or peer directives in the configuration file.
1235           The second argument is the hash function (by default SHA1 or MD5 if
1236           SHA1 is not available) and the third argument is the number of bits
1237           the key should have, between 80 and 4096 bits (by default 160
1238           bits).
1239
1240           An example is:
1241
1242               keygen 73 SHA1 256
1243
1244           which generates a 256-bit SHA1 key with number 73. The printed line
1245           should then be securely transferred and added to the key files on
1246           both server and client, or peers.
1247
1248       exit, quit
1249           The exit and quit commands exit from chronyc and return the user to
1250           the shell.
1251
1252       help
1253           The help command displays a summary of the commands and their
1254           arguments.
1255

SEE ALSO

1257       chrony.conf(5), chronyd(8)
1258

BUGS

1260       For instructions on how to report bugs, please visit <https://
1261       chrony.tuxfamily.org/>.
1262

AUTHORS

1264       chrony was written by Richard Curnow, Miroslav Lichvar, and others.
1265
1266
1267
1268chrony 3.5                        2019-05-10                        CHRONYC(1)
Impressum