summaryrefslogtreecommitdiffstats
path: root/doc/chronyc.adoc
blob: 1a843c3835e9922d706257ffdb7b2062bdd3fd3a (plain)
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
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
// This file is part of chrony
//
// Copyright (C) Richard P. Curnow  1997-2003
// Copyright (C) Stephen Wadeley  2016
// Copyright (C) Miroslav Lichvar  2009-2017, 2019-2023
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of version 2 of the GNU General Public License as
// published by the Free Software Foundation.
//
// This program is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// General Public License for more details.
//
// You should have received a copy of the GNU General Public License along
// with this program; if not, write to the Free Software Foundation, Inc.,
// 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

= chronyc(1)
:doctype: manpage
:man manual: User manual
:man source: chrony @CHRONY_VERSION@

== NAME

chronyc - command-line interface for chrony daemon

== SYNOPSIS

*chronyc* [_OPTION_]... [_COMMAND_]...

== DESCRIPTION

*chronyc* is a command-line interface program which can be used to monitor
*chronyd*'s performance and to change various operating parameters whilst it is
running.

If no commands are specified on the command line, *chronyc* will expect input
from the user. The prompt _chronyc>_ will be displayed when it is being run
from a terminal. If *chronyc*'s input or output are redirected from or to a file,
the prompt will not be shown.

There are two ways *chronyc* can access *chronyd*. One is the Internet
Protocol (IPv4 or IPv6) and the other is a Unix domain socket, which is
accessible locally by the root or _chrony_ user. By default, *chronyc* first
tries to connect to the Unix domain socket. The compiled-in default path is
_@CHRONYRUNDIR@/chronyd.sock_. If that fails (e.g. because *chronyc* is
running under a non-root user), it will try to connect to 127.0.0.1 and then
::1.

Only the following monitoring commands, which do not affect the behaviour of
*chronyd*, are allowed from the network: *activity*, *manual list*,
*rtcdata*, *smoothing*, *sourcename*, *sources*, *sourcestats*, *tracking*,
*waitsync*. The
set of hosts from which *chronyd* will accept these commands can be configured
with the <<chrony.conf.adoc#cmdallow,*cmdallow*>> directive in the *chronyd*'s
configuration file or the <<cmdallow,*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.

Having full access to *chronyd* via *chronyc* is more or less equivalent to
being able to modify the *chronyd*'s configuration file and restart it.

== OPTIONS

*-4*::
With this option hostnames will be resolved only to IPv4 addresses.

*-6*::
With this option hostnames will be resolved only to IPv6 addresses.

*-n*::
This option disables resolving of IP addresses to hostnames, e.g. to avoid slow
DNS lookups. Long addresses will not be truncated to fit into the column.

*-N*::
This option enables printing of original hostnames or IP addresses of NTP
sources that were specified in the configuration file, or *chronyc* commands.
Without the *-n* and *-N* option, the printed hostnames are obtained from
reverse DNS lookups and can be different from the specified hostnames.

*-c*::
This option enables printing of reports in a comma-separated values (CSV)
format. Reverse DNS lookups will be disabled, time will be printed as number of
seconds since the epoch, and values in seconds will not be converted to other
units.

*-e*::
With this option each *chronyc* response will end with a line containing a
single dot.

*-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 specifies the host to be contacted by *chronyc*. It can be
specified with a hostname, IP address, or path to the local Unix domain socket.
Multiple values can be specified as a comma-separated list to provide a
fallback.
+
The default value is _@CHRONYRUNDIR@/chronyd.sock,127.0.0.1,::1_, i.e. the host
where *chronyc* is being run. First, it tries to connect to the Unix domain
socket and if that fails (e.g. due to running under a non-root user), it
will try to connect to 127.0.0.1 and then ::1.

*-p* _port_::
This option allows the user to specify the UDP port number which the target
*chronyd* is using for its monitoring connections. This defaults to 323; there
would rarely be a need to change this.

*-f* _file_::
This option is ignored and is provided only for compatibility.

*-a*::
This option is ignored and is provided only for compatibility.

*-v*, *--version*::
With this option *chronyc* displays its version number on the terminal and
exits.

*--help*::
With this option *chronyc* displays a help message on the terminal and
exits.

== COMMANDS

This section describes each of the commands available within the *chronyc*
program.

=== System clock

[[tracking]]*tracking*::
The *tracking* command displays parameters about the system's clock
performance. An example of the output is shown below.
+
----
Reference ID    : CB00710F (ntp1.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,*local*>> command in *chronyc*, or the
<<chrony.conf.adoc#local,*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. _ntp1.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*:::
This is the current offset between the NTP clock and system clock. The NTP
clock is a software (virtual) clock maintained by *chronyd*, which is
synchronised to the configured time sources and provides time to NTP clients.
The system clock is synchronised to the NTP clock. To avoid steps in the
system time, which might have adverse consequences for certain applications,
the system clock is normally corrected only by speeding up or slowing down (up
to the rate configured by the <<chrony.conf.adoc#maxslewrate,*maxslewrate*>>
directive). If the offset is too large, this correction will take a very long
time. A step can be forced by the <<makestep,*makestep*>> command, or the
<<chrony.conf.adoc#makestep,*makestep*>> directive in the configuration file.
+
Note that all other offsets reported by *chronyc* and most offsets in the log
files are relative to the NTP clock, not the system clock.
*Last offset*:::
This is the estimated local offset on the last clock update. A positive value
indicates the local time (as previously estimated true time) was ahead of the
time sources.
*RMS offset*:::
This is a long-term average of the offset value.
*Frequency*:::
The '`frequency`' is the rate by which the system's clock would be wrong if
*chronyd* was not correcting it. It is expressed in ppm (parts per million).
For example, a value of 1 ppm would mean that when the system's clock thinks it
has advanced 1 second, it has actually advanced by 1.000001 seconds relative to
true time.
*Residual freq*:::
This shows the '`residual frequency`' for the currently selected reference
source. This reflects any difference between what the measurements from the
reference source indicate the frequency should be and the frequency currently
being used.
+
The reason this is not always zero is that a smoothing procedure is
applied to the frequency. Each time a measurement from the reference
source is obtained and a new residual frequency computed, the estimated
accuracy of this residual is compared with the estimated accuracy (see
'`skew`' next) of the existing frequency value. A weighted average is
computed for the new frequency, with weights depending on these accuracies.
If the measurements from the reference source follow a consistent trend, the
residual will be driven to zero over time.
*Skew*:::
This is the estimated error bound on the frequency.
*Root delay*:::
This is the total of the network path delays to the stratum-1 computer from
which the computer is ultimately synchronised.
*Root dispersion*:::
This is the total dispersion accumulated through all the computers back to
the stratum-1 computer from which the computer is ultimately synchronised.
Dispersion is due to system clock resolution, statistical measurement
variations, etc.
+
An absolute bound on the computer's clock accuracy (assuming the stratum-1
computer is correct) is given by:
+
----
clock_error <= |system_time_offset| + root_dispersion + (0.5 * root_delay)
----
*Update interval*:::
This is the interval between the last two clock updates.
*Leap status*:::
This is the leap status, which can be _Normal_, _Insert second_, _Delete
second_ or _Not synchronised_.

