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