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
* 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
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
@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
@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
@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
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
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
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
@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
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
@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,
@example
burst <n-good-measurements>/<max-measurements> [<mask>/<masked-address>]
+burst <n-good-measurements>/<max-measurements> [<masked-address>/<masked-bits>]
@end example
The mask and masked-address arguments are optional, in which case
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
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
@example
cmdaccheck a.b.c
cmdaccheck 1.2.3.4
+cmdaccheck 2001:db8::1
@end example
@c }}}
@c {{{ cmdallow
@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
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 }}}
@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.)
@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.
maxpoll <host> <new-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).
minpoll <host> <new-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).
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
@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
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
@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
@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
projects / thirdparty / chrony.git / commitdiff