[[makestep]]*makestep*::
*makestep* _threshold_ _limit_::
Normally *chronyd* will cause the system to gradually correct any time offset,
by slowing down or speeding up the clock as required. In certain situations,
the system clock might be so far adrift that this slewing process would take a
very long time to correct the system clock.
+
The *makestep* command can be used in this situation. There are two forms of
the command. The first form has no parameters. It tells *chronyd* to cancel any
remaining correction that was being slewed and jump the system clock by the
equivalent amount, making it correct immediately.
+
The second form configures the automatic stepping, similarly to the
<<chrony.conf.adoc#makestep,*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,*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]]*maxupdateskew* _skew-in-ppm_::
This command has the same effect as the
<<chrony.conf.adoc#maxupdateskew,*maxupdateskew*>> directive in the
configuration file.

[[waitsync]]*waitsync* [_max-tries_ [_max-correction_ [_max-skew_ [_interval_]]]]::
The *waitsync* command waits for *chronyd* to synchronise.
+
Up to four optional arguments can be specified. The first is the maximum number
of tries before giving up and returning a non-zero error code. When 0 is
specified, or there are no arguments, the number of tries will not be limited.
+
The second and third arguments are the maximum allowed remaining correction of
the system clock and the maximum allowed skew (in ppm) as reported by the
<<tracking,*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]]*sources* [*-a*] [*-v*]::
This command displays information about the current time sources that *chronyd*
is accessing.
+
If the *-a* option is specified, all sources are displayed, including those that
do not have a known address yet. Such sources have an identifier in the format
_ID#XXXXXXXXXX_, which can be used in other commands expecting a source address.
+
The *-v* option enables a verbose output. In this case,
extra caption lines are shown as a reminder of the meanings of the columns.
+
----
MS Name/IP address         Stratum Poll Reach LastRx Last sample
===============================================================================
#* GPS0                          0   4   377    11   -479ns[ -621ns] +/-  134ns
^? ntp1.example.net              2   6   377    23   -923us[ -924us] +/-   43ms
^+ ntp2.example.net              1   6   377    21  -2629us[-2619us] +/-   86ms
----
+
The columns are as follows:
+
*M*:::
This indicates the mode of the source. _^_ means a server, _=_ means a peer
and _#_ indicates a locally connected reference clock.
*S*:::
This column indicates the selection state of the source.
* _*_ indicates the best source which is currently selected for
  synchronisation.
* _+_ indicates other sources selected for synchronisation, which are combined
  with the best source.
* _-_ indicates a source which is considered to be selectable for
  synchronisation, but not currently selected.
* _x_ indicates a source which *chronyd* thinks is a falseticker (i.e. its
  time is inconsistent with a majority of other sources, or sources specified
  with the *trust* option).
* _~_ indicates a source whose time appears to have too much variability.
* _?_ indicates a source which is not considered to be selectable for
  synchronisation for other reasons (e.g. unreachable, not synchronised, or
  does not have enough measurements).
{blank}:::
The <<selectdata,*selectdata*>> command can be used to get more details about
the selection state.
*Name/IP address*:::
This shows the name or the IP address of the source, or reference ID for reference
clocks.
*Stratum*:::
This shows the stratum of the source, as reported in its most recently
received sample. Stratum 1 indicates a computer with a locally attached
reference clock. A computer that is synchronised to a stratum 1 computer is
at stratum 2. A computer that is synchronised to a stratum 2 computer is at
stratum 3, and so on.
*Poll*:::
This shows the rate at which the source is being polled, as a base-2
logarithm of the interval in seconds. Thus, a value of 6 would indicate that
a measurement is being made every 64 seconds. *chronyd* automatically varies
the polling rate in response to prevailing conditions.
*Reach*:::
This shows the source's reachability register printed as an octal number. The
register has 8 bits and is updated on every received or missed packet from
the source. A value of 377 indicates that a valid reply was received for all
from the last eight transmissions.
*LastRx*:::
This column shows how long ago the last good sample (which is shown in the next
column) was received from the source. Measurements that failed some tests are
ignored. This is normally in seconds. The letters _m_, _h_, _d_ or _y_ indicate
minutes, hours, days, or years.
*Last sample*:::
This column shows the offset between the local clock and the source at the
last measurement. The number in the square brackets shows the actual measured
offset. This can be suffixed by _ns_ (indicating nanoseconds), _us_
(indicating microseconds), _ms_ (indicating milliseconds), or _s_ (indicating
seconds). The number to the left of the square brackets shows the original
measurement, adjusted to allow for any slews applied to the local clock
since. Positive offsets indicate that the local clock is ahead of the source.
The number following the _+/-_ indicator shows the margin of error in the
measurement (NTP root distance).

