1CHRONYC(1) User manual CHRONYC(1)
2
6 chronyc - command-line interface for chrony daemon
7
9 chronyc [OPTION]... [COMMAND]...
10
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 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 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 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 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 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
47 -4
48 With this option hostnames will be resolved only to IPv4 addresses.
49 -6
51 With this option hostnames will be resolved only to IPv6 addresses.
52 -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 -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 -d
65 This option enables printing of debugging messages if chronyc was
66 compiled with debugging support.
67 -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 -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 The default is to contact chronyd running on the same host where
80 chronyc is being run.
81 -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 -f file
88 This option is ignored and is provided only for compatibility.
89 -a
91 This option is ignored and is provided only for compatibility.
92 -v
94 With this option chronyc displays its version number on the
95 terminal and exits.
96
98 This section describes each of the commands available within the
99 chronyc program.
100 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 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 The fields are explained as follows:
121 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 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 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 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 Ref time
147 This is the time (UTC) at which the last measurement from the
148 reference source was processed.
149 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 Last offset
164 This is the estimated local offset on the last clock update.
165 RMS offset
167 This is a long-term average of the offset value.
168 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 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 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 Skew
195 This is the estimated error bound on the frequency.
196 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 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 An absolute bound on the computer’s clock accuracy (assuming
209 the stratum-1 computer is correct) is given by:
210 clock_error <= |system_time_offset| + root_dispersion + (0.5 * root_delay)
212 Update interval
214 This is the interval between the last two clock updates.
215 Leap status
217 This is the leap status, which can be Normal, Insert second,
218 Delete second or Not synchronised.
219 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 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 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 makestep 0.1 1
242 burst 1/2
243 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 maxupdateskew skew-in-ppm
249 This command has the same effect as the maxupdateskew directive in
250 the configuration file.
251 waitsync [max-tries [max-correction [max-skew [interval]]]]
253 The waitsync command waits for chronyd to synchronise.
254 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 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 The fourth argument is the interval specified in seconds in which
267 the check is repeated. The interval is 10 seconds by default.
268 An example is:
270 waitsync 60 0.01
272 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 Time sources
278 sources [-v]
279 This command displays information about the current time sources
280 that chronyd is accessing.
281 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 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 The columns are as follows:
294 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 S
301 This column indicates the state of the source.
302 · * indicates the source to which chronyd is currently
304 synchronised.
305 · + indicates acceptable sources which are combined with the
307 selected source.
308 · - indicates acceptable sources which are excluded by the
310 combining algorithm.
311 · ? 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 · 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 · ~ indicates a source whose time appears to have too much
322 variability.
323 Name/IP address
325 This shows the name or the IP address of the source, or
326 reference ID for reference clocks.
327 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 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 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 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 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 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 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 An example report is:
379 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 The columns are as follows:
386 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 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 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 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 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 Freq Skew
418 This is the estimated error bounds on Freq (again in parts per
419 million).
420 Offset
422 This is the estimated offset of the source.
423 Std Dev
425 This is the estimated sample standard deviation.
426 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 The reselect command can be used to force chronyd to reselect the
433 best synchronisation source.
434 reselectdist distance
436 The reselectdist command sets the reselection distance. It is
437 equivalent to the reselectdist directive in the configuration file.
438 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 The report shows the number of servers and peers in 5 states:
448 online
450 the server or peer is currently online (i.e. assumed by chronyd
451 to be reachable)
452 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 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 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 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 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 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 The fields are explained as follows:
507 Remote address
509 The IP address of the NTP server or peer, and the corresponding
510 reference ID.
511 Remote port
513 The UDP port number to which the request was sent. The standard
514 NTP port is 123.
515 Local address
517 The local IP address which received the response, and the
518 corresponding reference ID.
519 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 Offset, Peer delay, Peer dispersion
525 The measured values.
526 Response time
528 The time the server or peer spent in processing of the request
529 and waiting before sending the response.
530 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 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 Interleaved
543 This shows if the response was in the interleaved mode.
544 Authenticated
546 This shows if the response was authenticated.
547 TX timestamping
549 The source of the local transmit timestamp. Valid values are
550 Daemon, Kernel, and Hardware.
551 RX timestamping
553 The source of the local receive timestamp.
554 Total TX
556 The number of packets sent to the source.
557 Total RX
559 The number of all packets received from the source.
560 Total valid RX
562 The number of valid packets received from the source.
563 add peer address [option]...
565 The add peer command allows a new NTP peer to be added whilst
566 chronyd is running.
567 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 An example of using this command is shown below.
575 add peer foo.example.net minpoll 6 maxpoll 10 key 25
577 add server address [option]...
579 The add server command allows a new NTP server to be added whilst
580 chronyd is running.
581 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 An example of using this command is shown below:
589 add server foo.example.net minpoll 6 maxpoll 10 key 25
591 delete address
593 The delete command allows an NTP server or peer to be removed from
594 the current set of sources.
595 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 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 The arguments have the following meaning and format:
612 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 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 mask
626 This is an IP address with which the IP address of each of
627 chronyd’s sources is to be masked.
628 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 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 address
639 This is an IP address or a hostname. The burst command is
640 applied only to that source.
641 If no mask or masked-address arguments are provided, every source
645 will be matched.
646 An example of the two-argument form of the command is:
648 burst 2/10
650 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 Examples of the four-argument form of the command are:
656 burst 2/10 255.255.0.0/1.2.0.0
658 burst 2/10 2001:db8:789a::/48
659 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 Example of the three-argument form of the command is:
667 burst 2/10 foo.example.net
669 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 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 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 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 Note that the new maximum polling interval only takes effect after
691 the next measurement has been made.
692 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 Note that the new minimum polling interval only takes effect after
699 the next measurement has been made.
700 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 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 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 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 offline
730 offline 255.255.255.0/1.2.3.0
731 offline 2001:db8:789a::/48
732 offline foo.example.net
733 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 The wildcard form of the address is equivalent to:
744 offline 0.0.0.0/0.0.0.0
746 offline ::/0
747 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 The syntax is identical to that of the offline command.
755 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 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 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 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 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 The on form of the command enables use of the settime command.
783 The off form of the command disables use of the settime command.
785 The list form of the command lists all the samples currently stored
787 in chronyd. The output is illustrated below.
788 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 The columns are as as follows:
795 1. The sample index (used for the manual delete command).
797 2. The date and time of the sample.
799 3. The system clock error when the timestamp was entered, adjusted
801 to allow for changes made to the system clock since.
802 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 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 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 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 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 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 Providing your computer’s time zone is set up properly, you will be
838 able to enter a local time (rather than UTC).
839 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 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 The time is parsed by the public domain getdate algorithm.
855 Consequently, you can only specify time to the nearest second.
856 Examples of inputs that are valid are shown below:
858 settime 16:30
860 settime 16:30:05
861 settime Nov 21, 2015 16:30:05
862 For a full description of getdate, see the getdate documentation
864 (bundled, for example, with the source for GNU tar).
865 NTP access
867 accheck address
868 This command allows you to check whether client NTP access is
869 allowed from a particular host.
870 Examples of use, showing a named host and a numeric IP address, are
872 as follows:
873 accheck foo.example.net
875 accheck 1.2.3.4
876 accheck 2001:db8::1
877 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 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 An example of the output is:
889 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 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 The columns are as follows:
901 1. The hostname of the client.
903 2. The number of NTP packets received from the client.
905 3. The number of NTP packets dropped to limit the response rate.
907 4. The average interval between NTP packets.
909 5. The average interval between NTP packets after limiting the
911 response rate.
912 6. Time since the last NTP packet was received
914 7. The number of command packets received from the client.
916 8. The number of command packets dropped to limit the response
918 rate.
919 9. The average interval between command packets.
921 10. Time since the last command packet was received.
923 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 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 allow [all] [subnet]
939 The effect of the allow command is identical to the allow directive
940 in the configuration file.
941 The syntax is illustrated in the following examples:
943 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 deny [all] [subnet]
956 The effect of the allow command is identical to the deny directive
957 in the configuration file.
958 The syntax is illustrated in the following examples:
960 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 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 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 The second form disables the local reference mode.
984 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 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 The fields are explained as follows:
998 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 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 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 Wander
1016 The current frequency wander of the served time. Negative value
1017 means the time observed by clients is slowing down.
1018 Last update
1020 This field shows how long ago the time smoothing process was
1021 updated, e.g. chronyd accumulated a new measurement.
1022 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 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 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 Examples of use are as follows:
1039 cmdaccheck foo.example.net
1041 cmdaccheck 1.2.3.4
1042 cmdaccheck 2001:db8::1
1043 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 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 Real-time clock (RTC)
1055 rtcdata
1056 The rtcdata command displays the current RTC parameters.
1057 An example output is shown below.
1059 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 The fields have the following meaning:
1068 RTC ref time (GMT)
1070 This is the RTC reading the last time its error was measured.
1071 Number of samples
1073 This is the number of previous measurements being used to
1074 determine the RTC gain or loss rate.
1075 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 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 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 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 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 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 1. Remember the currently estimated gain or loss rate of the RTC
1116 and flush the previous measurements.
1117 2. Step the real-time clock to bring it within a second of the
1119 system clock.
1120 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 4. Save the RTC parameters to the RTC file (specified with the
1126 rtcfile directive in the configuration file).
1127 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 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 The trimrtc command can be executed automatically by chronyd with
1142 the rtcautotrim directive in the configuration file.
1143 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 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 # 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 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 rekey
1174 The rekey command causes chronyd to re-read the key file specified
1175 in the configuration file by the keyfile directive.
1176 shutdown
1178 The shutdown command causes chronyd to exit. This is equivalent to
1179 sending the process the SIGTERM signal.
1180 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 There are five options:
1190 dns -n
1192 Disables resolving IP addresses to hostnames. Raw IP addresses
1193 will be displayed.
1194 dns +n
1196 Enables resolving IP addresses to hostnames. This is the
1197 default unless chronyc was started with -n option.
1198 dns -4
1200 Resolves hostnames only to IPv4 addresses.
1201 dns -6
1203 Resolves hostnames only to IPv6 addresses.
1204 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 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 By default, the timeout is 1000 milliseconds.
1217 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 The default is 2.
1224 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 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 An example is:
1241 keygen 73 SHA1 256
1243 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 exit, quit
1249 The exit and quit commands exit from chronyc and return the user to
1250 the shell.
1251 help
1253 The help command displays a summary of the commands and their
1254 arguments.
1255
1257 chrony.conf(5), chronyd(8)
1258
1260 For instructions on how to report bugs, please visit <https://
1261 chrony.tuxfamily.org/>.
1262
1264 chrony was written by Richard Curnow, Miroslav Lichvar, and others.
1265chrony 3.4 2018-09-19 CHRONYC(1)