diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/chrony.conf.adoc | 76 | ||||
| -rw-r--r-- | doc/chrony.conf.man.in | 93 | ||||
| -rw-r--r-- | doc/chronyc.adoc | 27 | ||||
| -rw-r--r-- | doc/chronyc.man.in | 47 | ||||
| -rw-r--r-- | doc/chronyd.man.in | 4 | ||||
| -rw-r--r-- | doc/contributing.adoc | 74 | ||||
| -rw-r--r-- | doc/faq.adoc | 60 |
7 files changed, 346 insertions, 35 deletions
diff --git a/doc/chrony.conf.adoc b/doc/chrony.conf.adoc index cb3f95c..2c993db 100644 --- a/doc/chrony.conf.adoc +++ b/doc/chrony.conf.adoc @@ -3,7 +3,7 @@ // Copyright (C) Richard P. Curnow 1997-2003 // Copyright (C) Stephen Wadeley 2016 // Copyright (C) Bryan Christianson 2017 -// Copyright (C) Miroslav Lichvar 2009-2023 +// Copyright (C) Miroslav Lichvar 2009-2024 // // 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 @@ -126,6 +126,15 @@ mechanism. Unlike with the *key* option, the server and client do not need to share a key in a key file. NTS has a Key Establishment (NTS-KE) protocol using the Transport Layer Security (TLS) protocol to get the keys and cookies required by NTS for authentication of NTP packets. ++ +With this option, the hostname specified in the server or pool directive is the +NTS-KE server or pool of NTS-KE servers respectively. The NTP server usually +runs on the same host, but it can be separated from the NTS-KE server (the +hostname or address of the NTP server is provided to the client by the NTS-KE +server). ++ +The NTS-KE server can be specified by IP address if it is included in the +server's certificate as a Subject Alternative Name (SAN). *certset* _ID_::: This option specifies which set of trusted certificates should be used to verify the server's certificate when the *nts* option is enabled. Sets of certificates @@ -220,7 +229,7 @@ when disconnecting the network link. (It will still be necessary to use the <<chronyc.adoc#online,*online*>> command when the link has been established, to enable measurements to start.) *prefer*::: -Prefer this source over sources without the *prefer* option. +Prefer this source over other selectable sources without the *prefer* option. *noselect*::: Never select this source. This is particularly useful for monitoring. *trust*::: @@ -343,6 +352,12 @@ the PTP port. The corrections are applied only to NTP measurements with HW timestamps (enabled by the <<hwtimestamp,*hwtimestamp*>> directive). This field should be enabled only for servers known to be running *chronyd* version 4.5 or later. +*ipv4*::: +*ipv6*::: +These options force *chronyd* to use only IPv4 or IPv6 addresses respectively +for this source. They do not override the *-4* or *-6* option on the *chronyd* +command line. + {blank}::: [[pool]]*pool* _name_ [_option_]...:: @@ -655,7 +670,7 @@ default is 64. With drivers that perform their own polling (PPS, PHC, SHM), the maximum value is adjusted to the number of driver polls per source poll, i.e. 2^(_poll_ - _dpoll_). *prefer*::: -Prefer this source over sources without the prefer option. +Prefer this source over other selectable sources without the *prefer* option. *noselect*::: Never select this source. This is useful for monitoring or with sources which are not very accurate, but are locked with a PPS refclock. @@ -674,9 +689,10 @@ trusted and required source. *tai*::: This option indicates that the reference clock keeps time in TAI instead of UTC and that *chronyd* should correct its offset by the current TAI-UTC offset. The -<<leapsectz,*leapsectz*>> directive must be used with this option and the -database must be kept up to date in order for this correction to work as -expected. This option does not make sense with PPS refclocks. +<<leapsectz,*leapsectz*>> or <<leapseclist,*leapseclist*>> directive must be +used with this option and the database must be kept up to date in order for +this correction to work as expected. This option does not make sense with PPS +refclocks. *local*::: This option specifies that the reference clock is an unsynchronised clock which is more stable than the system clock (e.g. TCXO, OCXO, or atomic clock) and @@ -1263,6 +1279,19 @@ $ TZ=right/UTC date -d 'Dec 31 2008 23:59:60' Wed Dec 31 23:59:60 UTC 2008 ---- +[[leapseclist]]*leapseclist* _file_:: +This directive specifies the path to a file containing a list of leap seconds +and TAI-UTC offsets in NIST/IERS format. It is recommended to use +the file _leap-seconds.list_ usually included with the system timezone +database. The behaviour of this directive is otherwise equivalent to +<<leapsectz,*leapsectz*>>. ++ +An example of this directive is: ++ +---- +leapseclist /usr/share/zoneinfo/leap-seconds.list +---- + [[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, @@ -1655,6 +1684,14 @@ The current root distance can be calculated from root delay and root dispersion ---- distance = delay / 2 + dispersion ---- +*activate* _distance_::: +This option sets an activating root distance for the local reference. The +local reference will not be used until the root distance drops below the +configured value for the first time. This can be used to prevent the local +reference from being activated on a server which has never been synchronised +with an upstream server. The default value of 0.0 causes no activating +distance to be used, such that the local reference is always eligible for +activation. *orphan*::: This option enables a special '`orphan`' mode, where sources with stratum equal to the local _stratum_ are assumed to not serve real time. They are ignored @@ -1677,7 +1714,7 @@ The *orphan* mode is compatible with the *ntpd*'s orphan mode (enabled by the An example of the directive is: + ---- -local stratum 10 orphan distance 0.1 +local stratum 10 orphan distance 0.1 activate 0.5 ---- [[ntpsigndsocket]]*ntpsigndsocket* _directory_:: @@ -1841,6 +1878,14 @@ source address from completely blocking responses to that address. The leak rate is defined as a power of 1/2 and it is 2 by default, i.e. on average at least every fourth request has a response. The minimum value is 1 and the maximum value is 4. +*kod* _rate_::: +This option sets the rate at which Kiss-o'-Death (KoD) RATE responses are +randomly sent when the limits specified by the *interval* and *burst* options +are exceeded. It is an additional stream of responses to the *leak* option. A +KoD RATE response is a request for the client to reduce its polling rate. Few +implementations actually support it. The rate is defined as a power of 1/2. The +default value is 0, which means disabled. The minimum value is 0 and the +maximum value is 4. {blank}:: + An example use of the directive is: @@ -1856,7 +1901,7 @@ packets, by up to 75% (with default *leak* of 2). [[ntsratelimit]]*ntsratelimit* [_option_]...:: This directive enables rate limiting of NTS-KE requests. It is similar to the <<ratelimit,*ratelimit*>> directive, except the default interval is 6 -(1 connection per 64 seconds). +(1 connection per 64 seconds) and the *kod* option is not supported. + An example of the use of the directive is: + @@ -2004,8 +2049,8 @@ need to be run with the *-p 257* option to inter-operate correctly.) [[cmdratelimit]]*cmdratelimit* [_option_]...:: This directive enables response rate limiting for command packets. It is similar to the <<ratelimit,*ratelimit*>> directive, except responses to -localhost are never limited and the default interval is -4 (16 packets per -second). +localhost are never limited, the default interval is -4 (16 packets per +second), and the *kod* option is not supported. + An example of the use of the directive is: + @@ -2143,8 +2188,8 @@ from the example line above): . Results of the *maxdelay*, *maxdelayratio*, and *maxdelaydevratio* (or *maxdelayquant*) tests, and a test for synchronisation loop (1=pass, 0=fail). The first test from these four also checks the server precision, - response time, and whether an interleaved response is acceptable for - synchronisation. [1111] + response time, validity of the measured offset, and whether an interleaved + response is acceptable for synchronisation. [1111] . Local poll [10] . Remote poll [10] . '`Score`' (an internal score within each polling level used to decide when to @@ -2736,6 +2781,8 @@ e.g.: ---- pidfile /run/chronyd.pid ---- ++ +Setting this directive to _/_ disables writing and checking of the PID file. [[ptpport]]*ptpport* _port_:: The *ptpport* directive enables *chronyd* to send and receive NTP messages @@ -2766,6 +2813,11 @@ hwtimestamp * rxfilter ptp ptpport 319 ---- +[[ptpdomain]]*ptpdomain* _domain_:: +The *ptpdomain* directive sets the PTP domain number of transmitted and +accepted NTP-over-PTP messages. Messages from other domains are ignored. +The default is 123, the minimum is 0, and the maximum is 255. + [[sched_priority]]*sched_priority* _priority_:: On Linux, FreeBSD, NetBSD, and illumos, the *sched_priority* directive will select the SCHED_FIFO real-time scheduler at the specified priority (which must diff --git a/doc/chrony.conf.man.in b/doc/chrony.conf.man.in index 66d2358..8b04427 100644 --- a/doc/chrony.conf.man.in +++ b/doc/chrony.conf.man.in @@ -2,12 +2,12 @@ .\" Title: chrony.conf .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.20 -.\" Date: 2023-12-05 +.\" Date: 2024-08-29 .\" Manual: Configuration Files .\" Source: chrony @CHRONY_VERSION@ .\" Language: English .\" -.TH "CHRONY.CONF" "5" "2023-12-05" "chrony @CHRONY_VERSION@" "Configuration Files" +.TH "CHRONY.CONF" "5" "2024-08-29" "chrony @CHRONY_VERSION@" "Configuration Files" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -144,6 +144,15 @@ mechanism. Unlike with the \fBkey\fP option, the server and client do not need t share a key in a key file. NTS has a Key Establishment (NTS\-KE) protocol using the Transport Layer Security (TLS) protocol to get the keys and cookies required by NTS for authentication of NTP packets. +.sp +With this option, the hostname specified in the server or pool directive is the +NTS\-KE server or pool of NTS\-KE servers respectively. The NTP server usually +runs on the same host, but it can be separated from the NTS\-KE server (the +hostname or address of the NTP server is provided to the client by the NTS\-KE +server). +.sp +The NTS\-KE server can be specified by IP address if it is included in the +server\(cqs certificate as a Subject Alternative Name (SAN). .RE .sp \fBcertset\fP \fIID\fP @@ -280,7 +289,7 @@ enable measurements to start.) .sp \fBprefer\fP .RS 4 -Prefer this source over sources without the \fBprefer\fP option. +Prefer this source over other selectable sources without the \fBprefer\fP option. .RE .sp \fBnoselect\fP @@ -450,6 +459,13 @@ field should be enabled only for servers known to be running \fBchronyd\fP versi .RE .RE .sp +\fBipv4\fP, \fBipv6\fP +.RS 4 +These options force \fBchronyd\fP to use only IPv4 or IPv6 addresses respectively +for this source. They do not override the \fB\-4\fP or \fB\-6\fP option on the \fBchronyd\fP +command line. +.RE +.sp .RS 4 .RE @@ -877,7 +893,7 @@ maximum value is adjusted to the number of driver polls per source poll, i.e. .sp \fBprefer\fP .RS 4 -Prefer this source over sources without the prefer option. +Prefer this source over other selectable sources without the \fBprefer\fP option. .RE .sp \fBnoselect\fP @@ -908,9 +924,10 @@ trusted and required source. .RS 4 This option indicates that the reference clock keeps time in TAI instead of UTC and that \fBchronyd\fP should correct its offset by the current TAI\-UTC offset. The -\fBleapsectz\fP directive must be used with this option and the -database must be kept up to date in order for this correction to work as -expected. This option does not make sense with PPS refclocks. +\fBleapsectz\fP or \fBleapseclist\fP directive must be +used with this option and the database must be kept up to date in order for +this correction to work as expected. This option does not make sense with PPS +refclocks. .RE .sp \fBlocal\fP @@ -1652,6 +1669,25 @@ Wed Dec 31 23:59:60 UTC 2008 .if n .RE .RE .sp +\fBleapseclist\fP \fIfile\fP +.RS 4 +This directive specifies the path to a file containing a list of leap seconds +and TAI\-UTC offsets in NIST/IERS format. It is recommended to use +the file \fIleap\-seconds.list\fP usually included with the system timezone +database. The behaviour of this directive is otherwise equivalent to +\fBleapsectz\fP. +.sp +An example of this directive is: +.sp +.if n .RS 4 +.nf +.fam C +leapseclist /usr/share/zoneinfo/leap\-seconds.list +.fam +.fi +.if n .RE +.RE +.sp \fBmakestep\fP \fIthreshold\fP \fIlimit\fP .RS 4 Normally \fBchronyd\fP will cause the system to gradually correct any time offset, @@ -2132,6 +2168,17 @@ distance = delay / 2 + dispersion .if n .RE .RE .sp +\fBactivate\fP \fIdistance\fP +.RS 4 +This option sets an activating root distance for the local reference. The +local reference will not be used until the root distance drops below the +configured value for the first time. This can be used to prevent the local +reference from being activated on a server which has never been synchronised +with an upstream server. The default value of 0.0 causes no activating +distance to be used, such that the local reference is always eligible for +activation. +.RE +.sp \fBorphan\fP .RS 4 This option enables a special \(oqorphan\(cq mode, where sources with stratum equal @@ -2161,7 +2208,7 @@ An example of the directive is: .if n .RS 4 .nf .fam C -local stratum 10 orphan distance 0.1 +local stratum 10 orphan distance 0.1 activate 0.5 .fam .fi .if n .RE @@ -2369,6 +2416,17 @@ rate is defined as a power of 1/2 and it is 2 by default, i.e. on average at least every fourth request has a response. The minimum value is 1 and the maximum value is 4. .RE +.sp +\fBkod\fP \fIrate\fP +.RS 4 +This option sets the rate at which Kiss\-o\*(Aq\-Death (KoD) RATE responses are +randomly sent when the limits specified by the \fBinterval\fP and \fBburst\fP options +are exceeded. It is an additional stream of responses to the \fBleak\fP option. A +KoD RATE response is a request for the client to reduce its polling rate. Few +implementations actually support it. The rate is defined as a power of 1/2. The +default value is 0, which means disabled. The minimum value is 0 and the +maximum value is 4. +.RE .RE .sp @@ -2393,7 +2451,7 @@ packets, by up to 75% (with default \fBleak\fP of 2). .RS 4 This directive enables rate limiting of NTS\-KE requests. It is similar to the \fBratelimit\fP directive, except the default interval is 6 -(1 connection per 64 seconds). +(1 connection per 64 seconds) and the \fBkod\fP option is not supported. .sp An example of the use of the directive is: .sp @@ -2582,8 +2640,8 @@ need to be run with the \fB\-p 257\fP option to inter\-operate correctly.) .RS 4 This directive enables response rate limiting for command packets. It is similar to the \fBratelimit\fP directive, except responses to -localhost are never limited and the default interval is \-4 (16 packets per -second). +localhost are never limited, the default interval is \-4 (16 packets per +second), and the \fBkod\fP option is not supported. .sp An example of the use of the directive is: .sp @@ -2861,8 +2919,8 @@ RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111] Results of the \fBmaxdelay\fP, \fBmaxdelayratio\fP, and \fBmaxdelaydevratio\fP (or \fBmaxdelayquant\fP) tests, and a test for synchronisation loop (1=pass, 0=fail). The first test from these four also checks the server precision, -response time, and whether an interleaved response is acceptable for -synchronisation. [1111] +response time, validity of the measured offset, and whether an interleaved +response is acceptable for synchronisation. [1111] .RE .sp .RS 4 @@ -4520,6 +4578,8 @@ pidfile /run/chronyd.pid .fam .fi .if n .RE +.sp +Setting this directive to \fI/\fP disables writing and checking of the PID file. .RE .sp \fBptpport\fP \fIport\fP @@ -4557,6 +4617,13 @@ ptpport 319 .if n .RE .RE .sp +\fBptpdomain\fP \fIdomain\fP +.RS 4 +The \fBptpdomain\fP directive sets the PTP domain number of transmitted and +accepted NTP\-over\-PTP messages. Messages from other domains are ignored. +The default is 123, the minimum is 0, and the maximum is 255. +.RE +.sp \fBsched_priority\fP \fIpriority\fP .RS 4 On Linux, FreeBSD, NetBSD, and illumos, the \fBsched_priority\fP directive will diff --git a/doc/chronyc.adoc b/doc/chronyc.adoc index 96a0551..1a843c3 100644 --- a/doc/chronyc.adoc +++ b/doc/chronyc.adoc @@ -459,8 +459,8 @@ states are reported. The following states indicate the source is not considered selectable for synchronisation: * _N_ - has the *noselect* option. -* _s_ - is not synchronised. * _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 @@ -492,7 +492,7 @@ local clock: 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 indicites whether an authentication mechanism is enabled for the +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. @@ -556,6 +556,13 @@ 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*:: @@ -689,6 +696,10 @@ 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: @@ -746,6 +757,18 @@ 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 diff --git a/doc/chronyc.man.in b/doc/chronyc.man.in index 4541fc6..3e52218 100644 --- a/doc/chronyc.man.in +++ b/doc/chronyc.man.in @@ -2,12 +2,12 @@ .\" Title: chronyc .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.20 -.\" Date: 2023-12-05 +.\" Date: 2024-08-29 .\" Manual: User manual .\" Source: chrony @CHRONY_VERSION@ .\" Language: English .\" -.TH "CHRONYC" "1" "2023-12-05" "chrony @CHRONY_VERSION@" "User manual" +.TH "CHRONYC" "1" "2024-08-29" "chrony @CHRONY_VERSION@" "User manual" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -695,7 +695,7 @@ synchronisation: . sp -1 . IP \(bu 2.3 .\} -\fIs\fP \- is not synchronised. +\fIM\fP \- does not have enough measurements. .RE .sp .RS 4 @@ -706,7 +706,7 @@ synchronisation: . sp -1 . IP \(bu 2.3 .\} -\fIM\fP \- does not have enough measurements. +\fIs\fP \- is not synchronised. .RE .sp .RS 4 @@ -881,7 +881,7 @@ or the reference ID if it is a reference clock. .sp \fBAuth\fP .RS 4 -This column indicites whether an authentication mechanism is enabled for the +This column indicates whether an authentication mechanism is enabled for the source. \fIY\fP means yes and \fIN\fP means no. .RE .sp @@ -1054,6 +1054,15 @@ The \fBreselectdist\fP command sets the reselection distance. It is equivalent t the \fBreselectdist\fP directive in the configuration file. .RE +.sp +\fBoffset\fP \fIaddress|refid\fP \fIoffset\fP +.RS 4 +The \fBoffset\fP command modifies the offset correction of an NTP source specified +by IP address (or the \fIID#XXXXXXXXXX\fP identifier used for unknown addresses), +or a reference clock specified by reference ID as a string. It is equivalent to +the \fBoffset\fP option in the \fBserver\fP or +\fBrefclock\fP directive respectively. +.RE .SS "NTP sources" .sp \fBactivity\fP @@ -1391,6 +1400,10 @@ 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 .fam .fi .if n .RE @@ -1486,6 +1499,30 @@ The number of packets which passed the first two groups of NTP tests. The number of packets which passed all three groups of NTP tests, i.e. the NTP measurement was accepted. .RE +.sp +\fBTotal kernel TX\fP +.RS 4 +The number of packets sent to the source for which a timestamp was captured by +the kernel. +.RE +.sp +\fBTotal kernel RX\fP +.RS 4 +The number of packets received from the source for which a timestamp was +captured by the kernel. +.RE +.sp +\fBTotal HW TX\fP +.RS 4 +The number of packets sent to the source for which a timestamp was captured by +the NIC. +.RE +.sp +\fBTotal HW RX\fP +.RS 4 +The number of packets received from the source for which a timestamp was +captured by the NIC. +.RE .RE .sp \fBadd peer\fP \fIname\fP [\fIoption\fP]... diff --git a/doc/chronyd.man.in b/doc/chronyd.man.in index 96e87a0..35d6819 100644 --- a/doc/chronyd.man.in +++ b/doc/chronyd.man.in @@ -2,12 +2,12 @@ .\" Title: chronyd .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.20 -.\" Date: 2023-12-05 +.\" Date: 2024-08-29 .\" Manual: System Administration .\" Source: chrony @CHRONY_VERSION@ .\" Language: English .\" -.TH "CHRONYD" "8" "2023-12-05" "chrony @CHRONY_VERSION@" "System Administration" +.TH "CHRONYD" "8" "2024-08-29" "chrony @CHRONY_VERSION@" "System Administration" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 diff --git a/doc/contributing.adoc b/doc/contributing.adoc new file mode 100644 index 0000000..7804e26 --- /dev/null +++ b/doc/contributing.adoc @@ -0,0 +1,74 @@ +// This file is part of chrony +// +// Copyright (C) Miroslav Lichvar 2024 +// +// 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. + += Contributing + +== Patches + +The source code of `chrony` is maintained in a git repository at +https://gitlab.com/chrony/chrony. Patches can be submitted to the `chrony-dev` +mailing list, or as a merge request on gitlab. Before spending a lot of time +implementing a new major feature, it is recommended to ask on the mailing list +for comments about its design and whether such feature fits the goals of the +project. + +Each commit should be a self-contained logical change, which does not break +the build or tests. New functionality and fixed bugs should be covered by a new +test or an extended existing test in the test suite. The test can be included +in the same commit or added as a separate commit. The same rule applies to +documentation. All command-line options, configuration directives, and +`chronyc` commands should be documented. + +The most important tests can be executed by running `make check` or `make +quickcheck`. The unit and system tests run on all supported systems. The system +tests require root privileges. The simulation tests run only on Linux and +require https://gitlab.com/chrony/clknetsim[clknetsim] to be compiled in the +directory containing the tests, but they are executed with a merge request on +gitlab. + +The commit message should explain any non-trivial changes, e.g. what problem is +the commit solving and how. The commit subject (first line of the message) +should be written in an imperative form, prefixed with the component name if it +is not a more general change, starting in lower case, and no period at the end. +See the git log for examples. + +Simpler code is better. Less code is better. Security is a top priority. + +Assertions should catch only bugs in the `chrony` code. Unexpected values in +external input (e.g. anything received from network) must be handled correctly +without crashing and memory corruption. Fuzzing support is available at +https://gitlab.com/chrony/chrony-fuzz. The fuzzing coverage is checked by the +project maintainer before each release. + +The code should mostly be self-documenting. Comments should explain the +less obvious things. + +== Coding style + +The code uses two spaces for indentation. No tabs. The line length should +normally not exceed 95 characters. Too much indentation indicates the code will +not be very readable. + +Function names are in an imperative form. Names of static functions use +lowercase characters and underscores. Public functions, structures, typedefs +are in CamelCase with a prefix specific to the module (e.g. LCL - local, NCR +- NTP core, NKS - NTS-KE server, SST - sourcestats). + +Function names are not followed by space, but keywords of the language (e.g. +`if`, `for`, `while`, `sizeof`) are followed by space. + +Have a look at the existing code to get a better idea what is expected. diff --git a/doc/faq.adoc b/doc/faq.adoc index 8fd350f..fa1b6ad 100644 --- a/doc/faq.adoc +++ b/doc/faq.adoc @@ -2,7 +2,7 @@ // // Copyright (C) Richard P. Curnow 1997-2003 // Copyright (C) Luke Valenta 2023 -// Copyright (C) Miroslav Lichvar 2014-2016, 2020-2023 +// Copyright (C) Miroslav Lichvar 2014-2016, 2020-2024 // // 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 @@ -772,6 +772,17 @@ print all sources, even those that do not have a known address yet, with their names as they were specified in the configuration. This can be useful to verify that the names specified in the configuration are used as expected. +When DNSSEC is enabled, it will not work until the time is synchronized, as it +requires validating a signature timestamp and its expiration date, so if the +system time is too far in the future or the past DNSSEC validation will fail and +`chronyd` will be unable to resolve the address of the NTP server. In such cases, +if hostnames are the only options and bare IP addresses cannot be used, DNSSEC +can be disabled for `chronyd` using resolver-specific mechanisms, if available, +although of course that means losing the protection afforded by DNSSEC. +For example, when using systemd-resolved, the `SYSTEMD_NSS_RESOLVE_VALIDATE=0` +environment variable can be set, for example in the `chronyd` systemd unit via +`Environment=SYSTEMD_NSS_RESOLVE_VALIDATE=0`. + === Is `chronyd` allowed to step the system clock? By default, `chronyd` adjusts the clock gradually by slowing it down or @@ -1155,6 +1166,53 @@ There are several different clocks used by `chronyd`: synchronised by `chronyd`. Its offset is tracked relative to the NTP clock in order to convert the hardware timestamps. +=== How accurate is my system clock? + +`chronyd` does not know how accurate really is the clock it is synchronizing. +Even if the measured offset of the clock is stable to nanoseconds, it could be +off by milliseconds due to asymmetric network delay, e.g. caused by asymmetric +routing or queuing delays in network switches. NTP provides root delay and root +dispersion to enable clients to estimate the maximum error of their clock. + +Root delay measures the sum of round-trip times between all NTP servers on the +path from the client to the primary time source (e.g. a GPS receiver). Half of +the root delay is the maximum error due to asymmetric delays, assuming one +direction (e.g. from the client to the server) has a zero delay and the other +direction (from the server to the client) takes all of the measured delay. The +root delay also covers timestamping errors if the server implementation and +hardware meet the NTP requirement for transmit timestamps to never be late and +receive timestamps to never be early. + +If you have additional information about the hardware and network between the +client and primary time source, you could modify the root delay to get a better +estimate of the maximum error. For example, from the physical distance of the +server and signal propagation speed in the cables a minimum symmetric +round-trip delay can be calculated and subtracted from the root delay measured +by NTP. + +Root dispersion estimates errors due to instability of clocks and NTP +measurements. `chronyd` adjusts the rate at which root dispersion grows between +updates of the clock according to the stability of its NTP measurements. The +minimum rate is set by the the `maxclockerror` directive. By default it is 1 +ppm (1 microsecond per second). + +The estimated maximum error of the NTP clock is the sum of the root dispersion +and half of the root delay. This value is called root distance. The current +values of root dispersion and delay are included in the `tracking` report. + +The estimated maximum error of the system clock, which is synchronized to the +NTP clock, is the sum of the root distance and remaining correction of the +system clock provided as `System time` in the `tracking` report. A maximum +value of this estimate between updates of the clock is included in the +`tracking` log. + +Note that the resolution of the root delay and root dispersion fields in NTP +messages is about 15 microseconds and `chronyd` rounds the values up, i.e. the +minimum root distance an NTP client can normally observe is about 22.5 +microseconds. An NTP extension field containing root delay and dispersion in a +better resolution of about 4 nanoseconds can be enabled by the `extfield F323` +option. + == Operating systems === Does `chrony` support Windows? |