[[sourcestats]]*sourcestats* [*-a*] [*-v*]::
The *sourcestats* command displays information about the drift rate and offset
estimation process for each of the sources currently being examined by
*chronyd*.
+
If the *-a* option is specified, all sources are displayed, including those that
do not have a known address yet. Such sources have an identifier in the format
_ID#XXXXXXXXXX_, which can be used in other commands expecting a source address.
+
The *-v* option enables a verbose output. In this case,
extra caption lines are shown as a reminder of the meanings of the columns.
+
An example report is:
+
----
Name/IP Address            NP  NR  Span  Frequency  Freq Skew  Offset  Std Dev
===============================================================================
ntp1.example.net           11   5   46m     -0.001      0.045      1us    25us
----
+
The columns are as follows:
+
*Name/IP Address*:::
This is the name or IP address of the NTP server (or peer) or reference ID of the
reference clock to which the rest of the line relates.
*NP*:::
This is the number of sample points currently being retained for the server.
The drift rate and current offset are estimated by performing a linear
regression through these points.
*NR*:::
This is the number of runs of residuals having the same sign following the
last regression. If this number starts to become too small relative to the
number of samples, it indicates that a straight line is no longer a good fit
to the data. If the number of runs is too low, *chronyd* discards older
samples and re-runs the regression until the number of runs becomes
acceptable.
*Span*:::
This is the interval between the oldest and newest samples. If no unit is
shown the value is in seconds. In the example, the interval is 46 minutes.
*Frequency*:::
This is the estimated residual frequency for the server, in parts per
million. In this case, the computer's clock is estimated to be running 1 part
in 10^9 slow relative to the server.
*Freq Skew*:::
This is the estimated error bounds on *Freq* (again in parts per million).
*Offset*:::
This is the estimated offset of the source.
*Std Dev*:::
This is the estimated sample standard deviation.

