diff --git a/chrony.texi b/chrony.texi index 25a11b2..1fe5920 100644 --- a/chrony.texi +++ b/chrony.texi @@ -203,14 +203,6 @@ integrated into @code{chronyd}. Things @code{xntpd} can do that @code{chronyd} can't: @itemize @bullet -@item -@code{xntpd} supports a range of different hardware reference clocks -(GPS, atomic etc) that can be connected to a computer to provide a -`stratum-1' server. @code{chronyd} does not support any such hardware -@emph{yet}; I don't have access to any to do any development work. -However, the software architecture should allow such equipment to be -interfaced at a later date. - @item @code{xntpd} supports effectively all of RFC1305, including broadcast / multicast clients and extra encryption schemes for authenticating @@ -1189,6 +1181,7 @@ directives can occur in any order in the file. * peer directive:: Specify an NTP peer * pidfile directive:: Specify the file where chronyd's pid is written * port directive:: Set port to use for NTP packets +* refclock directive:: Specify a reference clock * rtcdevice directive:: Specify name of enhanced RTC device (if not /dev/rtc) * rtcfile directive:: Specify the file where real-time clock data is stored * rtconutc directive:: Specify that the real time clock keeps UTC not local time @@ -1253,18 +1246,22 @@ allow 1.2 allow 3.4.5 allow 6.7.8/22 allow 6.7.8.9/22 +allow 2001:db8::/32 +allow 0/0 +allow ::/0 allow @end example The first command allows the named node to be an NTP client of this computer. -The second command allows any node with an IP address of the form 1.2.x.y (with +The second command allows any node with an IPv4 address of the form 1.2.x.y (with x and y arbitrary) to be an NTP client of this computer. Likewise, the third -command allows any node with an IP address of the form 3.4.5.x to have client -NTP access. The fourth and fifth forms allow access from any node with an IP +command allows any node with an IPv4 address of the form 3.4.5.x to have client +NTP access. The fourth and fifth forms allow access from any node with an IPv4 address of the form 6.7.8.x, 6.7.9.x, 6.7.10.x or 6.7.11.x (with x arbitrary), i.e. the value 22 is the number of bits defining the specified subnet. (In the -fifth form, the final byte is ignored). The sixth form allows access by any -node on the entire Internet. +fifth form, the final byte is ignored). The sixth form is used for IPv6 +addresses. The seventh and eighth forms allow access by any IPv4 and IPv6 node +respectively. The ninth forms allows access by any node (IPv4 or IPv6). A second form of the directive, @code{allow all}, has a greater effect, depending on the ordering of directives in the configuration file. To @@ -1330,6 +1327,9 @@ firewalls). It is, therefore, not particularly useful. Use of the @code{allow} and @code{deny} directives together with a network firewall is more likely to be successful. +For each of IPv4 and IPv6 protocols, only one @code{bindaddress} +directive can be specified. + @c }}} @c {{{ bindcmdaddress @node bindcmdaddress directive @@ -1354,6 +1354,9 @@ interfaces. It is, therefore, not particularly useful. Use of the @code{cmdallow} and @code{cmddeny} directives together with a network firewall is more likely to be successful. +For each of IPv4 and IPv6 protocols, only one @code{bindcmdaddress} +directive can be specified. + @c }}} @c {{{ broadcast directive @node broadcast directive @@ -1368,6 +1371,7 @@ The syntax is as follows @example broadcast 30 192.168.1.255 broadcast 60 192.168.2.255 12123 +broadcast 60 ff02::101 @end example In the first example, the destination port defaults to 123/udp (the normal NTP @@ -1537,8 +1541,9 @@ An example of the command is dumpdir /var/log/chrony @end example -A source whose IP address is 1.2.3.4 would have its measurement -history saved in the file @file{/var/log/chrony/1.2.3.4.dat}. +A source whose reference id (the IP address for IPv4 sources) is +1.2.3.4 would have its measurement history saved in the file +@file{/var/log/chrony/1.2.3.4.dat}. @c }}} @c {{{ dumponexit @node dumponexit directive @@ -2113,6 +2118,90 @@ port 11123 This would change the NTP port served by chronyd on the computer to udp/11123. +@c }}} +@c {{{ refclock +@node refclock directive +@subsection refclock +The @code{refclock} directive allows reference clocks to be specified. +The directive is immediately followed by a refclock driver name and +its parameter. + +There are currently three drivers implemented: + +@table @code +@item PPS +Pulse per second (PPS) API driver. The parameter is a path to the PPS +device. Assert events are used by default. The path can have +:1 appended to use clear events instead. + +PPS refclock needs another source (NTP or non-PPS refclock) or local +directive (@pxref{local directive}) enabled to function. For example: + +@example +refclock SHM 0 offset 0.5 delay 0.1 +refclock PPS /dev/pps0 +@end example + +@item SHM +NTP shared memory driver. The parameter is the number of the +shared memory segment that should be used to read timestamps, usually +0, 1, 2 or 3. For example: + +@example +refclock SHM 1 poll 3 refid GPS1 +@end example + +Software that can be used as a source of timestamps includes +@code{gpsd} and @code{shmpps}. +@item SOCK +Unix domain socket driver. The parameter is a path to the socket +which is used as the source of timestamps. This is as a better +alternative to SHM, it does not require polling and the offset +resolution is not limited to microsecond. The format for messages +sent over the socket is declared in file @code{refclock_sock.c}. +@end table + +The @code{refclock} command also supports a number of subfields (which +may be defined in any order): + +@table @code +@item poll +Timestamps produced by refclock drivers are not used immediately, but +they are stored and processed by a median filter in intervals +specified by this option. This is defined as a power of 2. The +default is 4 (16 seconds). A shorter interval allows @code{chronyd} +to react faster to frequency changes, but it may increase noise. +@item dpoll +Some drivers are not controlled by external events and thus require +polling. Again this is defined as a power of 2 and can be negative +for sub-second intervals. The default is 0 (1 second). +@item refid +This option is used to specify a reference id of the refclock, as up +to four ASCII characters. By default, first three characters from +driver name and the number of the refclock are used as refid. Each +refclock has to use an unique refid. +@item filter +This option sets the length of the median filter which is used to +reduce noise. With each poll about half of the stored samples are +discarded and one final sample is calculated as average of the +remaining samples. The default is 15. +@item rate +PPS signal frequency (in Hz). This option only controls how the +received pulses are aligned. To actually receive more than one +pulse per second, a negative @code{dpoll} has to be specified (-3 for +5Hz signal). The default is 1. +@item offset +This option can be used to compensate a constant error. The specified +offset (in seconds) is applied to all samples produced by the +refclock. The default is 0.0. +@item delay +This option is used to specify how the refclock is assumed +to be inaccurate (in seconds). Increasing the value is useful to +avoid having no majority in the source selection algorithm or to make +the algorithm prefer other refclocks. The default is 1e-9 (1 +nanosecond). +@end table + @c }}} @c {{{ rtcdevice @node rtcdevice directive @@ -2226,9 +2315,8 @@ synchronise its system time to that of the server, but the server's system time will never be influenced by that of a client. The @code{server} directive is immediately followed by either the name -of the server, or its IP address in dotted-quad notation. The server -command also supports a number of subfields (which may be defined in any -order): +of the server, or its IP address. The server command also supports a +number of subfields (which may be defined in any order): @table @code @item port @@ -2495,6 +2583,7 @@ follows: @example accheck a.b.c accheck 1.2.3.4 +accheck 2001:db8::1 @end example This command can be used to examine the effect of a series of @@ -2569,6 +2658,9 @@ allow 1.2 allow 3.4.5 allow 6.7.8/22 allow 6.7.8.9/22 +allow 2001:db8:789a::/48 +allow 0/0 +allow ::/0 allow @end example @@ -2585,7 +2677,7 @@ directive in the configuration file (@pxref{allow directive}). @node burst command @subsubsection burst The @code{burst} command tells @code{chronyd} to make a set of measurements to -each of its sources over a short duration (rather than the usual +each of its NTP sources over a short duration (rather than the usual periodic measurements that it makes). After such a burst, @code{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, @@ -2597,6 +2689,7 @@ The syntax of the burst command is as follows @example burst / [/] +burst / [/] @end example The mask and masked-address arguments are optional, in which case @@ -2618,18 +2711,21 @@ attempt to make, even if the required number of good measurements has not been obtained. @item mask -This is a dotted quad argument (e.g. @code{255.255.255.0}) with which -the IP address of each of @code{chronyd}'s sources is to be masked. +This is an IP address with which the IP address of each of @code{chronyd}'s +sources is to be masked. @item masked-address -This is a dotted quad argument (e.g. @code{1.2.3.0}). If the masked IP -address of a source matches this value then the burst command is applied -to that source. +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. + +@item masked-bits +This can be used with @code{masked-address} for CIDR notation, which is a +shorter alternative to the form with mask. + @end table -If no mask or masked address arguments are provided, the default is -@code{0.0.0.0} and @code{0.0.0.0} respectively, which will match every -source. +If no mask or masked address arguments are provided, every source will +be matched. An example of the two-argument form of the command is @@ -2641,15 +2737,17 @@ This will cause @code{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. -An example of the four-argument form of the command is +Examples of the four-argument form of the command are @example burst 2/10 255.255.0.0/1.2.0.0 +burst 2/10 2001:db8:789a::/48 @end example -In this case, the two out of ten sampling will only be applied to -sources whose IP addresses are of the form @code{1.2.x.y}, where x and y -are arbitrary. +In the first case, the two out of ten sampling will only be applied to +sources whose IPv4 addresses are of the form @code{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 @code{2001:db8:789a}. @c }}} @c {{{ clients @node clients command @@ -2714,6 +2812,7 @@ Examples of use are as follows: @example cmdaccheck a.b.c cmdaccheck 1.2.3.4 +cmdaccheck 2001:db8::1 @end example @c }}} @c {{{ cmdallow @@ -2776,6 +2875,7 @@ The syntax is illustrated in the examples below. @example delete foo.bar.com delete 1.2.3.4 +delete 2001:db8::1 @end example There is one parameter, the name or IP address of the server or peer to @@ -2795,6 +2895,9 @@ deny 1.2 deny 3.4.5 deny 6.7.8/22 deny 6.7.8.9/22 +deny 2001:db8:789a::/48 +deny 0/0 +deny ::/0 deny @end example @c }}} @@ -2947,12 +3050,14 @@ The following examples illustrate the syntax @example maxdelay foo.bar.com 0.3 maxdelay 1.2.3.4 0.0015 +maxdelay 2001:db8::1 0.0015 @end example The first example sets the maximum network delay allowed for a measurement to the host @code{foo.bar.com} to 0.3 seconds. The second -example sets the maximum network delay for a measurement to the host -with IP address @code{1.2.3.4} to 1.5 milliseconds. +and third examples set the maximum network delay for a measurement to +the host with IPv4 address @code{1.2.3.4} and the host with IPv6 address +@code{2001:db8::1} to 1.5 milliseconds. (Any measurement whose network delay exceeds the specified value is discarded.) @@ -2970,13 +3075,15 @@ The following examples illustrate the syntax @example maxdelayratio foo.bar.com 1.5 maxdelayratio 1.2.3.4 2.0 +maxdelayratio 2001:db8::1 2.0 @end example The first example sets the maximum network delay for a measurement to the host @code{foo.bar.com} to be 1.5 times the minimum delay found amongst the previous measurements that have been retained. The second -example sets the maximum network delay for a measurement to the host -with IP address @code{1.2.3.4} to be double the retained minimum. +and third examples set the maximum network delay for a measurement to +the host with IPv4 address @code{1.2.3.4} and the host with IPv6 +address @code{2001:db8::1} to be double the retained minimum. As for @code{maxdelay}, any measurement whose network delay is too large will be discarded. @@ -2995,7 +3102,7 @@ The syntax is as follows maxpoll @end example -where the host can be specified as either a machine name or dotted-quad +where the host can be specified as either a machine name or IP address. The new minimum poll is specified as a base-2 logarithm of the number of seconds between polls (e.g. specify 6 for 64 second sampling). @@ -3032,7 +3139,7 @@ The syntax is as follows minpoll @end example -where the host can be specified as either a machine name or dotted-quad +where the host can be specified as either a machine name or IP address. The new minimum poll is specified as a base-2 logarithm of the number of seconds between polls (e.g. specify 6 for 64 second sampling). @@ -3099,24 +3206,29 @@ the @code{offline} command being used, @code{chronyd} would assume that the source had failed and would attempt to pick another synchronisation source. -There are two forms of the @code{offline} command. The first form is a +There are three forms of the @code{offline} command. The first form is a wildcard, meaning all sources. The second form allows a IP address mask -and a masked address to be specified. These forms are illustrated below. +and a masked address to be specified. The third form uses the CIDR +notation. These forms are illustrated below. @example offline offline 255.255.255.0/1.2.3.0 +offline 2001:db8:789a::/48 @end example The second form means that the @code{offline} command is to be applied -to any source whose IP address is in the 1.2.3 subnet. (The host's +to any source whose IPv4 address is in the @code{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). +masked-address the host is processed). The third form means that the +command is to be applied to all sources whose IPv6 addresses have first +48 bits equal to @code{2001:db8:789a}. The wildcard form of the address is actually equivalent to @example offline 0.0.0.0/0.0.0.0 +offline ::/0 @end example @c }}} @c {{{ online @@ -3283,8 +3395,7 @@ The columns are as follows: @item M This indicates the mode of the source. @code{^} means a server, @code{=} means a peer and @code{#} indicates a locally connected -reference clock@footnote{In the current version this will never be -shown, because @code{chronyd} has no support for reference clocks yet.}. +reference clock. @item S This column indicates the state of the sources. @code{*} indicates the @@ -3297,7 +3408,8 @@ appears to have too much variability. The @code{~} condition is also shown at start-up, until at least 3 samples have been gathered from it. @item Name/IP address -This shows the name or the IP address of the source. +This shows the name or the IP address of the source, or refid for +reference clocks. @item Stratum This shows the stratum of the source, as reported in its most recently @@ -3360,8 +3472,8 @@ The columns are as follows @table @code @item Name/IP Address -This is the name or dotted-quad IP address of the NTP server (or peer) -to which the rest of the line relates. +This is the name or IP address of the NTP server (or peer) or refid of +the refclock to which the rest of the line relates. @item NP This is the number of sample points currently being retained for the @@ -3417,7 +3529,7 @@ The fields are explained as follows. @table @code @item Reference ID -This is the IP address, and name if available, of the server to which +This is the refid and name (or IP address) if available, of the server to which the computer is currently synchronised. If this is @code{127.127.1.1} it means the computer is not synchronised to any external source and that you have the `local' mode operating (via the @code{local} command