faraphel/chrony
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update documentation for refclock and IPv6 support

Browse source
This commit is contained in:
Miroslav Lichvar 2009-10-28 16:53:03 +01:00
parent 465e580a39
commit f2f592fa0d
1 changed files with 159 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

206
chrony.texi
View file

@ -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 <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
@ -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 <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).
@ -3032,7 +3139,7 @@ The syntax is as follows
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).
@ -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