[[selectdata]]*selectdata* [*-a*] [*-v*]::
The *selectdata* command displays information specific to the selection of time
sources. If the *-a* option is specified, all sources are displayed, including
those that do not have a known address yet. With the *-v* option, extra caption
lines are shown as a reminder of the meanings of the columns.
+
An example of the output is shown below.
+
----
S Name/IP Address        Auth COpts EOpts Last Score     Interval  Leap
=======================================================================
D ntp1.example.net          Y ----- --TR-    4   1.0   -61ms   +62ms  N
* ntp2.example.net          N ----- -----    0   1.0 -6846us +7305us  N
+ ntp3.example.net          N ----- -----   10   1.0 -7381us +7355us  N
----
+
The columns are as follows:
+
*S*:::
This column indicates the state of the source after the last source selection.
It is similar to the state reported by the *sources* command, but more
states are reported.
{blank}:::
The following states indicate the source is not considered selectable for
synchronisation:
* _N_ - has the *noselect* option.
* _M_ - does not have enough measurements.
* _s_ - is not synchronised.
* _d_ - has a root distance larger than the maximum distance (configured by the
        <<chrony.conf.adoc#maxdistance,*maxdistance*>> directive).
* _~_ - has a jitter larger than the maximum jitter (configured by the
        <<chrony.conf.adoc#maxjitter,*maxjitter*>> directive).
* _w_ - waits for other sources to get out of the _M_ state.
* _S_ - has older measurements than other sources.
* _O_ - has a stratum equal or larger than the orphan stratum (configured by
        the <<chrony.conf.adoc#local,*local*>> directive).
* _T_ - does not fully agree with sources that have the *trust* option.
* _x_ - does not agree with other sources (falseticker).
{blank}:::
The following states indicate the source is considered selectable, but it is
not currently used for synchronisation:
* _W_ - waits for other sources to be selectable (required by the
        <<chrony.conf.adoc#minsources,*minsources*>> directive, or
        the *require* option of another source).
* _P_ - another selectable source is preferred due to the *prefer* option.
* _U_ - waits for a new measurement (after selecting a different best source).
* _D_ - has, or recently had, a root distance which is too large to be combined
        with other sources (configured by the
        <<chrony.conf.adoc#combinelimit,*combinelimit*>> directive).
{blank}:::
The following states indicate the source is used for synchronisation of the
local clock:
* _+_ - combined with the best source.
* _*_ - selected as the best source to update the reference data (e.g. root
        delay, root dispersion).
*Name/IP address*:::
This column shows the name or IP address of the source if it is an NTP server,
or the reference ID if it is a reference clock.
*Auth*:::
This column indicates whether an authentication mechanism is enabled for the
source. _Y_ means yes and _N_ means no.
*COpts*:::
This column displays the configured selection options of the source.
* _N_ indicates the *noselect* option.
* _P_ indicates the *prefer* option.
* _T_ indicates the *trust* option.
* _R_ indicates the *require* option.
*EOpts*:::
This column displays the current effective selection options of the source,
which can be different from the configured options due to the authentication
selection mode (configured by the
<<chrony.conf.adoc#authselectmode,*authselectmode*>> directive). The symbols
are the same as in the *COpts* column.
*Last*:::
This column displays how long ago was the last measurement of the source made
when the selection was performed.
*Score*:::
This column displays the current score against the source in the _*_ state. The
scoring system avoids frequent reselection when multiple sources have a similar
root distance. A value larger than 1 indicates this source was better than the
_*_ source in recent selections. If the score reaches 10, the best source will
be reselected and the scores will be reset to 1.
*Interval*:::
This column displays the lower and upper endpoint of the interval which was
expected to contain the true offset of the local clock considering the root
distance at the time of the selection.
*Leap*:::
This column displays the current leap status of the source.
* _N_ indicates the normal status (no leap second).
* _+_ indicates that a leap second will be inserted at the end of the month.
* _-_ indicates that a leap second will be deleted at the end of the month.
* _?_ indicates the unknown status (i.e. no valid measurement was made).

[[selectopts]]*selectopts* _address|refid_ [_+|-option_]...::
The *selectopts* command modifies the configured selection options of an NTP
source specified by IP address (or the _ID#XXXXXXXXXX_ identifier used for
unknown addresses), or a reference clock specified by reference ID as a string.
+
The selection options can be added with the *+* symbol or removed with the *-*
symbol. The *selectdata* command can be used to verify the configuration. The
modified options will be applied in the next source selection, e.g. when a new
measurement is made, or the *reselect* command is executed.
+
An example of using this command is shown below.
+
----
selectopts 1.2.3.4 -noselect +prefer
selectopts GPS +trust
----

[[reselect]]*reselect*::
To avoid excessive switching between sources, *chronyd* can stay synchronised
to a source even when it is not currently the best one among the available
sources.
+
The *reselect* command can be used to force *chronyd* to reselect the best
synchronisation source.

[[reselectdist]]*reselectdist* _distance_::
The *reselectdist* command sets the reselection distance. It is equivalent to
the <<chrony.conf.adoc#reselectdist,*reselectdist*>> directive in the
configuration file.

[[offset]]*offset* _address|refid_ _offset_::
The *offset* command modifies the offset correction of an NTP source specified
by IP address (or the _ID#XXXXXXXXXX_ identifier used for unknown addresses),
or a reference clock specified by reference ID as a string. It is equivalent to
the *offset* option in the <<chrony.conf.adoc#server,*server*>> or
<<chrony.conf.adoc#refclock,*refclock*>> directive respectively.

=== NTP sources

[[activity]]*activity*::
This command reports the number of servers and peers that are online and
offline. If the *auto_offline* option is used in specifying some of the servers
or peers, the *activity* command can be useful for detecting when all of them
have entered the offline state after the network link has been disconnected.
+
The report shows the number of servers and peers in 5 states:
+
*online*:::
the server or peer is currently online (i.e. assumed by *chronyd* to be reachable)
*offline*:::
the server or peer is currently offline (i.e. assumed by *chronyd* to be
unreachable, and no measurements from it will be attempted.)
*burst_online*:::
a burst command has been initiated for the server or peer and is being
performed; after the burst is complete, the server or peer will be returned to
the online state.
*burst_offline*:::
a burst command has been initiated for the server or peer and is being
performed; after the burst is complete, the server or peer will be returned to
the offline state.
*unresolved*:::
the name of the server or peer was not resolved to an address yet; this source is
not visible in the *sources* and *sourcestats* reports.

[[authdata]]*authdata* [*-a*]::
The *authdata* command displays information specific to authentication of NTP
sources. If the *-a* option is specified, all sources are displayed, including
those that do not have a known address yet. An example of the output is
shown below.
+
----
Name/IP address             Mode KeyID Type KLen Last Atmp  NAK Cook CLen
=========================================================================
ntp1.example.net             NTS     1   15  256 135m    0    0    8  100
ntp2.example.net              SK    30   13  128    -    0    0    0    0
ntp3.example.net               -     0    0    0    -    0    0    0    0
----
+
The columns are as follows:
+
*Name/IP address*:::
This column shows the name or the IP address of the source.
*Mode*:::
This column shows which mechanism authenticates NTP packets received from the
source. _NTS_ means Network Time Security, _SK_ means a symmetric key, and _-_
means authentication is disabled.
*KeyID*:::
This column shows an identifier of the key used for authentication. With a
symmetric key, it is the ID from the <<chrony.conf.adoc#keyfile,key file>>.
With NTS, it is a number starting at zero and incremented by one with each
successful key establishment using the NTS-KE protocol, i.e. it shows how many
times the key establishment was performed with this source.
*Type*:::
This columns shows an identifier of the algorithm used for authentication.
With a symmetric key, it is the hash function or cipher specified in the key
file. With NTS, it is an authenticated encryption with associated data (AEAD)
algorithm, which is negotiated in the NTS-KE protocol. The following values can
be reported:
* 1: MD5
* 2: SHA1
* 3: SHA256
* 4: SHA384
* 5: SHA512
* 6: SHA3-224
* 7: SHA3-256
* 8: SHA3-384
* 9: SHA3-512
* 10: TIGER
* 11: WHIRLPOOL
* 13: AES128
* 14: AES256
* 15: AEAD-AES-SIV-CMAC-256
* 30: AEAD-AES-128-GCM-SIV
*KLen*:::
This column shows the length of the key in bits.
*Last*:::
This column shows how long ago the last successful key establishment was
performed. It is in seconds, or letters _m_, _h_, _d_ or _y_ indicate minutes,
hours, days, or years.
*Atmp*:::
This column shows the number of attempts to perform the key establishment since
the last successful key establishment. A number larger than 1 indicates a
problem with the network or server.
*NAK*:::
This column shows whether an NTS NAK was received since the last request.
A NAK indicates that authentication failed on the server side due to
*chronyd* using a cookie which is no longer valid and that it needs to perform
the key establishment again in order to get new cookies.
*Cook*:::
This column shows the number of NTS cookies that *chronyd* currently has. If
the key establishment was successful, a number smaller than 8 indicates a
problem with the network or server.
*CLen*:::
This column shows the length in bytes of the NTS cookie which will be used in
the next request.

[[ntpdata]]*ntpdata* [_address_]::
The *ntpdata* command displays the last valid measurement and other
NTP-specific information about the specified NTP source, or all NTP sources
(with a known address) if no address was specified. An example of the output is
shown below.
+
----
Remote address  : 203.0.113.15 (CB00710F)
Remote port     : 123
Local address   : 203.0.113.74 (CB00714A)
Leap status     : Normal
Version         : 4
Mode            : Server
Stratum         : 1
Poll interval   : 10 (1024 seconds)
Precision       : -24 (0.000000060 seconds)
Root delay      : 0.000015 seconds
Root dispersion : 0.000015 seconds
Reference ID    : 47505300 (GPS)
Reference time  : Fri Nov 25 15:22:12 2016
Offset          : -0.000060878 seconds
Peer delay      : 0.000175634 seconds
Peer dispersion : 0.000000681 seconds
Response time   : 0.000053050 seconds
Jitter asymmetry: +0.00
NTP tests       : 111 111 1111
Interleaved     : No
Authenticated   : No
TX timestamping : Kernel
RX timestamping : Kernel
Total TX        : 24
Total RX        : 24
Total valid RX  : 24
Total good RX   : 22
Total kernel TX : 24
Total kernel RX : 24
Total HW TX     : 0
Total HW RX     : 0
----
+
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 (or delay quantile), 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 packets which passed the first two groups of NTP tests.
*Total good RX*:::
The number of packets which passed all three groups of NTP tests, i.e. the NTP
measurement was accepted.
*Total kernel TX*:::
The number of packets sent to the source for which a timestamp was captured by
the kernel.
*Total kernel RX*:::
The number of packets received from the source for which a timestamp was
captured by the kernel.
*Total HW TX*:::
The number of packets sent to the source for which a timestamp was captured by
the NIC.
*Total HW RX*:::
The number of packets received from the source for which a timestamp was
captured by the NIC.

[[add_peer]]*add peer* _name_ [_option_]...::
The *add peer* command allows a new NTP peer to be added whilst
*chronyd* is running.
+
Following the words *add peer*, the syntax of the following
parameters and options is identical to that for the
<<chrony.conf.adoc#peer,*peer*>> directive in the configuration file.
+
An example of using this command is shown below.
+
----
add peer ntp1.example.net minpoll 6 maxpoll 10 key 25
----

[[add_pool]]*add pool* _name_ [_option_]...::
The *add pool* command allows a pool of NTP servers to be added whilst
*chronyd* is running.
+
Following the words *add pool*, the syntax of the following parameters and
options is identical to that for the <<chrony.conf.adoc#pool,*pool*>>
directive in the configuration file.
+
An example of using this command is shown below:
+
----
add pool ntp1.example.net maxsources 3 iburst
----

[[add_server]]*add server* _name_ [_option_]...::
The *add server* command allows a new NTP server to be added whilst
*chronyd* is running.
+
Following the words *add server*, the syntax of the following parameters and
options is identical to that for the <<chrony.conf.adoc#server,*server*>>
directive in the configuration file.
+
An example of using this command is shown below:
+
----
add server ntp1.example.net minpoll 6 maxpoll 10 key 25
----

[[delete]]*delete* _address_::
The *delete* command allows an NTP server or peer to be removed
from the current set of sources.

[[burst]]
*burst* _good_/_max_ [_mask_/_masked-address_]::
*burst* _good_/_max_ [_masked-address_/_masked-bits_]::
*burst* _good_/_max_ [_address_]::
The *burst* command tells *chronyd* to make a set of measurements to each of
its NTP sources over a short duration (rather than the usual periodic
measurements that it makes). After such a burst, *chronyd* will revert to the
previous state for each source. This might be either online, if the source was
being periodically measured in the normal way, or offline, if the source had
been indicated as being offline. (A source can be switched between the online
and offline states with the <<online,*online*>> and <<offline,*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.
{blank}::
+
If no _mask_ or _masked-address_ arguments are provided, every source will be
matched.
+
An example of the two-argument form of the command is:
+
----
burst 2/10
----
+
This will cause *chronyd* to attempt to get two good measurements from each
source, stopping after two have been obtained, but in no event will it try more
than ten probes to the source.
+
Examples of the four-argument form of the command are:
+
----
burst 2/10 255.255.0.0/1.2.0.0
burst 2/10 2001:db8:789a::/48
----
+
In the first case, the two out of ten sampling will only be applied to sources
whose IPv4 addresses are of the form _1.2.x.y_, where _x_ and _y_ are
arbitrary. In the second case, the sampling will be applied to sources whose
IPv6 addresses have first 48 bits equal to _2001:db8:789a_.
+
Example of the three-argument form of the command is:
+
----
burst 2/10 ntp1.example.net
----

[[maxdelay]]*maxdelay* _address_ _delay_::
This allows the *maxdelay* option for one of the sources to be modified, in the
same way as specifying the *maxdelay* option for the
<<chrony.conf.adoc#server,*server*>> directive in the configuration file.

[[maxdelaydevratio]]*maxdelaydevratio* _address_ _ratio_::
This allows the *maxdelaydevratio* option for one of the sources to be
modified, in the same way as specifying the *maxdelaydevratio* option for the
<<chrony.conf.adoc#server,*server*>> directive in the configuration file.

[[maxdelayratio]]*maxdelayratio* _address_ _ratio_::
This allows the *maxdelayratio* option for one of the sources to be modified,
in the same way as specifying the *maxdelayratio* option for the
<<chrony.conf.adoc#server,*server*>> directive in the configuration file.

[[maxpoll]]*maxpoll* _address_ _maxpoll_::
The *maxpoll* command is used to modify the maximum polling interval for one of
the current set of sources. It is equivalent to the *maxpoll* option in the
<<chrony.conf.adoc#server,*server*>> directive in the configuration file.
+
Note that the new maximum polling interval only takes effect after the next
measurement has been made.

[[minpoll]]*minpoll* _address_ _minpoll_::
The *minpoll* command is used to modify the minimum polling interval for one of
the current set of sources. It is equivalent to the *minpoll* option in the
<<chrony.conf.adoc#server,*server*>> directive in the configuration file.
+
Note that the new minimum polling interval only takes effect after the next
measurement has been made.

[[minstratum]]*minstratum* _address_ _minstratum_::
The *minstratum* command is used to modify the minimum stratum for one of the
current set of sources. It is equivalent to the *minstratum* option in the
<<chrony.conf.adoc#server,*server*>> directive in the configuration file.

[[offline]]
*offline* [_address_]::
*offline* [_masked-address_/_masked-bits_]::
*offline* [_mask_/_masked-address_]::
The *offline* command is used to warn *chronyd* that the network connection to
a particular host or hosts is about to be lost, e.g. on computers with
intermittent connection to their time sources.
+
Another case where *offline* could be used is where a computer serves time to a
local group of computers, and has a permanent connection to true time servers
outside the organisation. However, the external connection is heavily loaded at
certain times of the day and the measurements obtained are less reliable at
those times. In this case, it is probably most useful to determine the
gain or loss rate during the quiet periods and let the whole network coast through
the loaded periods. The *offline* and *online* commands can be used to achieve
this.
+
There are four forms of the *offline* command. The first form is a wildcard,
meaning all sources (including sources that do not have a known address yet).
The second form allows an IP address mask and a masked
address to be specified. The third form uses CIDR notation. The fourth form
uses an IP address or a hostname. These forms are illustrated below.
+
----
offline
offline 255.255.255.0/1.2.3.0
offline 2001:db8:789a::/48
offline ntp1.example.net
----
+
The second form means that the *offline* command is to be applied to any source
whose IPv4 address is in the _1.2.3_ subnet. (The host's address is logically
and-ed with the mask, and if the result matches the _masked-address_ the host
is processed.) The third form means that the command is to be applied to all
sources whose IPv6 addresses have their first 48 bits equal to _2001:db8:789a_. The
fourth form means that the command is to be applied only to that one source.
+
The wildcard form of the address is equivalent to:
+
----
offline 0.0.0.0/0.0.0.0
offline ::/0
----

[[online]]
*online* [_address_]::
*online* [_masked-address_/_masked-bits_]::
*online* [_mask_/_masked-address_]::
The *online* command is opposite in function to the <<offline,*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,*offline*>> command.

[[onoffline]]
*onoffline*::
The *onoffline* command tells *chronyd* to switch all sources that have a known
address to the online or
offline status according to the current network configuration. A source is
considered online if it is possible to send requests to it, i.e. a network
route to the source is present.

[[polltarget]]*polltarget* _address_ _polltarget_::
The *polltarget* command is used to modify the poll target for one of the
current set of sources. It is equivalent to the *polltarget* option in the
<<chrony.conf.adoc#server,*server*>> directive in the configuration file.

[[refresh]]*refresh*::
The *refresh* command can be used to force *chronyd* to resolve the names of
configured NTP sources to IP addresses again and replace any addresses missing
in the list of resolved addresses.
+
Sources that stop responding are replaced with newly resolved addresses
automatically after 8 polling intervals. This command can be used to replace
them immediately, e.g. after suspending and resuming the machine in a different
network.
+
Note that with pools which have more than 16 addresses, or not all IPv4 or IPv6
addresses are included in a single DNS response (e.g. pool.ntp.org), this
command might replace the addresses even if they are still in the pool.

[[reload]]*reload* *sources*::
The *reload sources* command causes *chronyd* to re-read all _*.sources_ files
from the directories specified by the
<<chrony.conf.adoc#sourcedir,*sourcedir*>> directive.
+
Note that modified sources (e.g. specified with a new option) are not modified
in memory. They are removed and added again, which causes them to lose old
measurements and reset the selection state.

[[sourcename]]*sourcename* _address_::
The *sourcename* command prints the original hostname or address that was
specified for an NTP source in the configuration file, or the *add* command.
This command is an alternative to the *-N* option, which can be useful in
scripts.
+
Note that different NTP sources can share the same name, e.g. servers from a
pool.

=== Manual time input

[[manual]]
*manual* *on*::
*manual* *off*::
*manual* *delete* _index_::
*manual* *list*::
*manual* *reset*::
The manual command enables and disables use of the <<settime,*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:
+
. The sample index (used for the *manual delete* command).
. The date and time of the sample.
. The system clock error when the timestamp was entered, adjusted to allow
  for changes made to the system clock since.
. The system clock error when the timestamp was entered, as it originally was
  (without allowing for changes to the system clock since).
. The regression residual at this point, in seconds. This allows '`outliers`'
  to be easily spotted, so that they can be deleted using the *manual delete*
  command.
{blank}::
+
The *delete* form of the command deletes a single sample. The parameter is the
index of the sample, as shown in the first column of the output from *manual
list*. Following deletion of the data point, the current error and drift rate
are re-estimated from the remaining data points and the system clock trimmed if
necessary. This option is intended to allow '`outliers`' to be discarded, i.e.
samples where the administrator realises they have entered a very poor
timestamp.
+
The *reset* form of the command deletes all samples at once. The system clock
is left running as it was before the command was entered.

[[settime]]*settime* _time_::
The *settime* command allows the current time to be entered manually, if this
option has been configured into *chronyd*. (It can be configured either with
the <<chrony.conf.adoc#manual,*manual*>> directive in the configuration file,
or with the <<manual,*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,*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]]*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 ntp1.example.net
accheck 1.2.3.4
accheck 2001:db8::1
----
+
This command can be used to examine the effect of a series of *allow*, *allow
all*, *deny*, and *deny all* commands specified either via *chronyc*, or in
*chronyd*'s configuration file.

[[clients]]*clients* [*-p* _packets_] [*-k*] [*-r*]::
This command shows a list of clients that have accessed the server, through
the NTP, command, or NTS-KE port. It does not include accesses over the Unix
domain command socket.
+
The *-p* option specifies the minimum number of received NTP or command
packets, or accepted NTS-KE connections, needed to include a client in the
list. The default value is 0, i.e. all clients are reported. With the *-k*
option the last four columns will show the NTS-KE accesses instead of command
accesses. If the *-r* option is specified, *chronyd* will reset the counters of
received and dropped packets or connections after reporting the current values.
+
An example of the output is:
+
----
Hostname                      NTP   Drop Int IntL Last     Cmd   Drop Int  Last
===============================================================================
localhost                       2      0   2   -   133      15      0  -1     7
ntp1.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,*allow*>>, <<deny,*deny*>>,
<<cmdallow,*cmdallow*>> and <<cmddeny,*cmddeny*>> commands or configuration
file directives) are logged. The intervals are displayed as a power of 2 in
seconds.
+
The columns are as follows:
+
. The hostname of the client.
. The number of NTP packets received from the client.
. The number of NTP packets dropped to limit the response rate.
. The average interval between NTP packets.
. The average interval between NTP packets after limiting the response rate.
. Time since the last NTP packet was received
. The number of command packets or NTS-KE connections received/accepted from
  the client.
. The number of command packets or NTS-KE connections dropped to limit the
  response rate.
. The average interval between command packets or NTS-KE connections.
. Time since the last command packet or NTS-KE connection was
  received/accepted.

[[serverstats]]*serverstats*::
The *serverstats* command displays NTP and command server statistics.
+
An example of the output is shown below.
+
----
NTP packets received       : 1598
NTP packets dropped        : 8
Command packets received   : 19
Command packets dropped    : 0
Client log records dropped : 0
NTS-KE connections accepted: 3
NTS-KE connections dropped : 0
Authenticated NTP packets  : 189
Interleaved NTP packets    : 43
NTP timestamps held        : 44
NTP timestamp span         : 120
NTP daemon RX timestamps   : 0
NTP daemon TX timestamps   : 1537
NTP kernel RX timestamps   : 1590
NTP kernel TX timestamps   : 43
NTP hardware RX timestamps : 0
NTP hardware TX timestamps : 0
----
+
The fields have the following meaning:
+
*NTP packets received*:::
The number of valid NTP requests received by the server.
*NTP packets dropped*:::
The number of NTP requests dropped by the server due to rate limiting
(configured by the <<chrony.conf.adoc#ratelimit,*ratelimit*>> directive).
*Command packets received*:::
The number of command requests received by the server.
*Command packets dropped*:::
The number of command requests dropped by the server due to rate limiting
(configured by the <<chrony.conf.adoc#cmdratelimit,*cmdratelimit*>> directive).
*Client log records dropped*:::
The number of client log records dropped by the server to limit the memory use
(configured by the <<chrony.conf.adoc#clientloglimit,*clientloglimit*>>
directive).
*NTS-KE connections accepted*:::
The number of NTS-KE connections accepted by the server.
*NTS-KE connections dropped*:::
The number of NTS-KE connections dropped by the server due to rate limiting
(configured by the <<chrony.conf.adoc#ntsratelimit,*ntsratelimit*>> directive).
*Authenticated NTP packets*:::
The number of received NTP requests that were authenticated (with a symmetric
key or NTS).
*Interleaved NTP packets*:::
The number of received NTP requests that were detected to be in the interleaved
mode.
*NTP timestamps held*:::
The number of pairs of receive and transmit timestamps that the server is
currently holding in memory for clients using the interleaved mode.
*NTP timestamp span*:::
The interval (in seconds) covered by the currently held NTP timestamps.
*NTP daemon RX timestamps*:::
The number of NTP responses which included a receive timestamp captured by the
daemon.
*NTP daemon TX timestamps*:::
The number of NTP responses which included a transmit timestamp captured by the
daemon.
*NTP kernel RX timestamps*:::
The number of NTP responses which included a receive timestamp captured by the
kernel.
*NTP kernel TX timestamps*:::
The number of NTP responses (in the interleaved mode) which included a transmit
timestamp captured by the kernel.
*NTP hardware RX timestamps*:::
The number of NTP responses which included a receive timestamp captured by the
NIC.
*NTP hardware TX timestamps*:::
The number of NTP responses (in the interleaved mode) which included a transmit
timestamp captured by the NIC.

[[allow]]*allow* [*all*] [_subnet_]::
The effect of the allow command is identical to the
<<chrony.conf.adoc#allow,*allow*>> directive in the configuration file.
+
The syntax is illustrated in the following examples:
+
----
allow 1.2.3.4
allow all 3.4.5.0/24
allow 2001:db8:789a::/48
allow 0/0
allow ::/0
allow
allow all
----

[[deny]]*deny* [*all*] [_subnet_]::
The effect of the allow command is identical to the
<<chrony.conf.adoc#deny,*deny*>> directive in the configuration file.
+
The syntax is illustrated in the following examples:
+
----
deny 1.2.3.4
deny all 3.4.5.0/24
deny 2001:db8:789a::/48
deny 0/0
deny ::/0
deny
deny all
----

[[local]]
*local* [_option_]...::
*local* *off*::
The *local* command allows *chronyd* to be told that it is to appear as a
reference source, even if it is not itself properly synchronised to an external
source. This can be used on isolated networks, to allow a computer to be the
primary time server for other computers.
+
The first form enables the local reference mode on the host. The syntax is
identical to the <<chrony.conf.adoc#local,*local*>> directive in the
configuration file.
+
The second form disables the local reference mode.

[[smoothing]]*smoothing*::
The *smoothing* command displays the current state of the NTP server time
smoothing, which can be enabled with the
<<chrony.conf.adoc#smoothtime,*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]]
*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
<<chrony.conf.adoc#smoothtime,*smoothtime*>> directive.

=== Monitoring access

[[cmdaccheck]]*cmdaccheck* _address_::
This command is similar to the <<accheck,*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 ntp1.example.net
cmdaccheck 1.2.3.4
cmdaccheck 2001:db8::1
----

[[cmdallow]]*cmdallow* [*all*] [_subnet_]::
This is similar to the <<allow,*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]]*cmddeny* [*all*] [_subnet_]::
This is similar to the <<deny,*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]]*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,*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]]*trimrtc*::
The *trimrtc* command is used to correct the system's real-time clock (RTC) to
the main system clock. It has no effect if the error between the two clocks is
currently estimated at less than a second.
+
The command takes no arguments. It performs the following steps (if the RTC is
more than 1 second away from the system clock):
+
. Remember the currently estimated gain or loss rate of the RTC and flush the
  previous measurements.
. Step the real-time clock to bring it within a second of the system clock.
. Make several measurements to accurately determine the new offset between
  the RTC and the system clock (i.e. the remaining fraction of a second
  error).
. Save the RTC parameters to the RTC file (specified with the
  <<chrony.conf.adoc#rtcfile,*rtcfile*>> directive in the configuration file).
{blank}::
+
The last step is done as a precaution against the computer suffering a power
failure before either the daemon exits or the <<writertc,*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
<<chrony.conf.adoc#rtcautotrim,*rtcautotrim*>> directive in the configuration
file.

[[writertc]]*writertc*::
The *writertc* command writes the currently estimated error and gain or loss rate
parameters for the RTC to the RTC file (specified with the
<<chrony.conf.adoc#rtcfile,*rtcfile*>> directive). This information is also
written automatically when *chronyd* is killed (by the SIGHUP, SIGINT, SIGQUIT
or SIGTERM signals) or when the <<trimrtc,*trimrtc*>> command is issued.

=== Other daemon commands

[[cyclelogs]]*cyclelogs*::
The *cyclelogs* command causes all of *chronyd*'s open log files to be closed
and re-opened. This allows them to be renamed so that they can be periodically
purged. An example of how to do this is shown below.
+
----
# mv /var/log/chrony/measurements.log /var/log/chrony/measurements1.log
# chronyc cyclelogs
# rm /var/log/chrony/measurements1.log
----

[[dump]]*dump*::
The *dump* command causes *chronyd* to write its current history of
measurements for each of its sources to dump files in the directory specified
in the configuration file by the <<chrony.conf.adoc#dumpdir,*dumpdir*>>
directive and also write server NTS keys and client NTS cookies to the
directory specified by the <<chrony.conf.adoc#ntsdumpdir1,*ntsdumpdir*>>
directive. Note that *chronyd* does this automatically when it exits. This
command is mainly useful for inspection whilst *chronyd* is running.

[[rekey]]*rekey*::
The *rekey* command causes *chronyd* to re-read the key file specified in the
configuration file by the <<chrony.conf.adoc#keyfile,*keyfile*>> directive. It
also re-reads the server NTS keys if
<<chrony.conf.adoc#ntsdumpdir2,*ntsdumpdir*>> is specified and
<<chrony.conf.adoc#ntsrotate,automatic rotation>> is disabled in the
configuration file.

[[reset]]*reset* *sources*::
The *reset sources* command causes *chronyd* to drop all measurements and
switch to the unsynchronised state. This command can help *chronyd* with
recovery when the measurements are known to be no longer valid or accurate,
e.g. due to moving the computer to a different network, or resuming the
computer from a low-power state (which resets the system clock). *chronyd* will
drop the measurements automatically when it detects the clock has made an
unexpected jump, but the detection is not completely reliable.

[[shutdown]]*shutdown*::
The *shutdown* command causes *chronyd* to exit. This is equivalent to sending
the process the SIGTERM signal.

=== Client commands

[[dns]]*dns* _option_::
The *dns* command configures how hostnames and IP addresses are resolved in
*chronyc*. IP addresses can be resolved to hostnames when printing results of
<<sources,*sources*>>, <<sourcestats,*sourcestats*>>, <<tracking,*tracking*>>
and <<clients,*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* _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,*retries*>> command.
+
By default, the timeout is 1000 milliseconds.

[[retries]]*retries* _retries_::
The *retries* command sets the maximum number of retries for *chronyc* requests
before giving up. The response timeout is controlled by the
<<timeout,*timeout*>> command.
+
The default is 2.

[[keygen]]*keygen* [_id_ [_type_ [_bits_]]]::
The *keygen* command generates a key that can be added to the
key file (specified with the <<chrony.conf.adoc#keyfile,*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 name
of the hash function or cipher (by default SHA1, or MD5 if SHA1 is not
available). The third argument is the length of the key in bits if a hash
function was selected, between 80 and 4096 bits (by default 160 bits).
+
An example is:
+
----
keygen 73 SHA1 256
----
+
which generates a 256-bit SHA1 key with number 73. The printed line should
then be securely transferred and added to the key files on both server and
client, or peers. A different key should be generated for each client or peer.
+
An example using the AES128 cipher is:
+
----
keygen 151 AES128
----

[[exit]]*exit*::
[[quit]]*quit*::
The *exit* and *quit* commands exit from *chronyc* and return the user to the shell.

[[help]]*help*::
The *help* command displays a summary of the commands and their arguments.

== SEE ALSO

<<chrony.conf.adoc#,*chrony.conf(5)*>>, <<chronyd.adoc#,*chronyd(8)*>>

== BUGS

For instructions on how to report bugs, please visit
https://chrony-project.org/.

== AUTHORS

chrony was written by Richard Curnow, Miroslav Lichvar, and others.