5367 lines
205 KiB
Text
5367 lines
205 KiB
Text
\input texinfo
|
|
@c {{{ Main header stuff
|
|
@afourwide
|
|
@paragraphindent 0
|
|
@setfilename chrony.info
|
|
@settitle User guide for the chrony suite
|
|
@c @setchapternewpage off
|
|
|
|
@ifinfo
|
|
@dircategory Net Utilities
|
|
@direntry
|
|
* chrony: (chrony). How to use chronyd and chronyc
|
|
* chronyd: (chrony)Starting chronyd. Reference for chronyd
|
|
* chronyc: (chrony)Running chronyc. Reference for chronyc
|
|
@end direntry
|
|
@end ifinfo
|
|
|
|
@titlepage
|
|
@sp 10
|
|
@title The chrony suite
|
|
@subtitle This manual describes how to use
|
|
@subtitle the programs chronyd and chronyc
|
|
@author Richard P. Curnow
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 1997-1999 Richard P. Curnow
|
|
Copyright @copyright{} 2009-2014 Miroslav Lichvar
|
|
@end titlepage
|
|
@c }}}
|
|
@c {{{ Top node
|
|
@node Top
|
|
@top
|
|
@menu
|
|
* Introduction:: What the chrony suite does
|
|
* Installation:: How to compile and install the software
|
|
* Typical scenarios:: How to configure the software for some common cases
|
|
* Usage reference:: Reference manual
|
|
* FAQ:: Answers to some common questions about chrony
|
|
* GPL:: The GNU General Public License
|
|
@end menu
|
|
@c }}}
|
|
@c {{{ Ch:Introduction
|
|
@c {{{ Chapter top
|
|
@node Introduction
|
|
@chapter Introduction
|
|
@menu
|
|
* Overview:: What the programs do
|
|
* Acknowledgements:: Credit where credit is due
|
|
* Availability:: Where to get the software
|
|
* Other time synchronisation packages:: Comparision with other software
|
|
* Distribution and warranty:: There is no warranty
|
|
* Bug reporting:: How to report bugs and make suggestions
|
|
* Contributing:: Areas where contributions are particularly welcome
|
|
@end menu
|
|
@c }}}
|
|
@c {{{ S:Overview
|
|
@node Overview
|
|
@section Overview
|
|
chrony is a versatile implementation of the Network Time Protocol (NTP).
|
|
It can synchronize the system clock with NTP servers, reference clocks
|
|
(e.g. GPS receiver), and manual input using wristwatch and keyboard.
|
|
It can also operate as an NTPv4 (RFC 5905) server and peer to provide
|
|
a time service to other computers in the network.
|
|
|
|
It is designed to perform well in a wide range of conditions, including
|
|
intermittent network connections, heavily congested networks, changing
|
|
temperatures (ordinary computer clocks are sensitive to temperature),
|
|
and systems that do not run continuosly, or run on a virtual machine.
|
|
|
|
Typical accuracy between two machines on a LAN is in tens, or a few
|
|
hundreds, of microseconds; over the Internet, accuracy is typically
|
|
within a few milliseconds. With a good hardware reference clock
|
|
sub-microsecond accuracy is possible.
|
|
|
|
Two programs are included in chrony, @code{chronyd} is a daemon that can
|
|
be started at boot time and @code{chronyc} is a command-line interface
|
|
program which can be used to monitor @code{chronyd}'s performance and to
|
|
change various operating parameters whilst it is running.
|
|
|
|
The IP addresses from which @code{chronyc} clients may connect can be tightly
|
|
controlled. The default is just the computer that @code{chronyd} itself is
|
|
running on.
|
|
@c }}}
|
|
@c {{{ S:Acknowledgments
|
|
@node Acknowledgements
|
|
@section Acknowledgements
|
|
|
|
The @code{chrony} suite makes use of the algorithm known as @emph{RSA
|
|
Data Security, Inc. MD5 Message-Digest Algorithm} for authenticating
|
|
messages between different machines on the network.
|
|
|
|
In writing the @code{chronyd} program, extensive use has been made of
|
|
RFC 1305 and RFC 5905, written by David Mills. The source code of
|
|
the NTP reference implementation has been used to check details of the
|
|
protocol.
|
|
@c }}}
|
|
@c {{{ S:Availability
|
|
@node Availability
|
|
@section Availability
|
|
@menu
|
|
* Getting the software:: Where can I get the software from?
|
|
* Platforms:: Which platforms will it run on?
|
|
@end menu
|
|
|
|
|
|
@node Getting the software
|
|
@subsection Getting the software
|
|
Links on @uref{http://chrony.tuxfamily.org, the chrony home page}
|
|
describe how to obtain the software.
|
|
|
|
|
|
@node Platforms
|
|
@subsection Platforms
|
|
Although most of the program is portable between
|
|
Unix-like systems, there are parts that have to be tailored to each
|
|
specific vendor's system. These are the parts that interface with the
|
|
operating system's facilities for adjusting the system clock;
|
|
different operating systems may provide different function calls to
|
|
achieve this, and even where the same function is used it may have
|
|
different quirks in its behaviour.
|
|
|
|
The software is known to work on Linux, FreeBSD, NetBSD and Solaris. Closely
|
|
related systems may work too. Porting the software to other systems
|
|
(particularly to those supporting an @code{adjtime} system call) should not be
|
|
difficult, however it requires access to such systems to test out the driver.
|
|
@c }}}
|
|
@c {{{ S:Other programs
|
|
@node Other time synchronisation packages
|
|
@section Relationship to other software packages
|
|
@menu
|
|
* Comparison with ntpd::
|
|
* Comparison with timed::
|
|
@end menu
|
|
|
|
@node Comparison with ntpd
|
|
@subsection ntpd
|
|
The `reference' implementation of the Network Time Protocol is the
|
|
program @code{ntpd}, available via
|
|
@uref{http://www.ntp.org/, The NTP home page}.
|
|
|
|
One of the main differences between @code{ntpd} and @code{chronyd} is in
|
|
the algorithms used to control the computer's clock. Things
|
|
@code{chronyd} can do better than @code{ntpd}:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{chronyd} can perform usefully in an environment where access to
|
|
the time reference is intermittent. @code{ntpd} needs regular polling
|
|
of the reference to work well.
|
|
@item
|
|
@code{chronyd} can usually synchronise the clock faster and with better
|
|
time accuracy.
|
|
@item
|
|
@code{chronyd} quickly adapts to sudden changes in the rate of the clock
|
|
(e.g. due to changes in the temperature of the crystal oscillator).
|
|
@code{ntpd} may need a long time to settle down again.
|
|
@item
|
|
@code{chronyd} can perform well even when the network is congested for
|
|
longer periods of time.
|
|
@item
|
|
@code{chronyd} in the default configuration never steps the time to not
|
|
upset other running programs. @code{ntpd} can be configured to never
|
|
step the time too, but it has to use a different means of adjusting the
|
|
clock, which has some
|
|
disadvantages.
|
|
@item
|
|
@code{chronyd} can adjust the rate of the clock on Linux in a larger
|
|
range, which allows it to operate even on machines with broken or
|
|
unstable clock (e.g. in some virtual machines).
|
|
@end itemize
|
|
|
|
Things @code{chronyd} can do that @code{ntpd} can't:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{chronyd} provides support for isolated networks whether the only
|
|
method of time correction is manual entry (e.g. by the administrator
|
|
looking at a clock). @code{chronyd} can look at the errors corrected at
|
|
different updates to work out the rate at which the computer gains or
|
|
loses time, and use this estimate to trim the computer clock
|
|
subsequently.
|
|
|
|
@item
|
|
@code{chronyd} provides support to work out the gain or loss rate of the
|
|
`real-time clock', i.e. the clock that maintains the time when the
|
|
computer is turned off. It can use this data when the system boots to
|
|
set the system time from a corrected version of the real-time clock.
|
|
These real-time clock facilities are only available on Linux, so far.
|
|
@end itemize
|
|
|
|
Things @code{ntpd} can do that @code{chronyd} can't:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{ntpd} supports all operating modes from RFC 5905, including
|
|
broadcast, multicast and manycast client / server. It supports the
|
|
orphan mode and it also supports authentication based on public-key
|
|
cryptography described in RFC 5906.
|
|
|
|
@item
|
|
@code{ntpd} has been ported to more types of computer / operating
|
|
system.
|
|
|
|
@item
|
|
@code{ntpd} includes drivers for many reference clocks. @code{chronyd}
|
|
relies on other programs (e.g. gpsd) to access the data from the
|
|
reference clocks.
|
|
@end itemize
|
|
|
|
@node Comparison with timed
|
|
@subsection timed
|
|
@code{timed} is a program that is part of the BSD networking suite. It
|
|
uses broadcast packets to find all machines running the daemon within a
|
|
subnet. The machines elect a master which periodically measures the
|
|
system clock offsets of the other computers using ICMP timestamps.
|
|
Corrections are sent to each member as a result of this process.
|
|
|
|
Problems that may arise with @code{timed} are :
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Because it uses broadcasts, it is not possible to isolate its
|
|
functionality to a particular group of computers; there is a risk of
|
|
upsetting other computers on the same network (e.g. where a whole
|
|
company is on the same subnet but different departments are independent
|
|
from the point of view of administering their computers.)
|
|
@item
|
|
The update period appears to be 10 minutes. Computers can build up
|
|
significant offsets relative to each other in that time. If a
|
|
computer can estimate its rate of drift it can keep itself closer to
|
|
the other computers between updates by adjusting its clock every few
|
|
seconds. @code{timed} does not seem to do this.
|
|
@item
|
|
@code{timed} does not have any integrated capability for feeding
|
|
real-time into its estimates, or for estimating the average rate of time
|
|
loss/gain of the machines relative to real-time (unless one of the
|
|
computers in the group has access to an external reference and is always
|
|
appointed as the `master').
|
|
@end itemize
|
|
|
|
@code{timed} does have the benefit over @code{chronyd} that for isolated
|
|
networks of computers, they will track the `majority vote' time. For
|
|
such isolated networks, @code{chronyd} requires one computer to be the
|
|
`master' with the others slaved to it. If the master has a particular
|
|
defective clock, the whole set of computers will tend to slip relative
|
|
to real time (but they @emph{will} stay accurate relative to one
|
|
another).
|
|
@c }}}
|
|
@c {{{ S:Rights + warranty
|
|
@node Distribution and warranty
|
|
@section Distribution rights and (lack of) warranty
|
|
|
|
Chrony may be distributed in accordance with the GNU General Public License
|
|
version 2, reproduced in @xref{GPL}.
|
|
|
|
@c }}}
|
|
@c {{{ S:Bug reporting + suggestions
|
|
@node Bug reporting
|
|
@section Bug reporting and suggestions
|
|
|
|
If you think you've found a bug in chrony, or have a suggestion, please let us
|
|
know. You can join chrony users mailing list by sending a message with the
|
|
subject subscribe to @email{chrony-users-request@@chrony.tuxfamily.org}. Only
|
|
subscribers can post to the list.
|
|
|
|
When you are reporting a bug, please send us all the information you can.
|
|
Unfortunately, chrony has proven to be one of those programs where it is very
|
|
difficult to reproduce bugs in a different environment. So we may have to
|
|
interact with you quite a lot to obtain enough extra logging and tracing to
|
|
pin-point the problem in some cases. Please be patient and plan for this!
|
|
|
|
Of course, if you can debug the problem yourself and send us a source code
|
|
patch to fix it, we will be very grateful!
|
|
|
|
@c }}}
|
|
@c {{{ S:Contributions
|
|
@node Contributing
|
|
@section Contributions
|
|
|
|
Although chrony is now a fairly mature and established project, there are still
|
|
areas that could be improved. If you can program in C and have some expertise
|
|
in these areas, you might be able to fill the gaps.
|
|
|
|
Particular areas that need addressing are :
|
|
|
|
@enumerate
|
|
@item Porting to other Unices
|
|
|
|
This involves creating equivalents of sys_solaris.c, sys_linux.c etc for the
|
|
new system.
|
|
|
|
@item Porting to Windows NT
|
|
|
|
A small amount of work on this was done under Cygwin. Only the sorting
|
|
out of the include files has really been achieved so far. The two main
|
|
areas still to address are
|
|
|
|
@enumerate
|
|
@item The system clock driver.
|
|
@item How to make chronyd into an NT service (i.e. what to replace fork(),
|
|
setsid() etc with so that chronyd can be automatically started in the system
|
|
bootstrap.
|
|
@end enumerate
|
|
|
|
@item More drivers for reference clock support
|
|
|
|
@end enumerate
|
|
@c }}}
|
|
@c }}}
|
|
@c {{{ Ch:Installation
|
|
@node Installation
|
|
@chapter Installation
|
|
|
|
@c {{{ main introduction text
|
|
The software is distributed as source code which has to be compiled.
|
|
The source code is supplied in the form of a gzipped tar file, which
|
|
unpacks to a subdirectory identifying the name and version of the
|
|
program.
|
|
|
|
After unpacking the source code, change directory into it, and type
|
|
|
|
@example
|
|
./configure
|
|
@end example
|
|
|
|
This is a shell script that automatically determines the system type.
|
|
There is a single optional parameter, @code{--prefix} which indicates
|
|
the directory tree where the software should be installed. For example,
|
|
|
|
@example
|
|
./configure --prefix=/opt/free
|
|
@end example
|
|
|
|
will install the @code{chronyd} daemon into /opt/free/sbin and the
|
|
@code{chronyc} control program into /opt/free/bin. The default value for the
|
|
prefix is /usr/local.
|
|
|
|
The configure script assumes you want to use gcc as your compiler.
|
|
If you want to use a different compiler, you can configure this way:
|
|
|
|
@example
|
|
CC=cc CFLAGS=-O ./configure --prefix=/opt/free
|
|
@end example
|
|
|
|
for Bourne-family shells, or
|
|
|
|
@example
|
|
setenv CC cc
|
|
setenv CFLAGS -O
|
|
./configure --prefix=/opt/free
|
|
@end example
|
|
|
|
for C-family shells.
|
|
|
|
If the software cannot (yet) be built on your system, an error message
|
|
will be shown. Otherwise, @file{Makefile} will be generated.
|
|
|
|
If editline or readline library is available, chronyc will be built with line
|
|
editing support. If you don't want this, specify the --disable-readline flag
|
|
to configure. Please refer to @pxref{line editing support} for more information.
|
|
|
|
If a @file{timepps.h} header is available (e.g. from the
|
|
@uref{http://linuxpps.org/, LinuxPPS project}), @code{chronyd} will be built with PPS API
|
|
reference clock driver. If the header is installed in a location that isn't
|
|
normally searched by the compiler, you can add it to the searched locations by
|
|
setting @code{CPPFLAGS} variable to @code{-I/path/to/timepps}.
|
|
|
|
Now type
|
|
|
|
@example
|
|
make
|
|
@end example
|
|
|
|
to build the programs.
|
|
|
|
If you want to build the manual in plain text, HTML and info versions, type
|
|
|
|
@example
|
|
make docs
|
|
@end example
|
|
|
|
Once the programs have been successfully compiled, they need to be
|
|
installed in their target locations. This step normally needs to be
|
|
performed by the superuser, and requires the following command to be
|
|
entered.
|
|
|
|
@example
|
|
make install
|
|
@end example
|
|
|
|
This will install the binaries, plain text manual and manpages.
|
|
|
|
To install the HTML and info versions of the manual as well, enter the command
|
|
|
|
@example
|
|
make install-docs
|
|
@end example
|
|
|
|
If you want chrony to appear in the top level info directory listing, you need
|
|
to run the @command{install-info} command manually after this step.
|
|
@command{install-info} takes 2 arguments. The first is the path to the
|
|
@file{chrony.info} file you have just installed. This will be the argument you
|
|
gave to --prefix when you configured (@file{/usr/local} by default), with
|
|
@file{/share/info/chrony.info} on the end. The second argument is the location of
|
|
the file called @file{dir}. This will typically be @file{/usr/share/info/dir}. So
|
|
the typical command line would be
|
|
|
|
@example
|
|
install-info /usr/local/share/info/chrony.info /usr/share/info/dir
|
|
@end example
|
|
|
|
Now that the software is successfully installed, the next step is to
|
|
set up a configuration file. The default location of the file
|
|
is @file{@SYSCONFDIR@/chrony.conf}. Several examples of configuration with
|
|
comments are included in the examples directory. Suppose you want to use
|
|
public NTP servers from the pool.ntp.org project as your time reference. A
|
|
minimal useful configuration file could be
|
|
|
|
@example
|
|
pool pool.ntp.org iburst
|
|
makestep 10 3
|
|
rtcsync
|
|
@end example
|
|
|
|
Then, @code{chronyd} can be run.
|
|
@c }}}
|
|
@menu
|
|
* line editing support:: If libraries are in a non-standard place
|
|
* package builders:: Extra options useful to package builders
|
|
@end menu
|
|
@c {{{ line editing support
|
|
@node line editing support
|
|
@section Support for line editing libraries
|
|
Chronyc can be built with support for line editing, this allows you to use the
|
|
cursor keys to replay and edit old commands. Two libraries are supported which
|
|
provide such functionality, editline and GNU readline.
|
|
|
|
Please note that readline since version 6.0 is licensed under GPLv3+ which is
|
|
incompatible with chrony's license GPLv2. You should use editline instead if
|
|
you don't want to use older readline versions.
|
|
|
|
The configure script will automatically enable the line editing support if one
|
|
of the supported libraries is available. If they are both available, the
|
|
editline library will be used.
|
|
|
|
If you don't want to use it (in which case chronyc will use a minimal command
|
|
line interface), invoke configure like this:
|
|
|
|
@example
|
|
./configure --disable-readline other-options...
|
|
@end example
|
|
|
|
If you have editline, readline or ncurses installed in locations that aren't
|
|
normally searched by the compiler and linker, you need to use extra options:
|
|
|
|
@table @samp
|
|
@item --with-readline-includes=directory_name
|
|
This defines the name of the directory above the one where @file{readline.h}
|
|
is. @file{readline.h} is assumed to be in @file{editline} or @file{readline}
|
|
subdirectory of the named directory.
|
|
|
|
@item --with-readline-library=directory_name
|
|
This defines the directory containing the @file{libedit.a} or @file{libedit.so}
|
|
file, or @file{libreadline.a} or @file{libreadline.so} file.
|
|
|
|
@item --with-ncurses-library=directory_name
|
|
This defines the directory containing the @file{libncurses.a} or
|
|
@file{libncurses.so} file.
|
|
@end table
|
|
|
|
@c }}}
|
|
@c {{{
|
|
@node package builders
|
|
@section Extra options for package builders
|
|
The configure and make procedures have some extra options that may be useful if
|
|
you are building a distribution package for chrony.
|
|
|
|
The --infodir=DIR option to configure specifies an install directory
|
|
for the info files. This overrides the @file{info} subdirectory of the
|
|
argument to the --prefix option. For example, you might use
|
|
|
|
@example
|
|
./configure --prefix=/usr --infodir=/usr/share/info
|
|
@end example
|
|
|
|
The --mandir=DIR option to configure specifies an install directory
|
|
for the man pages. This overrides the @file{man} subdirectory of the
|
|
argument to the --prefix option.
|
|
|
|
@example
|
|
./configure --prefix=/usr --infodir=/usr/share/info --mandir=/usr/share/man
|
|
@end example
|
|
|
|
to set both options together.
|
|
|
|
The final option is the DESTDIR option to the make command. For example, you
|
|
could use the commands
|
|
|
|
@example
|
|
./configure --prefix=/usr --infodir=/usr/share/info --mandir=/usr/share/man
|
|
make all docs
|
|
make install DESTDIR=./tmp
|
|
cd tmp
|
|
tar cvf - . | gzip -9 > chrony.tar.gz
|
|
@end example
|
|
|
|
to build a package. When untarred within the root directory, this will install
|
|
the files to the intended final locations.
|
|
|
|
@c }}}
|
|
|
|
@c }}}
|
|
@c {{{ Ch:Typical operating scenarios
|
|
@c {{{ Chapter top
|
|
@node Typical scenarios
|
|
@chapter Typical operating scenarios
|
|
@menu
|
|
* Computers on the net:: Your computer is on the Internet most of the time
|
|
(or on a private network with NTP servers)
|
|
* Infrequent connection:: You connect to the Internet sometimes (e.g. via a modem)
|
|
* Isolated networks:: You have an isolated network with no reference clocks
|
|
* Dial-up home PCs:: Additional considerations if you turn your computer off
|
|
when it's not in use
|
|
* Configuration options overview:: Overview of some configuration options
|
|
@end menu
|
|
@c }}}
|
|
@c {{{ S:Permanent connection
|
|
@node Computers on the net
|
|
@section Computers connected to the internet
|
|
In this section we discuss how to configure chrony for computers that
|
|
are connected to the Internet (or to any network containing true NTP
|
|
servers which ultimately derive their time from a reference clock)
|
|
permanently or most of the time.
|
|
|
|
To operate in this mode, you will need to know the names of the NTP
|
|
server machines you wish to use. You may be able to find names of
|
|
suitable servers by one of the following methods:
|
|
|
|
@itemize @bullet
|
|
@item Your institution may already operate servers on its network.
|
|
Contact your system administrator to find out.
|
|
|
|
@item Your ISP probably has one or more NTP servers available for its
|
|
customers.
|
|
|
|
@item Somewhere under the NTP homepage there is a list of public
|
|
stratum 1 and stratum 2 servers. You should find one or more servers
|
|
that are near to you --- check that their access policy allows you to
|
|
use their facilities.
|
|
|
|
@item Use public servers from
|
|
@uref{http://www.pool.ntp.org/, the pool.ntp.org project}.
|
|
@end itemize
|
|
|
|
Assuming that you have found some servers, you need to set up a
|
|
configuration file to run chrony. The (compiled-in) default location
|
|
for this file is @file{@SYSCONFDIR@/chrony.conf}. Assuming that your NTP
|
|
servers are called @code{foo.example.net}, @code{bar.example.net} and
|
|
@code{baz.example.net}, your @file{chrony.conf} file could contain as a minimum
|
|
|
|
@example
|
|
server foo.example.net
|
|
server bar.example.net
|
|
server baz.example.net
|
|
@end example
|
|
|
|
However, you will probably want to include some of the other directives
|
|
described later. The following directives may be particularly useful :
|
|
@code{driftfile}, @code{makestep}, @code{rtcsync}. Also, the @code{iburst}
|
|
server option is useful to speed up the initial synchronization. The smallest
|
|
useful configuration file would look something like
|
|
|
|
@example
|
|
server foo.example.net iburst
|
|
server bar.example.net iburst
|
|
server baz.example.net iburst
|
|
driftfile @CHRONYVARDIR@/drift
|
|
makestep 10 3
|
|
rtcsync
|
|
@end example
|
|
|
|
When using a pool of NTP servers (one name is used for multiple servers which
|
|
may change over time), it's better to specify them with the @code{pool}
|
|
directive instead of multiple @code{server} directives in order to allow
|
|
@code{chronyd} to replace unreachable or bad servers automatically. The
|
|
configuration file could in this case look like
|
|
|
|
@example
|
|
pool pool.ntp.org iburst
|
|
driftfile @CHRONYVARDIR@/drift
|
|
makestep 10 3
|
|
rtcsync
|
|
@end example
|
|
@c }}}
|
|
@c {{{ S:Infrequent connection
|
|
@node Infrequent connection
|
|
@section Infrequent connection to true NTP servers
|
|
In this section we discuss how to configure chrony for computers that
|
|
have occasional connections to the internet.
|
|
|
|
@menu
|
|
* Configuration for infrequent connections:: How to set up the @code{@SYSCONFDIR@/chrony.conf} file
|
|
* Advising chronyd of internet availability:: How to tell chronyd when the link is available
|
|
@end menu
|
|
|
|
@node Configuration for infrequent connections
|
|
@subsection Setting up the configuration file for infrequent connections
|
|
As in the previous section, you will need access to NTP servers on the
|
|
internet. The same remarks apply for how to find them.
|
|
|
|
In this case, you will need some additional configuration to tell
|
|
@code{chronyd} when the connection to the internet goes up and down.
|
|
This saves the program from continuously trying to poll the servers when
|
|
they are inaccessible.
|
|
|
|
Again, assuming that your NTP servers are called @code{foo.example.net},
|
|
@code{bar.example.net} and @code{baz.example.net}, your @file{chrony.conf} file
|
|
would need to contain something like
|
|
|
|
@example
|
|
server foo.example.net
|
|
server bar.example.net
|
|
server baz.example.net
|
|
@end example
|
|
|
|
However, your computer will keep trying to contact the servers to obtain
|
|
timestamps, even whilst offline. If you operate a dial-on-demand
|
|
system, things are even worse, because the link to the internet will
|
|
keep getting established.
|
|
|
|
For this reason, it would be better to specify this part of your
|
|
configuration file in the following way:
|
|
|
|
@example
|
|
server foo.example.net offline
|
|
server bar.example.net offline
|
|
server baz.example.net offline
|
|
@end example
|
|
|
|
The @code{offline} keyword indicates that the servers start
|
|
in an offline state, and that they should not be contacted until @code{chronyd}
|
|
receives notification that the link to the internet is present.
|
|
|
|
In order to notify @code{chronyd} of the presence of the link, you will need to
|
|
be able to log in to it with the program @code{chronyc}. To do this,
|
|
@code{chronyd} needs to be configured with an administrator password. The
|
|
password is read from a file specified by the @code{keyfile} directive. The
|
|
@code{generatecommandkey} directive can be used to generate a random password
|
|
automatically on the first @code{chronyd} start.
|
|
|
|
The smallest useful configuration file would look something like
|
|
|
|
@example
|
|
server foo.example.net offline
|
|
server bar.example.net offline
|
|
server baz.example.net offline
|
|
keyfile @SYSCONFDIR@/chrony.keys
|
|
generatecommandkey
|
|
driftfile @CHRONYVARDIR@/drift
|
|
makestep 10 3
|
|
@end example
|
|
|
|
The next section describes how to tell @code{chronyd} when the internet link
|
|
goes up and down.
|
|
|
|
@node Advising chronyd of internet availability
|
|
@subsection How to tell chronyd when the internet link is available.
|
|
To use this option, you will need to configure a command key in
|
|
@code{chronyd's} configuration file @file{@SYSCONFDIR@/chrony.conf}, as described in
|
|
the previous section.
|
|
|
|
To tell @code{chronyd} when to start and finish sampling the servers, the
|
|
@code{online} and @code{offline} commands of chronyc need to be used.
|
|
To give an example of their use, we assume that @code{pppd} is the
|
|
program being used to connect to the internet, and that chronyc has been
|
|
installed at its default location @file{@BINDIR@/chronyc}. We
|
|
also assume that the command key has been set up as described in the
|
|
previous section.
|
|
|
|
In the file @file{/etc/ppp/ip-up} we add the command sequence
|
|
|
|
@example
|
|
@BINDIR@/chronyc -a online
|
|
@end example
|
|
|
|
and in the file @file{/etc/ppp/ip-down} we add the sequence
|
|
|
|
@example
|
|
@BINDIR@/chronyc -a offline
|
|
@end example
|
|
|
|
@code{chronyd's} polling of the servers will now only occur whilst the
|
|
machine is actually connected to the Internet.
|
|
@c }}}
|
|
@c {{{ S:Isolated networks
|
|
@node Isolated networks
|
|
@section Isolated networks
|
|
In this section we discuss how to configure chrony for computers that
|
|
never have network conectivity to any computer which ultimately derives
|
|
its time from a reference clock.
|
|
|
|
In this situation, one computer is selected to be the master timeserver.
|
|
The other computers are either direct clients of the master, or clients
|
|
of clients.
|
|
|
|
The rate value in the master's drift file needs to be set to the average
|
|
rate at which the master gains or loses time. @code{chronyd} includes
|
|
support for this, in the form of the @code{manual} directive in the
|
|
configuration file and the @code{settime} command in the @code{chronyc}
|
|
program.
|
|
|
|
If the master is rebooted, @code{chronyd} can re-read the drift rate
|
|
from the drift file. However, the master has no accurate estimate of
|
|
the current time. To get around this, the system can be configured so
|
|
that the master can initially set itself to a `majority-vote' of
|
|
selected clients' times; this allows the clients to `flywheel' the
|
|
master across its outage.
|
|
|
|
A typical configuration file for the master (called @code{master}) might
|
|
be (assuming the clients are in the 192.168.165.x subnet and that the
|
|
master's address is 192.168.169.170)
|
|
|
|
@example
|
|
driftfile @CHRONYVARDIR@/drift
|
|
generatecommandkey
|
|
keyfile @SYSCONFDIR@/chrony.keys
|
|
initstepslew 10 client1 client3 client6
|
|
local stratum 8
|
|
manual
|
|
allow 192.168.165
|
|
@end example
|
|
|
|
For the clients that have to resynchronise the master when it restarts,
|
|
the configuration file might be
|
|
|
|
@example
|
|
server master
|
|
driftfile @CHRONYVARDIR@/drift
|
|
logdir /var/log/chrony
|
|
log measurements statistics tracking
|
|
keyfile @SYSCONFDIR@/chrony.keys
|
|
generatecommandkey
|
|
local stratum 10
|
|
initstepslew 20 master
|
|
allow 192.168.169.170
|
|
@end example
|
|
|
|
The rest of the clients would be the same, except that the @code{local}
|
|
and @code{allow} directives are not required.
|
|
@c }}}
|
|
@c {{{ S:Dial-up home PCs
|
|
@node Dial-up home PCs
|
|
@section The home PC with a dial-up connection
|
|
|
|
@menu
|
|
* Dial-up overview:: General discussion of how the software operates in this mode
|
|
* Dial-up configuration:: Typical configuration files
|
|
@end menu
|
|
|
|
@node Dial-up overview
|
|
@subsection Assumptions/how the software works
|
|
This section considers the home computer which has a dial-up connection.
|
|
It assumes that Linux is run exclusively on the computer. Dual-boot
|
|
systems may work; it depends what (if anything) the other system does to
|
|
the system's real-time clock.
|
|
|
|
Much of the configuration for this case is discussed earlier
|
|
(@pxref{Infrequent connection}). This section addresses specifically
|
|
the case of a computer which is turned off between 'sessions'.
|
|
|
|
In this case, @code{chronyd} relies on the computer's real-time clock
|
|
(RTC) to maintain the time between the periods when it is powered up.
|
|
The arrangement is shown in the figure below.
|
|
|
|
@example
|
|
@group
|
|
trim if required PSTN
|
|
+---------------------------+ +----------+
|
|
| | | |
|
|
v | | |
|
|
+---------+ +-------+ +-----+ +---+
|
|
| System's| measure error/ |chronyd| |modem| |ISP|
|
|
|real-time|------------------->| |-------| | | |
|
|
| clock | drift rate +-------+ +-----+ +---+
|
|
+---------+ ^ |
|
|
| | |
|
|
+---------------------------+ --o-----o---
|
|
set time at boot up |
|
|
+----------+
|
|
|NTP server|
|
|
+----------+
|
|
@end group
|
|
@end example
|
|
|
|
When the computer is connected to the Internet (via the modem),
|
|
@code{chronyd} has access to external NTP servers which it makes
|
|
measurements from. These measurements are saved, and straight-line fits
|
|
are performed on them to provide an estimate of the computer's time
|
|
error and rate of gaining/losing time.
|
|
|
|
When the computer is taken offline from the Internet, the best estimate
|
|
of the gain/loss rate is used to free-run the computer until it next
|
|
goes online.
|
|
|
|
Whilst the computer is running, @code{chronyd} makes measurements of the
|
|
real-time clock (RTC) (via the @file{/dev/rtc} interface, which must be
|
|
compiled into the kernel). An estimate is made of the RTC error at a
|
|
particular RTC second, and the rate at which the RTC gains or loses time
|
|
relative to true time.
|
|
|
|
On 2.6 and later kernels, if your motherboard has a HPET, you need to enable the
|
|
@samp{HPET_EMULATE_RTC} option in your kernel configuration. Otherwise, chrony
|
|
will not be able to interact with the RTC device and will give up using it.
|
|
|
|
When the computer is powered down, the measurement histories for all the
|
|
NTP servers are saved to files (if the @code{dumponexit} directive is
|
|
specified in the configuration file), and the RTC tracking information
|
|
is also saved to a file (if the @code{rtcfile} directive has been
|
|
specified). These pieces of information are also saved if the
|
|
@code{dump} and @code{writertc} commands respectively are issued through
|
|
@code{chronyc}.
|
|
|
|
When the computer is rebooted, @code{chronyd} reads the current RTC time
|
|
and the RTC information saved at the last shutdown. This information is
|
|
used to set the system clock to the best estimate of what its time would
|
|
have been now, had it been left running continuously. The measurement
|
|
histories for the servers are then reloaded.
|
|
|
|
The next time the computer goes online, the previous sessions'
|
|
measurements can contribute to the line-fitting process, which gives a
|
|
much better estimate of the computer's gain/loss rate.
|
|
|
|
One problem with saving the measurements and RTC data when the machine
|
|
is shut down is what happens if there is a power failure; the most
|
|
recent data will not be saved. Although @code{chronyd} is robust enough
|
|
to cope with this, some performance may be lost. (The main danger
|
|
arises if the RTC has been changed during the session, with the
|
|
@code{trimrtc} command in @code{chronyc}. Because of this,
|
|
@code{trimrtc} will make sure that a meaningful RTC file is saved out
|
|
after the change is completed).
|
|
|
|
The easiest protection against power failure is to put the @code{dump}
|
|
and @code{writertc} commands in the same place as the @code{offline}
|
|
command is issued to take @code{chronyd} offline; because @code{chronyd}
|
|
free-runs between online sessions, no parameters will change
|
|
significantly between going offline from the Internet and any power
|
|
failure.
|
|
|
|
A final point regards home computers which are left running for extended
|
|
periods and where it is desired to spin down the hard disc when it is
|
|
not in use (e.g. when not accessed for 15 minutes). @code{chronyd} has
|
|
been planned so it supports such operation; this is the reason why the
|
|
RTC tracking parameters are not saved to disc after every update, but
|
|
only when the user requests such a write, or during the shutdown
|
|
sequence. The only other facility that will generate periodic writes to
|
|
the disc is the @code{log rtc} facility in the configuration file; this
|
|
option should not be used if you want your disc to spin down.
|
|
|
|
@node Dial-up configuration
|
|
@subsection Typical configuration files.
|
|
|
|
To illustrate how a dial-up home computer might be configured, example
|
|
configuration files are shown in this section.
|
|
|
|
For the @file{@SYSCONFDIR@/chrony.conf} file, the following can be used as an
|
|
example.
|
|
|
|
@example
|
|
server foo.example.net maxdelay 0.4 offline
|
|
server bar.example.net maxdelay 0.4 offline
|
|
server baz.example.net maxdelay 0.4 offline
|
|
logdir /var/log/chrony
|
|
log statistics measurements tracking
|
|
driftfile @CHRONYVARDIR@/drift
|
|
keyfile @SYSCONFDIR@/chrony.keys
|
|
generatecommandkey
|
|
makestep 10 3
|
|
maxupdateskew 100.0
|
|
dumponexit
|
|
dumpdir @CHRONYVARDIR@
|
|
rtcfile @CHRONYVARDIR@/rtc
|
|
@end example
|
|
|
|
@code{pppd} is used for connecting to the internet. This runs two scripts
|
|
@file{/etc/ppp/ip-up} and @file{/etc/ppp/ip-down} when the link goes
|
|
online and offline respectively.
|
|
|
|
The relevant part of the @file{/etc/ppp/ip-up} file is
|
|
|
|
@example
|
|
@BINDIR@/chronyc -a online
|
|
@end example
|
|
|
|
and the relevant part of the @file{/etc/ppp/ip-down} script is
|
|
|
|
@example
|
|
@BINDIR@/chronyc -a -m offline dump writertc
|
|
@end example
|
|
|
|
To start @code{chronyd} during the boot sequence, the following
|
|
is in @file{/etc/rc.d/rc.local} (this is a Slackware system)
|
|
|
|
@example
|
|
if [ -f @SBINDIR@/chronyd -a -f @SYSCONFDIR@/chrony.conf ]; then
|
|
@SBINDIR@/chronyd -r -s
|
|
echo "Start chronyd"
|
|
fi
|
|
@end example
|
|
|
|
The placement of this command may be important on some systems. In
|
|
particular, @code{chronyd} may need to be started before any software
|
|
that depends on the system clock not jumping or moving backwards,
|
|
depending on the directives in @code{chronyd's} configuration file.
|
|
|
|
For the system shutdown, @code{chronyd} should receive a SIGTERM several
|
|
seconds before the final SIGKILL; the SIGTERM causes the measurement
|
|
histories and RTC information to be saved out.
|
|
@c }}}
|
|
@c {{{ S:Other config options
|
|
@node Configuration options overview
|
|
@section Other important configuration options
|
|
The most common option to include in the configuration file is the
|
|
@code{driftfile} option. One of the major tasks of @code{chronyd} is to
|
|
work out how fast or how slow the system clock runs relative to real
|
|
time - e.g. in terms of seconds gained or lost per day. Measurements
|
|
over a long period are usually required to refine this estimate to an
|
|
acceptable degree of accuracy. Therefore, it would be bad if
|
|
@code{chronyd} had to work the value out each time it is restarted,
|
|
because the system clock would not run so accurately whilst the
|
|
determination is taking place.
|
|
|
|
To avoid this problem, @code{chronyd} allows the gain or loss rate to be
|
|
stored in a file, which can be read back in when the program is
|
|
restarted. This file is called the drift file, and might typically be
|
|
stored in @file{@CHRONYVARDIR@/drift}. By specifying an option like the
|
|
following
|
|
|
|
@example
|
|
driftfile @CHRONYVARDIR@/drift
|
|
@end example
|
|
|
|
in the configuration file (@file{@SYSCONFDIR@/chrony.conf}), the drift file
|
|
facility will be activated.
|
|
@c }}}
|
|
@c }}}
|
|
@c {{{ Ch:Usage reference
|
|
@node Usage reference
|
|
@chapter Usage reference
|
|
|
|
@c {{{ Chapter top
|
|
@menu
|
|
* Starting chronyd:: Command line options for the daemon
|
|
* Configuration file:: Format of the configuration file
|
|
* Running chronyc:: The run-time configuration program
|
|
@end menu
|
|
@c }}}
|
|
@c {{{ S:Starting chronyd
|
|
@node Starting chronyd
|
|
@section Starting chronyd
|
|
If @code{chronyd} has been installed to its default location
|
|
@file{@SBINDIR@/chronyd}, starting it is simply a matter of
|
|
entering the command
|
|
|
|
@example
|
|
@SBINDIR@/chronyd
|
|
@end example
|
|
|
|
Information messages and warnings will be logged to syslog.
|
|
|
|
If no configuration commands are specified on the command line,
|
|
@code{chronyd} will read the commands from the configuration file
|
|
(default @file{@SYSCONFDIR@/chrony.conf}).
|
|
|
|
The command line options supported are as follows:
|
|
|
|
@table @code
|
|
@item -n
|
|
When run in this mode, the program will not detach itself from the
|
|
terminal.
|
|
@item -d
|
|
When run in this mode, the program will not detach itself from the
|
|
terminal, and all messages will be sent to the terminal instead of to
|
|
syslog. When @code{chronyd} was compiled with debugging support,
|
|
this option can be used twice to print also debugging messages.
|
|
@item -f <conf-file>
|
|
This option can be used to specify an alternate location for the
|
|
configuration file (default @file{@SYSCONFDIR@/chrony.conf}).
|
|
@item -r
|
|
This option will reload sample histories for each of the servers and refclocks being
|
|
used. These histories are created by using the @code{dump} command in
|
|
@code{chronyc}, or by setting the @code{dumponexit} directive in the
|
|
configuration file. This option is useful if you want to stop and
|
|
restart @code{chronyd} briefly for any reason, e.g. to install a new
|
|
version. However, it only makes sense on systems where the kernel can
|
|
maintain clock compensation whilst not under @code{chronyd's} control.
|
|
The only version where this happens so far is Linux. On other systems
|
|
this option should not be used.
|
|
@item -R
|
|
When this option is used, the @code{initstepslew} directive and the
|
|
@code{makestep} directive used with a positive limit will be ignored.
|
|
This option is useful when restarting @code{chronyd} and can be used
|
|
in conjunction with the `-r' option.
|
|
|
|
@item -s
|
|
This option will set the system clock from the computer's real-time
|
|
clock. This is analogous to supplying the `-s' flag to the
|
|
@file{/sbin/hwclock} program during the Linux boot sequence.
|
|
|
|
Support for real-time clocks is limited at present - the criteria are
|
|
described in the section on the @code{rtcfile} directive (@pxref{rtcfile
|
|
directive}).
|
|
|
|
If used in conjunction with the `-r' flag, @code{chronyd} will attempt
|
|
to preserve the old samples after setting the system clock from the real
|
|
time clock (RTC). This can be used to allow @code{chronyd} to perform long
|
|
term averaging of the gain or loss rate across system reboots, and is
|
|
useful for dial-up systems that are shut down when not in use. For this
|
|
to work well, it relies on @code{chronyd} having been able to determine
|
|
accurate statistics for the difference between the RTC and
|
|
system clock last time the computer was on.
|
|
|
|
If @code{chronyd} doesn't support the RTC on your computer or there is no RTC
|
|
installed, the system clock will be set with this option forward to the time of
|
|
the last modification of the drift file (specified by the @code{driftfile}
|
|
directive) to restore the system time at which @code{chronyd} was previously
|
|
stopped.
|
|
@item -u <user>
|
|
This option sets the name of the user to which will @code{chronyd} switch to
|
|
drop root privileges if compiled with Linux capabilities support (default
|
|
@code{@DEFAULT_USER@}).
|
|
@item -q
|
|
When run in this mode, @code{chronyd} will set the system clock once
|
|
and exit. It will not detach from the terminal.
|
|
@item -Q
|
|
This option is similar to `-q', but it will only print the offset and
|
|
not correct the clock.
|
|
@item -v
|
|
This option displays @code{chronyd's} version number to the terminal and
|
|
exits.
|
|
@item -P <priority>
|
|
This option will select the SCHED_FIFO real-time scheduler at the
|
|
specified priority (which must be between 0 and 100). This mode is
|
|
supported only on Linux.
|
|
@item -m
|
|
This option will lock chronyd into RAM so that it will never be paged
|
|
out. This mode is only supported on Linux.
|
|
@item -4
|
|
With this option hostnames will be resolved only to IPv4 addresses and only
|
|
IPv4 sockets will be created.
|
|
@item -6
|
|
With this option hostnames will be resolved only to IPv6 addresses and only
|
|
IPv6 sockets will be created.
|
|
@end table
|
|
|
|
On systems that support an @file{/etc/rc.local} file for starting
|
|
programs at boot time, @code{chronyd} can be started from there.
|
|
|
|
On systems with a System V style initialisation, a
|
|
suitable start/stop script might be as shown below. This might be
|
|
placed in the file @file{/etc/rc2.d/S83chrony}.
|
|
|
|
@example
|
|
@group
|
|
#!/bin/sh
|
|
# This file should have uid root, gid sys and chmod 744
|
|
#
|
|
|
|
killproc() @{ # kill the named process(es)
|
|
pid=`/usr/bin/ps -e |
|
|
/usr/bin/grep -w $1 |
|
|
/usr/bin/sed -e 's/^ *//' -e 's/ .*//'`
|
|
[ "$pid" != "" ] && kill $pid
|
|
@}
|
|
|
|
case "$1" in
|
|
|
|
'start')
|
|
if [ -f /opt/free/sbin/chronyd -a -f @SYSCONFDIR@/chrony.conf ]; then
|
|
/opt/free/sbin/chronyd
|
|
fi
|
|
;;
|
|
'stop')
|
|
killproc chronyd
|
|
;;
|
|
*)
|
|
echo "Usage: /etc/rc2.d/S83chrony @{ start | stop @}"
|
|
;;
|
|
esac
|
|
@end group
|
|
@end example
|
|
|
|
(In both cases, you may want to bear in mind that @code{chronyd} can
|
|
step the time when it starts. There may be other programs started at
|
|
boot time that could be upset by this, so you may need to consider the
|
|
ordering carefully. However, @code{chronyd} will need to start after
|
|
daemons providing services that it may require, e.g. the domain name
|
|
service.)
|
|
@c }}}
|
|
@c {{{ S:chronyd configuration file
|
|
@node Configuration file
|
|
@section The chronyd configuration file
|
|
@c {{{ section top
|
|
The configuration file is normally called @file{@SYSCONFDIR@/chrony.conf}; in
|
|
fact, this is the compiled-in default. However, other locations can be
|
|
specified with a command line option.
|
|
|
|
Each command in the configuration file is placed on a separate line.
|
|
The following sections describe each of the commands in turn. The
|
|
directives can occur in any order in the file and they are not
|
|
case-sensitive.
|
|
|
|
The configuration commands can also be specified directly on the
|
|
@code{chronyd} command line, each argument is parsed as a line and
|
|
the configuration file is ignored.
|
|
|
|
@menu
|
|
* comments in config file:: How to write a comment
|
|
* acquisitionport directive:: Set NTP client port
|
|
* allow directive:: Give access to NTP clients
|
|
* bindacqaddress directive:: Limit network interface used by NTP client
|
|
* bindaddress directive:: Limit network interface used by NTP server
|
|
* bindcmdaddress directive:: Limit network interface used for commands
|
|
* broadcast directive:: Make chronyd act as an NTP broadcast server
|
|
* clientloglimit directive:: Set client log memory limit
|
|
* cmdallow directive:: Give control access to chronyc on other computers
|
|
* cmddeny directive:: Deny control access to chronyc on other computers
|
|
* cmdport directive:: Set port to use for runtime commanding
|
|
* combinelimit directive:: Limit sources included in combining algorithm
|
|
* commandkey directive:: Set runtime command key
|
|
* corrtimeratio directive:: Set correction time ratio
|
|
* deny directive:: Deny access to NTP clients
|
|
* driftfile directive:: Specify location of file containing drift data
|
|
* dumpdir directive:: Specify directory for dumping measurements
|
|
* dumponexit directive:: Dump measurements when daemon exits
|
|
* fallbackdrift directive:: Specify fallback drift intervals
|
|
* generatecommandkey directive:: Generate command key automatically
|
|
* hwclockfile directive:: Specify location of hwclock's adjtime file
|
|
* include directive:: Include a configuration file
|
|
* initstepslew directive:: Trim the system clock on boot-up
|
|
* keyfile directive:: Specify location of file containing keys
|
|
* leapsecmode directive:: Select leap second handling mode
|
|
* leapsectz directive:: Read leap second data from tz database
|
|
* local directive:: Allow unsynchronised machine to act as server
|
|
* lock_all directive:: Require that chronyd be locked into RAM
|
|
* log directive:: Make daemon log certain sets of information
|
|
* logbanner directive:: Specify how often is banner written to log files
|
|
* logchange directive:: Generate syslog messages if large offsets occur
|
|
* logdir directive:: Specify directory for logging
|
|
* mailonchange directive:: Send email if a clock correction above a threshold occurs
|
|
* makestep directive:: Step system clock if large correction is needed
|
|
* manual directive:: Allow manual entry using chronyc's settime cmd
|
|
* maxchange directive:: Set maximum allowed offset
|
|
* maxclockerror directive:: Set maximum frequency error of local clock
|
|
* maxsamples directive:: Set maximum number of samples per source
|
|
* maxslewrate directive:: Set maximum slew rate
|
|
* maxupdateskew directive:: Stop bad estimates upsetting machine clock
|
|
* minsamples directive:: Set minimum number of samples per source
|
|
* minsources directive:: Set minimum number of selectable sources to update clock
|
|
* noclientlog directive:: Prevent chronyd from gathering data about clients
|
|
* peer directive:: Specify an NTP peer
|
|
* pidfile directive:: Specify the file where chronyd's pid is written
|
|
* pool directive:: Specify an NTP pool
|
|
* port directive:: Set NTP server port
|
|
* refclock directive:: Specify a reference clock
|
|
* reselectdist directive:: Set improvement in distance needed to reselect a source
|
|
* rtcautotrim directive:: Specify threshold at which RTC is trimmed automatically
|
|
* 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
|
|
* rtcsync directive:: Specify that RTC should be automatically synchronised by kernel
|
|
* sched_priority directive:: Require real-time scheduling and specify a priority for it
|
|
* server directive:: Specify an NTP server
|
|
* smoothtime directive:: Smooth served time to keep clients close together
|
|
* stratumweight directive:: Specify how important is stratum when selecting source
|
|
* tempcomp directive:: Specify temperature sensor and compensation coefficients
|
|
* user directive:: Specify user for dropping root privileges
|
|
|
|
@end menu
|
|
@c }}}
|
|
@c {{{ comments in config file
|
|
@node comments in config file
|
|
@subsection Comments in the configuration file
|
|
The configuration file may contain comment lines. A comment line is any line
|
|
that starts with zero or more spaces followed by any one of the following
|
|
characters:
|
|
@itemize
|
|
@item !
|
|
@item ;
|
|
@item #
|
|
@item %
|
|
@end itemize
|
|
Any line with this format will be ignored.
|
|
@c }}}
|
|
@c {{{ acquisitionport directive
|
|
@node acquisitionport directive
|
|
@subsection acquisitionport
|
|
By default, @code{chronyd} uses a separate client socket for each configured
|
|
server and their source port is chosen arbitrarily by the operating system.
|
|
However, you can use the @code{acquisitionport} directive to explicitly specify
|
|
a port and use only one socket (per IPv4/IPv6 address family) for all
|
|
configured servers. This may be useful for getting through firewalls. If set
|
|
to 0, the source port of the socket will be chosen arbitrarily.
|
|
|
|
It may be set to the same port as used by the NTP server (@pxref{port
|
|
directive}) to use only one socket for all NTP packets.
|
|
|
|
An example of the @code{acquisitionport} command is
|
|
|
|
@example
|
|
acquisitionport 1123
|
|
@end example
|
|
|
|
This would change the source port used for client requests to udp/1123. You
|
|
could then persuade the firewall administrator to let that port through.
|
|
@c }}}
|
|
@c {{{ allow
|
|
@node allow directive
|
|
@subsection allow
|
|
The @code{allow} command is used to designate a particular subnet from
|
|
which NTP clients are allowed to access the computer as an NTP server.
|
|
|
|
The default is that no clients are allowed access, i.e. @code{chronyd}
|
|
operates purely as an NTP client. If the @code{allow} directive is
|
|
used, @code{chronyd} will be both a client of its servers, and a server
|
|
to other clients.
|
|
|
|
Examples of use of the command are as follows:
|
|
|
|
@example
|
|
allow foo.example.net
|
|
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 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 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 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
|
|
illustrate the effect, consider the two examples
|
|
|
|
@example
|
|
allow 1.2.3.4
|
|
deny 1.2.3
|
|
allow 1.2
|
|
@end example
|
|
|
|
and
|
|
|
|
@example
|
|
allow 1.2.3.4
|
|
deny 1.2.3
|
|
allow all 1.2
|
|
@end example
|
|
|
|
In the first example, the effect is the same regardles of what order the
|
|
three directives are given in. So the 1.2.x.y subnet is allowed access,
|
|
except for the 1.2.3.x subnet, which is denied access, however the host
|
|
1.2.3.4 is allowed access.
|
|
|
|
In the second example, the @code{allow all 1.2} directives overrides the
|
|
effect of @emph{any} previous directive relating to a subnet within the
|
|
specified subnet. Within a configuration file this capability is
|
|
probably rather moot; however, it is of greater use for reconfiguration
|
|
at run-time via @code{chronyc} (@pxref{allow all command}).
|
|
|
|
Note, if the @code{initstepslew} directive (@pxref{initstepslew
|
|
directive}) is used in the configuration file, each of the computers
|
|
listed in that directive must allow client access by this computer for
|
|
it to work.
|
|
@c }}}
|
|
@c {{{ bindacqaddress
|
|
@node bindacqaddress directive
|
|
@subsection bindacqaddress
|
|
The @code{bindacqaddress} directive sets the network interface to which will
|
|
@code{chronyd} bind its NTP client sockets. The syntax is similar to the
|
|
@code{bindaddress} and @code{bindcmdaddress} directives.
|
|
|
|
For each of IPv4 and IPv6 protocols, only one @code{bindacqaddress}
|
|
directive can be specified.
|
|
@c }}}
|
|
@c {{{ bindaddress
|
|
@node bindaddress directive
|
|
@subsection bindaddress
|
|
The @code{bindaddress} directive allows you to restrict the network interface
|
|
to which @code{chronyd} will listen for NTP requests. This provides an
|
|
additional level of access restriction above that available through the
|
|
@code{deny} mechanism.
|
|
|
|
Suppose you have a local ethernet with addresses in the 192.168.1.0
|
|
subnet together with an internet connection. The ethernet interface's IP
|
|
address is 192.168.1.1. Suppose you want to block all access through the
|
|
internet connection. You could add the line
|
|
|
|
@example
|
|
bindaddress 192.168.1.1
|
|
@end example
|
|
|
|
to the configuration file.
|
|
|
|
For each of IPv4 and IPv6 protocols, only one @code{bindaddress} directive can
|
|
be specified. Therefore, it's not useful on computers which should serve NTP
|
|
on multiple network interfaces.
|
|
@c }}}
|
|
@c {{{ bindcmdaddress
|
|
@node bindcmdaddress directive
|
|
@subsection bindcmdaddress
|
|
The @code{bindcmdaddress} directive allows you to specify the network
|
|
interface to which @code{chronyd} will listen for command packets (issued by
|
|
@code{chronyc}). This provides an additional level of access restriction above
|
|
that available through @code{cmddeny} mechanism.
|
|
|
|
By default, @code{chronyd} binds to the loopback interface (with addresses
|
|
@code{127.0.0.1} and @code{::1}). This blocks all access except from
|
|
localhost. To listen for command packets on all interfaces, you can add the
|
|
lines
|
|
|
|
@example
|
|
bindcmdaddress 0.0.0.0
|
|
bindcmdaddress ::
|
|
@end example
|
|
|
|
to the configuration file.
|
|
|
|
For each of IPv4 and IPv6 protocols, only one @code{bindcmdaddress}
|
|
directive can be specified.
|
|
@c }}}
|
|
@c {{{ broadcast directive
|
|
@node broadcast directive
|
|
@subsection broadcast
|
|
The @code{broadcast} directive is used to declare a broadcast address to which
|
|
chronyd should send packets in NTP broadcast mode (i.e. make chronyd act as a
|
|
broadcast server). Broadcast clients on that subnet will be able to
|
|
synchronise.
|
|
|
|
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
|
|
port). In the second example, the destionation port is specified as 12123.
|
|
The first parameter in each case (30 or 60 respectively) is the interval in
|
|
seconds between broadcast packets being sent. The second parameter in each
|
|
case is the broadcast address to send the packet to. This should correspond to
|
|
the broadcast address of one of the network interfaces on the computer where
|
|
chronyd is running.
|
|
|
|
You can have more than 1 @code{broadcast} directive if you have more than 1
|
|
network interface onto which you wish to send NTP broadcast packets.
|
|
|
|
@code{chronyd} itself cannot currently act as a broadcast client; it must always be
|
|
configured as a point-to-point client by defining specific NTP servers and
|
|
peers. This broadcast server feature is intended for providing a time source
|
|
to other NTP software (e.g. various MS Windows clients).
|
|
|
|
If ntpd is used as the broadcast client, it will try to use a point-to-point
|
|
client/server NTP access to measure the round-trip delay. Thus, the broadcast
|
|
subnet should also be the subject of an @code{allow} directive (@pxref{allow
|
|
directive}).
|
|
@c }}}
|
|
@c {{{ clientloglimit
|
|
@node clientloglimit directive
|
|
@subsection clientloglimit
|
|
This directive specifies the maximum size of the memory allocated to
|
|
log client accesses. When the limit is reached, only information for
|
|
clients that have already been logged will be updated. If 0 is
|
|
specified, the memory size will be unlimited. The default is 524288
|
|
bytes.
|
|
|
|
An example of the use of this directive is
|
|
|
|
@example
|
|
clientloglimit 1048576
|
|
@end example
|
|
@c }}}
|
|
@c {{{ cmdallow
|
|
@node cmdallow directive
|
|
@subsection cmdallow
|
|
|
|
This is similar to the @code{allow} directive (@pxref{allow directive}), except
|
|
that it allows control access (rather than NTP client access) to a particular
|
|
subnet or host. (By 'control access' is meant that chronyc can be run on those
|
|
hosts and successfully connect to chronyd on this computer.)
|
|
|
|
The syntax is identical to the @code{allow} directive.
|
|
|
|
There is also a @code{cmdallow all} directive with similar behaviour to the
|
|
@code{allow all} directive (but applying to control access in this case, of
|
|
course).
|
|
|
|
Note that @code{chronyd} has to be configured with the @code{bindcmdaddress}
|
|
directive to not listen only on the loopback interface to actually allow remote
|
|
access.
|
|
@c }}}
|
|
@c {{{ cmddeny
|
|
@node cmddeny directive
|
|
@subsection cmddeny
|
|
|
|
This is similar to the @code{cmdallow} directive (@pxref{cmdallow directive}),
|
|
except that it denies control access to a particular subnet or host,
|
|
rather than allowing it.
|
|
|
|
The syntax is identical.
|
|
|
|
There is also a @code{cmddeny all} directive with similar behaviour to the
|
|
@code{cmdallow all} directive.
|
|
@c }}}
|
|
@c {{{ cmdport
|
|
@node cmdport directive
|
|
@subsection cmdport
|
|
|
|
The @code{cmdport} directive allows the port that is used for run-time
|
|
command and monitoring (via the program @code{chronyc}) to be altered
|
|
from its default (323/udp). If set to 0, @code{chronyd} will not open the
|
|
port, this is useful to disable the @code{chronyc} access completely.
|
|
|
|
An example shows the syntax
|
|
|
|
@example
|
|
cmdport 257
|
|
@end example
|
|
|
|
This would make @code{chronyd} use 257/udp as its command port.
|
|
(@code{chronyc} would need to be run with the @code{-p 257} switch to
|
|
inter-operate correctly).
|
|
@c }}}
|
|
@c {{{ combinelimit
|
|
@node combinelimit directive
|
|
@subsection combinelimit
|
|
When @code{chronyd} has multiple sources available for synchronization, it has
|
|
to select one source as the synchronization source. The measured offsets and
|
|
frequencies of the system clock relative to the other sources, however, can be
|
|
combined with the selected source to improve the accuracy of the system clock.
|
|
|
|
The @code{combinelimit} directive limits which sources are included in the
|
|
combining algorithm. Their synchronization distance has to be shorter than the
|
|
distance of the selected source multiplied by the value of the limit. Also,
|
|
their measured frequencies have to be close to the frequency of the selected
|
|
source.
|
|
|
|
By default, the limit is 3. Setting the limit to 0 effectively disables the
|
|
source combining algorithm and only the selected source will be used to
|
|
control the system clock.
|
|
|
|
The syntax is
|
|
|
|
@example
|
|
combinelimit <limit>
|
|
@end example
|
|
@c }}}
|
|
@c {{{ commandkey
|
|
@node commandkey directive
|
|
@subsection commandkey
|
|
The commandkey command is used to set the key number used for
|
|
authenticating user commands via the chronyc program at run time.
|
|
This allows certain actions of the chronyc program to be restricted to
|
|
administrators.
|
|
|
|
An example of the commandkey command is
|
|
|
|
@example
|
|
commandkey 20
|
|
@end example
|
|
|
|
By default, the key number is 0.
|
|
|
|
In the key file (see the keyfile command) there should be a line of
|
|
the form
|
|
|
|
@example
|
|
20 MD5 HEX:B028F91EA5C38D06C2E140B26C7F41EC
|
|
@end example
|
|
|
|
When running the chronyc program to perform run-time configuration,
|
|
the command
|
|
|
|
@example
|
|
password HEX:B028F91EA5C38D06C2E140B26C7F41EC
|
|
@end example
|
|
|
|
must be entered before any commands affecting the operation of the
|
|
daemon can be entered, or chronyc must be started with the `-a' option to run
|
|
the password command automatically.
|
|
@c }}}
|
|
@c {{{ corrtimeratio
|
|
@node corrtimeratio directive
|
|
@subsection corrtimeratio
|
|
When @code{chronyd} makes a time correction, it controls how quickly
|
|
the system clock is slewed (so far only on Linux). This rate
|
|
affects the frequency error of the system clock.
|
|
|
|
The @code{corrtimeratio} directive sets the ratio between the
|
|
duration in which the clock is slewed for an average correction
|
|
according to the source history and the interval in which the
|
|
corrections are done (usually the NTP polling interval). Corrections
|
|
larger than the average take less time and smaller corrections take
|
|
more time, the amount of the correction and the correction time are
|
|
inversely proportional.
|
|
|
|
Increasing @code{corrtimeratio} improves the overall frequency error
|
|
of the system clock, but increases the overall time error as the
|
|
corrections take longer.
|
|
|
|
By default, the ratio is set to 3, the time accuracy of the clock is
|
|
preferred over its frequency accuracy.
|
|
|
|
The syntax is
|
|
|
|
@example
|
|
corrtimeratio 100
|
|
@end example
|
|
|
|
The maximum allowed slew rate can be set by the @code{maxslewrate}
|
|
directive (@pxref{maxslewrate directive}. The current remaining
|
|
correction is shown in the @code{tracking} report (@pxref{tracking
|
|
command}) as the @code{System time} value.
|
|
@c }}}
|
|
@c {{{ deny
|
|
@node deny directive
|
|
@subsection deny
|
|
|
|
This is similar to the @code{allow} directive (@pxref{allow directive}),
|
|
except that it denies NTP client access to a particular subnet or host,
|
|
rather than allowing it.
|
|
|
|
The syntax is identical.
|
|
|
|
There is also a @code{deny all} directive with similar behaviour to the
|
|
@code{allow all} directive.
|
|
@c }}}
|
|
@c {{{ driftfile
|
|
@node driftfile directive
|
|
@subsection driftfile
|
|
One of the main activities of the @code{chronyd} program is to work out
|
|
the rate at which the system clock gains or loses time relative to real
|
|
time.
|
|
|
|
Whenever @code{chronyd} computes a new value of the gain/loss rate, it
|
|
is desirable to record it somewhere. This allows @code{chronyd} to
|
|
begin compensating the system clock at that rate whenever it is
|
|
restarted, even before it has had a chance to obtain an equally good
|
|
estimate of the rate during the new run. (This process may take many
|
|
minutes, at least).
|
|
|
|
The driftfile command allows a file to be specified into which
|
|
@code{chronyd} can store the rate information. Two parameters are
|
|
recorded in the file. The first is the rate at which the system clock
|
|
gains or loses time, expressed in parts per million, with gains
|
|
positive. Therefore, a value of 100.0 indicates that when the system
|
|
clock has advanced by a second, it has gained 100 microseconds on
|
|
reality (so the true time has only advanced by 999900 microseconds).
|
|
The second is an estimate of the error bound around the first value in
|
|
which the true rate actually lies.
|
|
|
|
An example of the driftfile command is
|
|
|
|
@example
|
|
driftfile @CHRONYVARDIR@/drift
|
|
@end example
|
|
@c }}}
|
|
@c {{{ dumpdir
|
|
@node dumpdir directive
|
|
@subsection dumpdir
|
|
To compute the rate of gain or loss of time, @code{chronyd} has to store
|
|
a measurement history for each of the time sources it uses.
|
|
|
|
Certain systems (so far only Linux) have operating system support for
|
|
setting the rate of gain or loss to compensate for known errors. (On
|
|
other systems, @code{chronyd} must simulate such a capability by
|
|
periodically slewing the system clock forwards or backwards by a
|
|
suitable amount to compensate for the error built up since the previous
|
|
slew).
|
|
|
|
For such systems, it is possible to save the measurement history across
|
|
restarts of @code{chronyd} (assuming no changes are made to the system
|
|
clock behaviour whilst it is not running). If this capability is to be
|
|
used (via the dumponexit command in the configuration file, or the dump
|
|
command in chronyc), the dumpdir command should be used to define the
|
|
directory where the measurement histories are saved.
|
|
|
|
An example of the command is
|
|
|
|
@example
|
|
dumpdir @CHRONYVARDIR@
|
|
@end example
|
|
|
|
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/lib/chrony/1.2.3.4.dat}.
|
|
@c }}}
|
|
@c {{{ dumponexit
|
|
@node dumponexit directive
|
|
@subsection dumponexit
|
|
If this command is present, it indicates that @code{chronyd} should save
|
|
the measurement history for each of its time sources recorded whenever
|
|
the program exits. (See the dumpdir command above).
|
|
@c }}}
|
|
@c {{{ fallbackdrift
|
|
@node fallbackdrift directive
|
|
@subsection fallbackdrift
|
|
Fallback drifts are long-term averages of the system clock drift
|
|
calculated over exponentially increasing intervals. They are used
|
|
when the clock is no longer synchronised to avoid quickly drifting
|
|
away from true time if there was a short-term deviation in the drift
|
|
before the synchronisation was lost.
|
|
|
|
The directive specifies the minimum and maximum interval since last
|
|
clock update to switch between fallback drifts. They are defined as a
|
|
power of 2 (in seconds). The syntax is as follows
|
|
|
|
@example
|
|
fallbackdrift 16 19
|
|
@end example
|
|
|
|
In this example, the minimum interval is 16 (18 hours) and maximum
|
|
interval is 19 (6 days). The system clock frequency will be set to
|
|
the first fallback 18 hours after last clock update, to the
|
|
second after 36 hours, etc. This might be a good setting to cover
|
|
daily and weekly temperature fluctuations.
|
|
|
|
By default (or if the specified maximum or minimum is 0), no fallbacks
|
|
are used and the clock frequency changes only with new measurements from
|
|
NTP, reference clocks or manual input.
|
|
@c }}}
|
|
@c {{{ generatecommandkey
|
|
@node generatecommandkey directive
|
|
@subsection generatecommandkey
|
|
With this directive, if the command key is not found on start in the file
|
|
specified by the @code{keyfile} directive, @code{chronyd} will generate a new
|
|
command key from the /dev/urandom file and write it to the key file.
|
|
|
|
The generated key will use SHA1 if @code{chronyd} is compiled with the support,
|
|
otherwise MD5 will be used.
|
|
@c }}}
|
|
@c {{{ hwclockfile
|
|
@node hwclockfile directive
|
|
@subsection hwclockfile
|
|
The @code{hwclockfile} directive sets the location of the adjtime file which is
|
|
used by the @file{/sbin/hwclock} program. With this directive, @code{chronyd}
|
|
will parse the file to find out if the RTC keeps local time or UTC. It
|
|
overrides the @code{rtconutc} directive (@pxref{rtconutc directive}).
|
|
|
|
An example of the command is
|
|
|
|
@example
|
|
hwclockfile /etc/adjtime
|
|
@end example
|
|
@c }}}
|
|
@c {{{ include
|
|
@node include directive
|
|
@subsection include
|
|
The @code{include} directive includes a specified configuration file.
|
|
This is useful when maintaining configuration on multiple hosts to
|
|
keep the differences in a separate file.
|
|
|
|
@example
|
|
include @SYSCONFDIR@/chrony/local.conf
|
|
@end example
|
|
@c }}}
|
|
@c {{{ initstepslew
|
|
@node initstepslew directive
|
|
@subsection initstepslew
|
|
In normal operation, @code{chronyd} slews the time when it needs to
|
|
adjust the system clock. For example, to correct a system clock which
|
|
is 1 second slow, @code{chronyd} slightly increases the amount by which the
|
|
system clock is advanced on each clock interrupt, until the error is
|
|
removed. (Actually, this is done by calling the @code{adjtime()} or
|
|
similar system function which does it for us.) Note that at no time
|
|
does time run backwards with this method.
|
|
|
|
On most Unix systems it is not desirable to step the system clock,
|
|
because many programs rely on time advancing monotonically forwards.
|
|
|
|
When the @code{chronyd} daemon is initially started, it is possible that the
|
|
system clock is considerably in error. Attempting to correct such an
|
|
error by slewing may not be sensible, since it may take several hours
|
|
to correct the error by this means.
|
|
|
|
The purpose of the @code{initstepslew} directive is to allow @code{chronyd} to
|
|
make a rapid measurement of the system clock error at boot time, and to
|
|
correct the system clock by stepping before normal operation begins.
|
|
Since this would normally be performed only at an appropriate point in
|
|
the system boot sequence, no other software should be adversely affected
|
|
by the step.
|
|
|
|
If the correction required is less than a specified threshold, a slew is
|
|
used instead. This makes it easier to restart @code{chronyd} whilst the
|
|
system is in normal operation.
|
|
|
|
The @code{initstepslew} directive takes a threshold and a list of NTP
|
|
servers as arguments. Each of the servers
|
|
is rapidly polled several times, and a majority voting mechanism used to
|
|
find the most likely range of system clock error that is present. A
|
|
step (or slew) is applied to the system clock to correct this error.
|
|
@code{chronyd} then enters its normal operating mode.
|
|
|
|
An example of use of the command is
|
|
|
|
@example
|
|
initstepslew 30 foo.example.net bar.example.net
|
|
@end example
|
|
|
|
where 2 NTP servers are used to make the measurement. The @code{30}
|
|
indicates that if the system's error is found to be 30 seconds or less,
|
|
a slew will be used to correct it; if the error is above 30 seconds, a
|
|
step will be used.
|
|
|
|
The @code{initstepslew} directive can also be used in an isolated LAN
|
|
environment, where the clocks are set manually. The most stable
|
|
computer is chosen as the master, and the other computers are slaved to
|
|
it. If each of the slaves is configured with the local option (see
|
|
below), the master can be set up with an @code{initstepslew} directive
|
|
which references some or all of the slaves. Then, if the master machine
|
|
has to be rebooted, the slaves can be relied on to 'flywheel' the time
|
|
for the master.
|
|
|
|
The @code{initstepslew} directive is functionally similar to a
|
|
combination of the @code{makestep} and @code{server} directives with
|
|
the @code{iburst} option. The main difference is that the
|
|
@code{initstepslew} servers are used only before normal operation
|
|
begins and that the foreground @code{chronyd} process waits for
|
|
@code{initstepslew} to finish before exiting. This is useful to
|
|
prevent programs started in the boot sequence after @code{chronyd}
|
|
from reading the clock before it's stepped.
|
|
@c }}}
|
|
@c {{{ keyfile
|
|
@node keyfile directive
|
|
@subsection keyfile
|
|
This command is used to specify the location of the file containing
|
|
ID/key pairs for the following 2 uses:
|
|
|
|
@itemize @bullet
|
|
@item Authentication of NTP packets.
|
|
@item Authentication of administrator commands entered via chronyc.
|
|
@end itemize
|
|
|
|
The format of the command is shown in the example below
|
|
|
|
@example
|
|
keyfile @SYSCONFDIR@/chrony.keys
|
|
@end example
|
|
|
|
The argument is simply the name of the file containing the ID/key
|
|
pairs. The format of the file is shown below
|
|
|
|
@example
|
|
10 tulip
|
|
11 hyacinth
|
|
20 MD5 ASCII:crocus
|
|
25 SHA1 HEX:1dc764e0791b11fa67efc7ecbc4b0d73f68a070c
|
|
...
|
|
@end example
|
|
|
|
Each line consists of an ID, a name of authentication hash function (optional)
|
|
and a password. The ID can be any unsigned integer in the range 0 through
|
|
2**32-1, but ID of 0 can be used only for the command key and not for the NTP
|
|
authentication. The hash function is MD5 by default, depending on how was
|
|
@code{chronyd} compiled other allowed hash functions may be SHA1, SHA256,
|
|
SHA384, SHA512, RMD128, RMD160, RMD256, RMD320, TIGER and WHIRLPOOL. The
|
|
password can be encoded as a string of characters not containing a space with
|
|
optional @code{ASCII:} prefix or as a hexadecimal number with @code{HEX:}
|
|
prefix.
|
|
|
|
The password is used with the hash function to generate and verify a message
|
|
authentication code (MAC) in NTP and command packets.
|
|
For maximum security, it's recommended to use SHA1 or stronger hash function.
|
|
The passwords should be random and they should be as long as the output size of
|
|
the configured hash function, e.g. 160 bits with SHA1.
|
|
|
|
The ID for the chronyc authentication key is specified with the commandkey
|
|
command (see earlier). The command key can be generated automatically on
|
|
start with the @code{generatecommandkey} directive.
|
|
@c }}}
|
|
@c {{{ leapsecmode
|
|
@node leapsecmode directive
|
|
@subsection leapsecmode
|
|
This directive selects how @code{chronyd} handles leap seconds. The Unix time
|
|
doesn't include leap seconds. When a leap second is applied to UTC, the system
|
|
clock is off by one second and it needs to be corrected.
|
|
|
|
There are four options:
|
|
|
|
@table @code
|
|
@item system
|
|
The kernel steps the system clock backwards by one second at 0:00:00 UTC
|
|
(before correction) when leap second is inserted or steps forward by one second
|
|
at 23:59:59 UTC when leap second is deleted. This is the default mode when the
|
|
system driver supports leap seconds (currently Linux only).
|
|
@item step
|
|
This is similar to the system mode, except the clock is stepped by
|
|
@code{chronyd} instead of the kernel. This is the default mode when the system
|
|
driver doesn't support leap seconds.
|
|
@item slew
|
|
The clock is corrected by slew starting at 0:00:00 UTC when leap second is
|
|
inserted or 23:59:59 UTC when leap second is deleted. This may be preferred
|
|
over the system or step mode when applications running on the system are
|
|
sensitive to jumps in the system time and it's acceptable that the clock will
|
|
be off for a longer time. On Linux with the default @code{maxslewrate} the
|
|
correction takes 12 seconds. Note that unless the @code{smoothtime} directive
|
|
is used (@pxref{smoothtime directive}), there will still be a jump in the time
|
|
that @code{chronyd} serves to NTP clients. With the @code{smoothtime}
|
|
directive, the leap second status will not be passed to NTP clients and the
|
|
leap second will be "smeared" instead.
|
|
@item ignore
|
|
No correction is applied to the clock for the leap second. The clock will be
|
|
corrected later in normal operation when new measurements are made and the
|
|
estimated offset includes the one second error.
|
|
@end table
|
|
|
|
An example of the command is
|
|
|
|
@example
|
|
leapsecmode slew
|
|
@end example
|
|
|
|
An example enabling the leap smear for NTP clients with the @code{smoothtime}
|
|
directive could be
|
|
|
|
@example
|
|
leapsecmode slew
|
|
smoothtime 400 0.001
|
|
@end example
|
|
|
|
With this configuration the NTP clients would not know there was any leap
|
|
second. The server time they follow would be slowly corrected in about 16
|
|
hours after the leap second was applied to UTC. This configuration should not
|
|
be used if the clients poll also other NTP servers, because they could reject
|
|
this server as a falseticker or could fail to select a source completely.
|
|
@c }}}
|
|
@c {{{ leapsectz
|
|
@node leapsectz directive
|
|
@subsection leapsectz
|
|
This directive is used to set the name of the timezone in the system
|
|
tz database which @code{chronyd} can use to find out when will the
|
|
next leap second occur. It will periodically check if the times
|
|
23:59:59 and 23:59:60 are valid on Jun 30 and Dec 31 in the timezone.
|
|
A useful timezone is @code{right/UTC}.
|
|
This is mainly useful with reference clocks which don't provide the
|
|
leap second information. It is not necessary to restart
|
|
@code{chronyd} if the tz database is updated with a new leap second at
|
|
least 12 hours before the event.
|
|
|
|
An example of the command is
|
|
|
|
@example
|
|
leapsectz right/UTC
|
|
@end example
|
|
|
|
The following shell command verifies that the timezone contains leap
|
|
seconds and can be used with this directive
|
|
|
|
@example
|
|
$ TZ=right/UTC date -d 'Dec 31 2008 23:59:60'
|
|
Wed Dec 31 23:59:60 UTC 2008
|
|
@end example
|
|
|
|
@c }}}
|
|
@c {{{ local
|
|
@node local directive
|
|
@subsection local
|
|
The local keyword is used to allow @code{chronyd} to appear synchronised
|
|
to real time (from the viewpoint of clients polling it), even if it has
|
|
no current synchronisation source.
|
|
|
|
This option is normally used on computers in an isolated network,
|
|
where several computers are required to synchronise to one other, this
|
|
being the "master" which is kept vaguely in line with real time by
|
|
manual input.
|
|
|
|
An example of the command is
|
|
|
|
@example
|
|
local stratum 10
|
|
@end example
|
|
|
|
The value 10 may be substituted with other values in the range 1
|
|
through 15. Stratum 1 indicates a computer that has a true real-time
|
|
reference directly connected to it (e.g. GPS, atomic clock etc)
|
|
– such computers are expected to be very close to real time.
|
|
Stratum 2 computers are those which have a stratum 1 server; stratum 3
|
|
computers have a stratum 2 server and so on.
|
|
|
|
A large value of 10 indicates that the clock is so many hops away from
|
|
a reference clock that its time is fairly unreliable. Put another
|
|
way, if the computer ever has access to another computer which is
|
|
ultimately synchronised to a reference clock, it will almost certainly
|
|
be at a stratum less than 10. Therefore, the choice of a high value
|
|
like 10 for the local command prevents the machine's own time from
|
|
ever being confused with real time, were it ever to leak out to
|
|
clients that have visibility of real servers.
|
|
@c }}}
|
|
@c {{{ lock_all
|
|
@node lock_all directive
|
|
@subsection lock_all
|
|
|
|
The @code{lock_all} directive will lock chronyd into RAM so that it
|
|
will never be paged out. This mode is only supported on Linux. This
|
|
directive uses the Linux mlockall() system call to prevent @code{chronyd}
|
|
from ever being swapped out. This should result in lower and more
|
|
consistent latency. It should not have significant impact on
|
|
performance as @code{chronyd's} memory usage is modest. The mlockall man
|
|
page has more details.
|
|
@c }}}
|
|
@c {{{ log
|
|
@node log directive
|
|
@subsection log
|
|
@c {{{ section top
|
|
The log command indicates that certain information is to be logged.
|
|
|
|
@table @code
|
|
@item measurements
|
|
This option logs the raw NTP measurements and related information to a
|
|
file called measurements.log.
|
|
|
|
@item statistics
|
|
This option logs information about the regression processing to a file
|
|
called statistics.log.
|
|
|
|
@item tracking
|
|
This option logs changes to the estimate of the system's gain or loss
|
|
rate, and any slews made, to a file called tracking.log.
|
|
|
|
@item rtc
|
|
This option logs information about the system's real-time clock.
|
|
|
|
@item refclocks
|
|
This option logs the raw and filtered reference clock measurements to
|
|
a file called refclocks.log.
|
|
@item tempcomp
|
|
This option logs the temperature measurements and system rate
|
|
compensations to a file called tempcomp.log.
|
|
@end table
|
|
|
|
The files are written to the directory specified by the logdir
|
|
command.
|
|
|
|
An example of the command is
|
|
|
|
@example
|
|
log measurements statistics tracking
|
|
@end example
|
|
|
|
@menu
|
|
* measurements log:: The format of the measurements log
|
|
* statistics log:: The format of the statistics log
|
|
* tracking log:: The format of the tracking log
|
|
* RTC log:: The format of the RTC log
|
|
* refclocks log:: The format of the refclocks log
|
|
* tempcomp log:: The format of the tempcomp log
|
|
@end menu
|
|
@c }}}
|
|
@c {{{ measurements.log
|
|
@node measurements log
|
|
@subsubsection Measurements log file format
|
|
|
|
An example line (which actually appears as a single line in the file)
|
|
from the measurements log file is shown below.
|
|
|
|
@example
|
|
2014-10-13 05:40:50 158.152.1.76 N 2 111 111 1111 10 10 1.0 \
|
|
-4.966e-03 2.296e-01 1.577e-05 1.615e-01 7.446e-03
|
|
@end example
|
|
|
|
The columns are as follows (the quantities in square brackets are the
|
|
values from the example line above) :
|
|
|
|
@enumerate 1
|
|
@item
|
|
Date [2014-10-13]
|
|
@item
|
|
Hour:Minute:Second [05:40:50]. Note that the date/time pair is
|
|
expressed in UTC, not the local time zone.
|
|
@item
|
|
IP address of server/peer from which measurement comes [158.152.1.76]
|
|
@item
|
|
Leap status (@code{N} means normal, @code{+} means that the last minute
|
|
of the current month has 61 seconds, @code{-} means that the last minute
|
|
of the month has 59 seconds, @code{?} means the remote computer is not
|
|
currently synchronised.) [N]
|
|
@item
|
|
Stratum of remote computer. [2]
|
|
@item
|
|
RFC 5905 tests 1 through 3 (1=pass, 0=fail) [111]
|
|
@item
|
|
RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111]
|
|
@item
|
|
Tests for maximum delay, maximum delay ratio and maximum delay dev ratio,
|
|
against defined parameters, and a test for synchronisation loop
|
|
(1=pass, 0=fail) [1111]
|
|
@item
|
|
Local poll [10]
|
|
@item
|
|
Remote poll [10]
|
|
@item
|
|
`Score' (an internal score within each polling level used to decide when
|
|
to increase or decrease the polling level. This is adjusted based on number
|
|
of measurements currently being used for the regression algorithm). [1.0]
|
|
@item
|
|
The estimated local clock error (`theta' in RFC 5905). Positive
|
|
indicates that the local clock is slow of the remote source. [-4.966e-03].
|
|
@item
|
|
The peer delay (`delta' in RFC 5905). [2.296e-01]
|
|
@item
|
|
The peer dispersion (`epsilon' in RFC 5905). [1.577e-05]
|
|
@item
|
|
The root delay (`DELTA' in RFC 5905). [1.615e-01]
|
|
@item
|
|
The root dispersion (`EPSILON' in RFC 5905). [7.446e-03]
|
|
@end enumerate
|
|
|
|
A banner is periodically written to the log file to indicate the
|
|
meanings of the columns.
|
|
@c }}}
|
|
@c {{{ statistics.log
|
|
@node statistics log
|
|
@subsubsection Statistics log file format
|
|
|
|
An example line (which actually appears as a single line in the file)
|
|
from the statistics log file is shown below.
|
|
|
|
@example
|
|
1998-07-22 05:40:50 158.152.1.76 6.261e-03 -3.247e-03 \
|
|
2.220e-03 1.874e-06 1.080e-06 7.8e-02 16 0 8
|
|
@end example
|
|
|
|
The columns are as follows (the quantities in square brackets are the
|
|
values from the example line above) :
|
|
|
|
@enumerate 1
|
|
@item
|
|
Date [1998-07-22]
|
|
@item
|
|
Hour:Minute:Second [05:40:50]. Note that the date/time pair is
|
|
expressed in UTC, not the local time zone.
|
|
@item
|
|
IP address of server/peer from which measurement comes [158.152.1.76]
|
|
@item
|
|
The estimated standard deviation of the measurements from the source (in
|
|
seconds). [6.261e-03]
|
|
@item
|
|
The estimated offset of the source (in seconds, positive means the local
|
|
clock is estimated to be fast, in this case). [-3.247e-03]
|
|
@item
|
|
The estimated standard deviation of the offset estimate (in
|
|
seconds). [2.220e-03]
|
|
@item
|
|
The estimated rate at which the local clock is gaining or losing time
|
|
relative to the source (in seconds per second, positive means the local
|
|
clock is gaining). This is relative to the compensation currently being
|
|
applied to the local clock, @emph{not} to the local clock without any
|
|
compensation. [1.874e-06]
|
|
@item
|
|
The estimated error in the rate value (in seconds per
|
|
second). [1.080e-06].
|
|
@item
|
|
The ration of |old_rate - new_rate| / old_rate_error. Large values
|
|
indicate the statistics are not modelling the source very well. [7.8e-02]
|
|
@item
|
|
The number of measurements currently being used for the regression
|
|
algorithm. [16]
|
|
@item
|
|
The new starting index (the oldest sample has index 0; this is the
|
|
method used to prune old samples when it no longer looks like the
|
|
measurements fit a linear model). [0, i.e. no samples discarded this
|
|
time]
|
|
@item
|
|
The number of runs. The number of runs of regression residuals with the
|
|
same sign is computed. If this is too small it indicates that the
|
|
measurements are no longer represented well by a linear model and that
|
|
some older samples need to be discarded. The number of runs for the
|
|
data that is being retained is tabulated. Values of approximately half
|
|
the number of samples are expected. [8]
|
|
@end enumerate
|
|
|
|
A banner is periodically written to the log file to indicate the
|
|
meanings of the columns.
|
|
@c }}}
|
|
@c {{{ tracking.log
|
|
@node tracking log
|
|
@subsubsection Tracking log file format
|
|
|
|
An example line (which actually appears as a single line in the file)
|
|
from the tracking log file is shown below.
|
|
|
|
@example
|
|
2012-02-23 05:40:50 158.152.1.76 3 340.529 1.606 1.046e-03 N \
|
|
4 6.849e-03 -4.670e-04
|
|
@end example
|
|
|
|
The columns are as follows (the quantities in square brackets are the
|
|
values from the example line above) :
|
|
|
|
@enumerate 1
|
|
@item
|
|
Date [2012-02-03]
|
|
@item
|
|
Hour:Minute:Second [05:40:50]. Note that the date/time pair is
|
|
expressed in UTC, not the local time zone.
|
|
@item
|
|
The IP address of the server/peer to which the local system is
|
|
synchronised. [158.152.1.76]
|
|
@item
|
|
The stratum of the local system. [3]
|
|
@item
|
|
The local system frequency (in ppm, positive means the local system runs
|
|
fast of UTC). [340.529]
|
|
@item
|
|
The error bounds on the frequency (in ppm) [1.606]
|
|
@item
|
|
The estimated local offset at the epoch (which is rapidly corrected by
|
|
slewing the local clock. (In seconds, positive indicates the local
|
|
system is fast of UTC). [1.046e-3]
|
|
@item
|
|
Leap status (@code{N} means normal, @code{+} means that the last minute
|
|
of this month has 61 seconds, @code{-} means that the last minute of the month
|
|
has 59 seconds, @code{?} means the clock is not currently synchronised.) [N]
|
|
@item
|
|
The number of combined sources. [4]
|
|
@item
|
|
The estimated standard deviation of the combined offset (in seconds).
|
|
[6.849e-03]
|
|
@item
|
|
The remaining offset correction from the previous update (in seconds, positive
|
|
means the system clock is slow of UTC). [-4.670e-04]
|
|
@end enumerate
|
|
|
|
A banner is periodically written to the log file to indicate the
|
|
meanings of the columns.
|
|
@c }}}
|
|
@c {{{ rtc.log
|
|
@node RTC log
|
|
@subsubsection Real-time clock log file format
|
|
|
|
An example line (which actually appears as a single line in the file)
|
|
from the measurements log file is shown below.
|
|
|
|
@example
|
|
1998-07-22 05:40:50 -0.037360 1 -0.037434\
|
|
-37.948 12 5 120
|
|
@end example
|
|
|
|
The columns are as follows (the quantities in square brackets are the
|
|
values from the example line above) :
|
|
|
|
@enumerate 1
|
|
@item
|
|
Date [1998-07-22]
|
|
@item
|
|
Hour:Minute:Second [05:40:50]. Note that the date/time pair is
|
|
expressed in UTC, not the local time zone.
|
|
@item
|
|
The measured offset between the system's real time clock and the system
|
|
(@code{gettimeofday()}) time. In seconds, positive indicates that the
|
|
RTC is fast of the system time. [-0.037360].
|
|
@item
|
|
Flag indicating whether the regression has produced valid
|
|
coefficients. (1 for yes, 0 for no). [1]
|
|
@item
|
|
Offset at the current time predicted by the regression process. A large
|
|
difference between this value and the measured offset tends to indicate
|
|
that the measurement is an outlier with a serious measurement
|
|
error. [-0.037434].
|
|
@item
|
|
The rate at which the RTC is losing or gaining time relative to the
|
|
system clock. In ppm, with positive indicating that the RTC is gaining
|
|
time. [-37.948]
|
|
@item
|
|
The number of measurements used in the regression. [12]
|
|
@item
|
|
The number of runs of regression residuals of the same sign. Low values
|
|
indicate that a straight line is no longer a good model of the measured
|
|
data and that older measurements should be discarded. [5]
|
|
@item
|
|
The measurement interval used prior to the measurement being made (in
|
|
seconds). [120]
|
|
@end enumerate
|
|
|
|
A banner is periodically written to the log file to indicate the
|
|
meanings of the columns.
|
|
@c }}}
|
|
@c {{{ refclocks.log
|
|
@node refclocks log
|
|
@subsubsection Refclocks log file format
|
|
|
|
An example line (which actually appears as a single line in the file)
|
|
from the refclocks log file is shown below.
|
|
|
|
@example
|
|
2009-11-30 14:33:27.000000 PPS2 7 N 1 4.900000e-07 -6.741777e-07 1.000e-06
|
|
@end example
|
|
|
|
The columns are as follows (the quantities in square brackets are the
|
|
values from the example line above) :
|
|
|
|
@enumerate 1
|
|
@item
|
|
Date [2009-11-30]
|
|
@item
|
|
Hour:Minute:Second.Microsecond [14:33:27.000000]. Note that the
|
|
date/time pair is expressed in UTC, not the local time zone.
|
|
@item
|
|
Reference ID of refclock from which measurement comes. [PPS2]
|
|
@item
|
|
Sequence number of driver poll within one polling interval for raw
|
|
samples, or @code{-} for filtered samples. [7]
|
|
@item
|
|
Leap status (@code{N} means normal, @code{+} means that the last minute
|
|
of the current month has 61 seconds, @code{-} means that the last minute
|
|
of the month has 59 seconds). [N]
|
|
@item
|
|
Flag indicating whether the sample comes from PPS source. (1 for yes,
|
|
0 for no, or @code{-} for filtered sample). [1]
|
|
@item
|
|
Local clock error measured by refclock driver, or @code{-} for
|
|
filtered sample. [4.900000e-07]
|
|
@item
|
|
Local clock error with applied corrections. Positive indicates
|
|
that the local clock is slow. [-6.741777e-07]
|
|
@item
|
|
Assumed dispersion of the sample. [1.000e-06]
|
|
@end enumerate
|
|
|
|
A banner is periodically written to the log file to indicate the
|
|
meanings of the columns.
|
|
@c }}}
|
|
@c {{{ tempcomp.log
|
|
@node tempcomp log
|
|
@subsubsection Tempcomp log file format
|
|
|
|
An example line (which actually appears as a single line in the file)
|
|
from the tempcomp log file is shown below.
|
|
|
|
@example
|
|
2010-04-19 10:39:48 2.8000e+04 3.6600e-01
|
|
@end example
|
|
|
|
The columns are as follows (the quantities in square brackets are the
|
|
values from the example line above) :
|
|
|
|
@enumerate 1
|
|
@item
|
|
Date [2010-04-19]
|
|
@item
|
|
Hour:Minute:Second [10:39:48]. Note that the
|
|
date/time pair is expressed in UTC, not the local time zone.
|
|
@item
|
|
Temperature read from tempcomp file. [2.8000e+04]
|
|
@item
|
|
Applied compensation in ppm, positive means the system clock is
|
|
running faster than it would be without the compensation. [3.6600e-01]
|
|
@end enumerate
|
|
|
|
A banner is periodically written to the log file to indicate the
|
|
meanings of the columns.
|
|
@c }}}
|
|
@c }}}
|
|
@c {{{ logbanner
|
|
@node logbanner directive
|
|
@subsection logbanner
|
|
A banner is periodically written to the log files enabled by the
|
|
@code{log} directive to indicate the meanings of the columns.
|
|
|
|
The @code{logbanner} directive specifies after how many entries in the
|
|
log file should be the banner written. The default is 32, and 0 can be
|
|
used to disable it entirely.
|
|
@c }}}
|
|
@c {{{ logchange
|
|
@node logchange directive
|
|
@subsection logchange
|
|
This directive forces @code{chronyd} to send a message to syslog if it
|
|
makes a system clock adjustment larger than a threshold value. An
|
|
example of use is
|
|
|
|
@example
|
|
logchange 0.5
|
|
@end example
|
|
|
|
which would cause a syslog message to be generated a system clock error
|
|
of over 0.5 seconds starts to be compensated.
|
|
|
|
Clock errors detected either via NTP packets or via timestamps entered
|
|
via the @code{settime} command of @code{chronyc} are logged.
|
|
|
|
This directive assumes that syslog messages are appearing where somebody
|
|
can see them. This allows that person to see if a large error has
|
|
arisen, e.g. because of a fault, or because of faulty timezone handling,
|
|
for example when summer time (daylight saving) starts or ends.
|
|
@c }}}
|
|
@c {{{ logdir
|
|
@node logdir directive
|
|
@subsection logdir
|
|
This directive allows the directory where log files are written to be
|
|
specified.
|
|
|
|
An example of the use of this directive is
|
|
|
|
@example
|
|
logdir /var/log/chrony
|
|
@end example
|
|
@c }}}
|
|
@c {{{ mailonchange
|
|
@node mailonchange directive
|
|
@subsection mailonchange
|
|
This directive defines an email address to which mail should be sent if
|
|
chronyd applies a correction exceeding a particular threshold to the
|
|
system clock.
|
|
|
|
An example of use of this directive is
|
|
|
|
@example
|
|
mailonchange root@@localhost 0.5
|
|
@end example
|
|
|
|
This would send a mail message to root if a change of more than 0.5
|
|
seconds were applied to the system clock.
|
|
@c }}}
|
|
@c {{{ makestep
|
|
@node makestep directive
|
|
@subsection makestep
|
|
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 may be so far adrift that this
|
|
slewing process would take a very long time to correct the system clock.
|
|
|
|
This directive forces @code{chronyd} to step system clock if the
|
|
adjustment is larger than a threshold value, but only if there were no
|
|
more clock updates since @code{chronyd} was started than a specified
|
|
limit (a negative value can be used to disable the limit).
|
|
|
|
This is particularly useful when using reference clocks, because the
|
|
@code{initstepslew} directive (@pxref{initstepslew directive}) works
|
|
only with NTP sources.
|
|
|
|
An example of the use of this directive is
|
|
|
|
@example
|
|
makestep 1000 10
|
|
@end example
|
|
|
|
This would step system clock if the adjustment is larger than 1000
|
|
seconds, but only in the first ten clock updates.
|
|
@c }}}
|
|
@c {{{ manual
|
|
@node manual directive
|
|
@subsection manual
|
|
The @code{manual} directive enables support at run-time for the
|
|
@code{settime} command in chronyc (@pxref{settime command}). If no
|
|
@code{manual} directive is included, any attempt to use the
|
|
@code{settime} command in chronyc will be met with an error message.
|
|
|
|
Note that the @code{settime} command can be enabled at run-time using
|
|
the @code{manual} command in chronyc (@pxref{manual command}). (The
|
|
idea of the two commands is that the @code{manual} command controls the
|
|
manual clock driver's behaviour, whereas the @code{settime} command
|
|
allows samples of manually entered time to be provided).
|
|
@c }}}
|
|
@c {{{ maxchange
|
|
@node maxchange directive
|
|
@subsection maxchange
|
|
This directive sets the maximum allowed offset corrected on a clock
|
|
update. The check is performed only after the specified number of
|
|
updates to allow a large initial adjustment of the system clock. When
|
|
an offset larger than the specified maximum occurs, it will be ignored
|
|
for the specified number of times and then @code{chronyd} will give up
|
|
and exit (a negative value can be used to never exit). In both cases
|
|
a message is sent to syslog.
|
|
|
|
An example of the use of this directive is
|
|
|
|
@example
|
|
maxchange 1000 1 2
|
|
@end example
|
|
|
|
After the first clock update, @code{chronyd} will check the offset on
|
|
every clock update, it will ignore two adjustments larger than 1000
|
|
seconds and exit on another one.
|
|
@c }}}
|
|
@c {{{ maxclockerror
|
|
@node maxclockerror directive
|
|
@subsection maxclockerror
|
|
The @code{maxclockerror} directive sets the maximum assumed frequency
|
|
error of the local clock. This is a frequency stability of the clock,
|
|
not an absolute frequency error.
|
|
|
|
By default, the maximum assumed error is set to 1 ppm.
|
|
|
|
The syntax is
|
|
|
|
@example
|
|
maxclockerror <error-in-ppm>
|
|
@end example
|
|
|
|
Typical values for <error-in-ppm> might be 10 for a low quality clock
|
|
to 0.1 for a high quality clock using a temperature compensated
|
|
crystal oscillator.
|
|
@c }}}
|
|
@c {{{ maxsamples
|
|
@node maxsamples directive
|
|
@subsection maxsamples
|
|
The @code{maxsamples} directive sets the default maximum number of samples
|
|
@code{chronyd} should keep for each source. This setting can be overriden for
|
|
individual sources in the @code{server} and @code{refclock} directives
|
|
(@pxref{server directive}, @pxref{refclock directive}). The default value is
|
|
0, which disables the configurable limit. The useful range is 4 to 64.
|
|
|
|
The syntax is
|
|
|
|
@example
|
|
maxsamples <samples>
|
|
@end example
|
|
@c }}}
|
|
@c {{{ maxslewrate
|
|
@node maxslewrate directive
|
|
@subsection maxslewrate
|
|
The @code{maxslewrate} directive sets the maximum rate at which @code{chronyd}
|
|
is allowed to slew the time. It limits the slew rate controlled by the
|
|
correction time ratio (@pxref{corrtimeratio directive}) and is effective
|
|
only on systems where @code{chronyd} is able to control the rate (so
|
|
far only Linux).
|
|
|
|
By default, the maximum slew rate is 83333.333 ppm (one twelfth).
|
|
|
|
The syntax is
|
|
|
|
@example
|
|
maxslewrate <rate-in-ppm>
|
|
@end example
|
|
@c }}}
|
|
@c {{{ maxupdateskew
|
|
@node maxupdateskew directive
|
|
@subsection maxupdateskew
|
|
One of @code{chronyd's} tasks is to work out how fast or slow the computer's
|
|
clock runs relative to its reference sources. In addition, it computes
|
|
an estimate of the error bounds around the estimated value.
|
|
|
|
If the range of error is too large, it probably indicates that the
|
|
measurements have not settled down yet, and that the estimated gain or
|
|
loss rate is not very reliable.
|
|
|
|
The @code{maxupdateskew} parameter allows the threshold for determining
|
|
whether an estimate may be so unreliable that it should not be used.
|
|
By default, the threshold is 1000 ppm.
|
|
|
|
The syntax is
|
|
|
|
@example
|
|
maxupdateskew <skew-in-ppm>
|
|
@end example
|
|
|
|
Typical values for <skew-in-ppm> might be 100 for a dial-up connection
|
|
to servers over a phone line, and 5 or 10 for a computer on a LAN.
|
|
|
|
It should be noted that this is not the only means of protection against
|
|
using unreliable estimates. At all times, @code{chronyd} keeps track of
|
|
both the estimated gain or loss rate, and the error bound on the
|
|
estimate. When a new estimate is generated following another
|
|
measurement from one of the sources, a weighted combination algorithm is
|
|
used to update the master estimate. So if @code{chronyd} has an existing
|
|
highly-reliable master estimate and a new estimate is generated which
|
|
has large error bounds, the existing master estimate will dominate in
|
|
the new master estimate.
|
|
@c }}}
|
|
@c {{{ minsamples
|
|
@node minsamples directive
|
|
@subsection minsamples
|
|
The @code{minsamples} directive sets the default minimum number of samples
|
|
@code{chronyd} should keep for each source. This setting can be overriden for
|
|
individual sources in the @code{server} and @code{refclock} directives
|
|
(@pxref{server directive}, @pxref{refclock directive}). The default value is
|
|
0. The useful range is 4 to 64.
|
|
|
|
The syntax is
|
|
|
|
@example
|
|
minsamples <samples>
|
|
@end example
|
|
@c }}}
|
|
@c {{{ minsources
|
|
@node minsources directive
|
|
@subsection minsources
|
|
The @code{minsources} directive sets the minimum number of sources that need
|
|
to be considered as selectable in the source selection algorithm before the
|
|
local clock is updated. The default value is 1.
|
|
|
|
Setting this option to a larger number can be used to improve the reliability.
|
|
More sources will have to agree with each other and the clock will not be
|
|
updated when only one source (which could be serving wrong time) is reachable.
|
|
|
|
The syntax is
|
|
|
|
@example
|
|
minsources <sources>
|
|
@end example
|
|
@c }}}
|
|
@c {{{ noclientlog
|
|
@node noclientlog directive
|
|
@subsection noclientlog
|
|
This directive, which takes no arguments, specifies that client accesses
|
|
are not to be logged. Normally they are logged, allowing statistics to
|
|
be reported using the @code{clients} command in @code{chronyc}.
|
|
@c }}}
|
|
@c {{{ peer
|
|
@node peer directive
|
|
@subsection peer
|
|
The syntax of this directive is identical to that for the @code{server}
|
|
directive (@pxref{server directive}), except that it is used to specify
|
|
an NTP peer rather than an NTP server.
|
|
|
|
Please note that NTP peers that are not configured with a key to enable
|
|
authentication are vulnerable to a denial-of-service attack. An attacker
|
|
knowing that NTP hosts A and B are peering with each other can send a packet
|
|
with random timestamps to host A with source address of B which will set the
|
|
NTP state variables on A to the values sent by the attacker. Host A will then
|
|
send on its next poll to B a packet with originate timestamp that doesn't match
|
|
the transmit timestamp of B and the packet will be dropped. If the attacker
|
|
does this periodically for both hosts, they won't be able to synchronize to
|
|
each other.
|
|
|
|
This attack can be prevented by enabling authentication with the key option, or
|
|
using the @code{server} directive on both sides to specify the other host as a
|
|
server instead of peer, the only drawback is that it will double the network
|
|
traffic between the two hosts.
|
|
@c }}}
|
|
@c {{{ pidfile
|
|
@node pidfile directive
|
|
@subsection pidfile
|
|
chronyd always writes its process ID (pid) to a file, and checks this file on startup to see if another chronyd may already be running on the system. By default, the file used is @code{/var/run/chronyd.pid}. The @code{pidfile} directive allows the name to be changed, e.g.
|
|
|
|
@example
|
|
pidfile /var/tmp/chronyd.pid
|
|
@end example
|
|
@c }}}
|
|
@c {{{ pool
|
|
@node pool directive
|
|
@subsection pool
|
|
The syntax of this directive is similar to that for the @code{server}
|
|
directive (@pxref{server directive}), except that it is used to specify a pool
|
|
of NTP servers rather than a single NTP server. The pool name is expected to
|
|
resolve to multiple addresses which may change over time.
|
|
|
|
All options valid in the @code{server} directive can be used in this directive
|
|
too. There is one option specific to @code{pool} directive: @code{maxsources}
|
|
sets the maximum number of sources that can be used from the pool, the default
|
|
value is 4.
|
|
|
|
On start, when the pool name is resolved, @code{chronyd} will add up to 16
|
|
sources, one for each resolved address. When the number of sources from which
|
|
at least one valid reply was received reaches @code{maxsources}, the other
|
|
sources will be removed. When a pool source is unreachable or marked as
|
|
falseticker, @code{chronyd} will try to replace the source with a newly
|
|
resolved address of the pool.
|
|
|
|
An example of the pool directive is
|
|
|
|
@example
|
|
pool pool.ntp.org iburst maxsources 3
|
|
@end example
|
|
@c }}}
|
|
@c {{{ port
|
|
@node port directive
|
|
@subsection port
|
|
This option allows you to configure the port on which @code{chronyd}
|
|
will listen for NTP requests. The port will be open only when an address is
|
|
allowed by the @code{allow} directive or command, an NTP peer is configured, or
|
|
the broadcast server mode is enabled.
|
|
|
|
The compiled in default is udp/123, the standard NTP port. If set to 0,
|
|
@code{chronyd} will never open the server port and will operate strictly in a
|
|
client-only mode. The source port used in NTP client requests can be set by
|
|
the @code{acquisitionport} directive.
|
|
|
|
An example of the port command is
|
|
|
|
@example
|
|
port 11123
|
|
@end example
|
|
|
|
This would change the NTP port served by @code{chronyd} on the computer to
|
|
udp/11123.
|
|
@c }}}
|
|
@c {{{ refclock
|
|
@node refclock directive
|
|
@subsection refclock
|
|
Reference clocks allows very accurate synchronisation and @code{chronyd}
|
|
can function as a stratum 1 server. They are specified by the
|
|
@code{refclock} directive. It has two mandatory parameters, a refclock driver
|
|
name and a driver specific parameter.
|
|
|
|
There are currently four drivers included:
|
|
|
|
@table @code
|
|
@item PPS
|
|
PPSAPI (pulse per second) driver. The parameter is the path to a PPS
|
|
device. Assert events are used by default. Driver option @code{:clear}
|
|
can be appended to the path if clear events should be used instead.
|
|
|
|
As PPS refclock gets only sub-second time information, it needs another
|
|
source (NTP or non-PPS refclock) or local directive (@pxref{local
|
|
directive}) enabled to work. For example:
|
|
|
|
@example
|
|
refclock PPS /dev/pps0 lock NMEA
|
|
refclock SHM 0 offset 0.5 delay 0.2 refid NMEA noselect
|
|
@end example
|
|
|
|
@item SHM
|
|
NTP shared memory driver. This driver uses a shared memory segment to
|
|
receive data from another daemon which communicates with an actual
|
|
reference clock. The parameter is the number of a shared memory segment,
|
|
usually 0, 1, 2 or 3. For example:
|
|
|
|
@example
|
|
refclock SHM 1 poll 3 refid GPS1
|
|
@end example
|
|
|
|
A driver option in form @code{:perm=NNN} can be appended to the
|
|
segment number to create the segment with permissions other than the
|
|
default @code{0600}.
|
|
|
|
Some examples of applications that can be used as SHM sources are
|
|
@uref{http://catb.org/gpsd/, @code{gpsd}}, @code{shmpps} and
|
|
@uref{http://www.buzzard.me.uk/jonathan/radioclock.html, @code{radioclk}}.
|
|
@item SOCK
|
|
Unix domain socket driver. It is similar to the SHM driver, but uses a
|
|
different format and uses a socket instead of shared memory. It does not
|
|
require polling and it
|
|
supports transmitting of PPS data. The parameter is a path to the socket which
|
|
will be created by @code{chronyd} and used to receive the messages. The format
|
|
of messages sent over the socket is described in the
|
|
@code{refclock_sock.c} file.
|
|
|
|
Recent versions of the @code{gpsd} daemon include support for the SOCK
|
|
protocol. The path where the socket should be created is described in the
|
|
@code{gpsd(8)} man page. For example:
|
|
|
|
@example
|
|
refclock SOCK /var/run/chrony.ttyS0.sock
|
|
@end example
|
|
|
|
@item PHC
|
|
PTP hardware clock (PHC) driver. The parameter is the path to the device of
|
|
the PTP clock, which can be synchronised by a PTP daemon (e.g. @code{ptp4l}
|
|
from the @uref{http://linuxptp.sourceforge.net/, Linux PTP project}. The PTP
|
|
clocks are typically kept in TAI instead of UTC. The @code{offset} option can
|
|
be used to compensate for the current UTC/TAI offset. For example:
|
|
|
|
@example
|
|
refclock PHC /dev/ptp0 poll 3 dpoll -2 offset -35
|
|
@end example
|
|
|
|
@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 the polling interval
|
|
specified by this option. This is defined as a power of 2 and may be
|
|
negative to specify a sub-second interval. The
|
|
default is 4 (16 seconds). A shorter interval allows @code{chronyd}
|
|
to react faster to changes in clock frequency, but it may decrease
|
|
the accuracy if the source is too noisy.
|
|
@item dpoll
|
|
Some drivers don't listen for external events and try to produce
|
|
samples in their own polling interval. This is defined as a power of
|
|
2 and may be negative to specify a sub-second interval. 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 must have an unique refid.
|
|
@item filter
|
|
This option sets the length of the median filter which is used to
|
|
reduce noise. With each poll about 40 percent of the stored samples is
|
|
discarded and one final sample is calculated as average of the
|
|
remaining samples. If the length is 4 or above, at least 4 samples
|
|
have to be collected between polls. For lengths below 4, the filter
|
|
has to be full. The default is 64.
|
|
@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 lock
|
|
This option can be used to lock a PPS refclock to another refclock
|
|
whose reference id is specified by this option. In this mode received
|
|
pulses are aligned directly to unfiltered samples from the refclock.
|
|
By default, pulses are aligned to local clock, but only when it is
|
|
well synchronised.
|
|
@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 sets the NTP delay of the source (in seconds). Half of
|
|
this value is included in the maximum assumed error which is used in the
|
|
source selection algorithm. Increasing the delay is useful to avoid
|
|
having no majority in the algorithm or to make it prefer other
|
|
sources. The default is 1e-9 (1 nanosecond).
|
|
@item precision
|
|
Refclock precision (in seconds). The default is 1e-6 (1 microsecond)
|
|
for SHM refclock, and 1e-9 (1 nanosecond) for SOCK, PPS and PHC refclocks.
|
|
@item maxdispersion
|
|
Maximum allowed dispersion for filtered samples (in seconds). Samples
|
|
with larger estimated dispersion are ignored. By default, this limit
|
|
is disabled.
|
|
@item prefer
|
|
Prefer this source over sources without prefer option.
|
|
@item 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.
|
|
@item minsamples
|
|
Set the minimum number of samples kept for this source. This overrides the
|
|
@code{minsamples} directive (@pxref{minsamples directive}).
|
|
@item maxsamples
|
|
Set the maximum number of samples kept for this source. This overrides the
|
|
@code{maxsamples} directive (@pxref{maxsamples directive}).
|
|
@end table
|
|
|
|
@c }}}
|
|
@c {{{ reselectdist
|
|
@node reselectdist directive
|
|
@subsection reselectdist
|
|
When @code{chronyd} selects synchronisation source from available sources, it
|
|
will prefer the one with minimum synchronisation distance. However, to
|
|
avoid frequent reselecting when there are sources with similar distance, a
|
|
fixed distance is added to the distance for sources that are currently not
|
|
selected. This can be set with the @code{reselectdist} option. By default, the
|
|
distance is 100 microseconds.
|
|
|
|
The syntax is
|
|
|
|
@example
|
|
reselectdist <dist-in-seconds>
|
|
@end example
|
|
@c }}}
|
|
@c {{{ rtcautotrim
|
|
@node rtcautotrim directive
|
|
@subsection rtcautotrim
|
|
The @code{rtcautotrim} directive is used to keep the real time clock (RTC)
|
|
close to the system clock automatically. When the system clock is synchronized
|
|
and the estimated error between the two clocks is larger than the specified
|
|
threshold, @code{chronyd} will trim the RTC as if the @code{trimrtc}
|
|
(@pxref{trimrtc command}) command was issued.
|
|
|
|
This directive is effective only with the @code{rtcfile} directive.
|
|
|
|
An example of the use of this directive is
|
|
|
|
@example
|
|
rtcautotrim 30
|
|
@end example
|
|
|
|
This would set the threshold error to 30 seconds.
|
|
@c }}}
|
|
@c {{{ rtcdevice
|
|
@node rtcdevice directive
|
|
@subsection rtcdevice
|
|
The @code{rtcdevice} directive defines the name of the device file for
|
|
accessing the real time clock. By default this is @code{/dev/rtc}, unless the
|
|
directive is used to set a different value. This applies to Linux systems with
|
|
devfs. An example of use is
|
|
|
|
@example
|
|
rtcdevice /dev/misc/rtc
|
|
@end example
|
|
@c }}}
|
|
@c {{{ rtcfile
|
|
@node rtcfile directive
|
|
@subsection rtcfile
|
|
The @code{rtcfile} directive defines the name of the file in which
|
|
@code{chronyd} can save parameters associated with tracking the accuracy
|
|
of the system's real-time clock (RTC).
|
|
|
|
The syntax is illustrated in the following example
|
|
|
|
@example
|
|
rtcfile @CHRONYVARDIR@/rtc
|
|
@end example
|
|
|
|
@code{chronyd} saves information in this file when it exits and when the
|
|
@code{writertc} command is issued in @code{chronyc}. The information
|
|
saved is the RTC's error at some epoch, that epoch (in seconds since
|
|
January 1 1970), and the rate at which the RTC gains or loses time.
|
|
|
|
So far, the support for real-time clocks is limited - their code is even
|
|
more system-specific than the rest of the software. You can only use
|
|
the real time clock facilities (the @code{rtcfile} directive and the
|
|
@code{-s} command line option to @code{chronyd}) if the following three
|
|
conditions apply:
|
|
|
|
@enumerate 1
|
|
@item
|
|
You are running Linux version 2.2.x or later.
|
|
|
|
@item
|
|
You have compiled the kernel with extended real-time clock support
|
|
(i.e. the @file{/dev/rtc} device is capable of doing useful things).
|
|
|
|
@item
|
|
You don't have other applications that need to make use of
|
|
@file{/dev/rtc} at all.
|
|
|
|
@end enumerate
|
|
@c }}}
|
|
@c {{{ rtconutc
|
|
@node rtconutc directive
|
|
@subsection rtconutc
|
|
|
|
@code{chronyd} assumes by default that the real time clock (RTC) keeps
|
|
local time (including any daylight saving changes). This is convenient
|
|
on PCs running Linux which are dual-booted with DOS or Windows.
|
|
|
|
NOTE : IF YOU KEEP THE REAL TIME CLOCK ON LOCAL TIME AND YOUR COMPUTER
|
|
IS OFF WHEN DAYLIGHT SAVING (SUMMER TIME) STARTS OR ENDS, THE COMPUTER'S
|
|
SYSTEM TIME WILL BE ONE HOUR IN ERROR WHEN YOU NEXT BOOT AND START
|
|
CHRONYD.
|
|
|
|
An alternative is for the RTC to keep Universal Coordinated Time (UTC).
|
|
This does not suffer from the 1 hour problem when daylight saving starts
|
|
or ends.
|
|
|
|
If the @code{rtconutc} directive appears, it means the RTC is required
|
|
to keep UTC. The directive takes no arguments. It is equivalent to
|
|
specifying the @code{-u} switch to the Linux @file{/sbin/hwclock} program.
|
|
|
|
Note that this setting is overriden when the @code{hwclockfile} directive
|
|
(@pxref{hwclockfile directive}) is used.
|
|
@c }}}
|
|
@c {{{ rtcsync
|
|
@node rtcsync directive
|
|
@subsection rtcsync
|
|
|
|
The @code{rtcsync} directive will enable a kernel mode where the
|
|
system time is copied to the real time clock (RTC) every 11 minutes.
|
|
|
|
This directive is supported only on Linux and cannot be used when the
|
|
normal RTC tracking is enabled, i.e. when the @code{rtcfile} directive
|
|
is used.
|
|
@c }}}
|
|
@c {{{ sched_priority
|
|
@node sched_priority directive
|
|
@subsection sched_priority
|
|
|
|
The @code{sched_priority} directive will select the SCHED_FIFO real-time
|
|
scheduler at the specified priority (which must be between 0 and 100).
|
|
This mode is supported only on Linux.
|
|
|
|
This directive uses the Linux sched_setscheduler() system call to
|
|
instruct the kernel to use the SCHED_FIFO first-in, first-out
|
|
real-time scheduling policy for @code{chronyd} with the specified priority.
|
|
This means that whenever @code{chronyd} is ready to run it will run,
|
|
interrupting whatever else is running unless it is a higher priority
|
|
real-time process. This should not impact performance as @code{chronyd's}
|
|
resource requirements are modest, but it should result in lower and
|
|
more consistent latency since @code{chronyd} will not need to wait for the
|
|
scheduler to get around to running it. You should not use this unless
|
|
you really need it. The sched_setscheduler man page has more details.
|
|
@c }}}
|
|
@c {{{ server
|
|
@node server directive
|
|
@subsection server
|
|
The @code{server} directive allows NTP servers to be specified. The
|
|
client/server relationship is strictly hierarchical : a client may
|
|
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. The server command also supports a
|
|
number of subfields (which may be defined in any order):
|
|
|
|
@table @code
|
|
@item port
|
|
This option allows the UDP port on which the server understands NTP
|
|
requests to be specified. For normal servers this option should not be
|
|
required (the default is 123, the standard NTP port).
|
|
@item minpoll
|
|
Although @code{chronyd} will trim the rate at which it samples the
|
|
server during normal operation, the user may wish to constrain the
|
|
minimum polling interval. This is always defined as a power of 2, so
|
|
@code{minpoll 5} would mean that the polling interval cannot drop below 32
|
|
seconds. The default is 6 (64 seconds).
|
|
@item maxpoll
|
|
In a similar way, the user may wish to constrain the maximum polling
|
|
interval. Again this is specified as a power of 2, @code{maxpoll 9}
|
|
indicates that the polling interval must stay at or below 512 seconds.
|
|
The default is 10 (1024 seconds).
|
|
@item maxdelay
|
|
@code{chronyd} uses the network round-trip delay to the server to
|
|
determine how accurate a particular measurement is likely to be. Long
|
|
round-trip delays indicate that the request, or the response, or both
|
|
were delayed. If only one of the messages was delayed the measurement
|
|
error is likely to be substantial.
|
|
|
|
For small variations in round trip delay, @code{chronyd} uses a
|
|
weighting scheme when processing the measurements. However, beyond a
|
|
certain level of delay the measurements are likely to be so corrupted as
|
|
to be useless. (This is particularly so on dial-up or other slow links,
|
|
where a long delay probably indicates a highly asymmetric delay caused
|
|
by the response waiting behind a lot of packets related to a download of
|
|
some sort).
|
|
|
|
If the user knows that round trip delays above a certain level should
|
|
cause the measurement to be ignored, this level can be defined with the
|
|
maxdelay command. For example, @code{maxdelay 0.3} would indicate that
|
|
measurements with a round-trip delay of 0.3 seconds or more should be
|
|
ignored. The default value is 3 seconds.
|
|
|
|
@item maxdelayratio
|
|
This option is similar to the maxdelay option above. @code{chronyd}
|
|
keeps a record of the minimum round-trip delay amongst the previous
|
|
measurements that it has buffered. If a measurement has a round trip
|
|
delay that is greater than the maxdelayratio times the minimum delay, it
|
|
will be rejected.
|
|
|
|
@item maxdelaydevratio
|
|
If a measurement has ratio of the increase in round-trip delay from
|
|
the minimum delay amongst the previous measurements to the standard
|
|
deviation of the previous measurements that is greater than
|
|
maxdelaydevratio, it will be rejected. The default is 10.0.
|
|
|
|
@item presend
|
|
If the timing measurements being made by @code{chronyd} are the only
|
|
network data passing between two computers, you may find that some
|
|
measurements are badly skewed due to either the client or the server
|
|
having to do an ARP lookup on the other party prior to transmitting a
|
|
packet. This is more of a problem with long sampling intervals, which
|
|
may be similar in duration to the lifetime of entries in the ARP caches
|
|
of the machines.
|
|
|
|
In order to avoid this problem, the @code{presend} option may be used.
|
|
It takes a single integer argument, which is the smallest polling
|
|
interval for which an extra pair of NTP packets will be exchanged
|
|
between the client and the server prior to the actual measurement.
|
|
For example, with the following option included in a
|
|
@code{server} directive :
|
|
|
|
@example
|
|
presend 9
|
|
@end example
|
|
|
|
when the polling interval is 512 seconds or more, an extra NTP client
|
|
packet will be sent to the server a short time (currently 4 seconds)
|
|
before making the actual measurement.
|
|
|
|
@item key
|
|
The NTP protocol supports the inclusion of checksums in the packets, to
|
|
prevent computers having their system time upset by rogue packets being
|
|
sent to them. The checksums are generated as a function of a password,
|
|
using the cryptographic hash function set in the key file.
|
|
|
|
The association between key numbers and passwords is contained in the
|
|
keys file, defined by the keyfile command.
|
|
|
|
If the key option is present, @code{chronyd} will attempt to use
|
|
authenticated packets when communicating with this server. The key
|
|
number used will be the single argument to the key option (an
|
|
unsigned integer in the range 1 through 2**32-1). The server
|
|
must have the same password for this key number configured, otherwise no
|
|
relationship between the computers will be possible.
|
|
|
|
@item offline
|
|
If the server will not be reachable when @code{chronyd} is started, the
|
|
offline option may be specified. @code{chronyd} will not try to poll
|
|
the server until it is enabled to do so (by using the online option of
|
|
@code{chronyc}).
|
|
|
|
@item auto_offline
|
|
If this option is set, the server will be assumed to have gone offline when 2
|
|
requests have been sent to it without receiving a response. This option avoids
|
|
the need to run the @code{offline} (@pxref{offline command}) command from
|
|
chrony when disconnecting the dial-up link. (It will still be necessary to use
|
|
chronyc's @code{online} (@pxref{online command}) command when the link has been
|
|
established, to enable measurements to start.)
|
|
|
|
@item iburst
|
|
On start, make four measurements over a short duration (rather than
|
|
the usual periodic measurements).
|
|
|
|
@item minstratum
|
|
When the synchronisation source is selected from available sources, sources
|
|
with lower stratum are normally preferred. This option can be used to increase
|
|
stratum of the source to the specified minimum, so @code{chronyd} will avoid
|
|
selecting that source. This is useful with low stratum sources that are known
|
|
to be unrealiable or inaccurate and which should be used only when other
|
|
sources are unreachable.
|
|
|
|
@item polltarget
|
|
Target number of measurements to use for the regression algorithm which
|
|
@code{chronyd} will try to maintain by adjusting polling interval between
|
|
@code{minpoll} and @code{maxpoll}. A higher target makes @code{chronyd} prefer
|
|
shorter polling intervals. The default is 6 and a useful range is 6 to 60.
|
|
|
|
@item version
|
|
This option sets the NTP version number used in packets sent to the server.
|
|
This can be useful when the server runs an old NTP implementation that doesn't
|
|
respond to newer versions. The default version number is 4.
|
|
|
|
@item prefer
|
|
Prefer this source over sources without prefer option.
|
|
|
|
@item noselect
|
|
Never select this source. This is particularly useful for monitoring.
|
|
|
|
@item minsamples
|
|
Set the minimum number of samples kept for this source. This overrides the
|
|
@code{minsamples} directive (@pxref{minsamples directive}).
|
|
|
|
@item maxsamples
|
|
Set the maximum number of samples kept for this source. This overrides the
|
|
@code{maxsamples} directive (@pxref{maxsamples directive}).
|
|
|
|
@end table
|
|
@c }}}
|
|
@c {{{ smoothtime
|
|
@node smoothtime directive
|
|
@subsection smoothtime
|
|
The @code{smoothtime} directive can be used to enable smoothing of the time
|
|
that @code{chronyd} serves to its clients to make it easier for them to track
|
|
it and keep their clocks close together even when large offset or frequency
|
|
corrections are applied to the server's clock, for example after being offline
|
|
for a longer time.
|
|
|
|
If a large offset has been accumulated, it may take a very long time to smooth
|
|
it out. This directive should be used only when the clients are not configured
|
|
to poll also another NTP server, because they could reject this server as a
|
|
falseticker or fail to select a source completely.
|
|
|
|
The smoothing process is independent from any slewing applied to the local
|
|
system clock, but the accumulated offset and frequency for smoothing will be
|
|
reset when the clock is corrected by step, e.g. by the @code{makestep}
|
|
directive or command.
|
|
|
|
The directive takes two arguments, the maximum frequency offset of the smoothed
|
|
time to the tracked NTP time (in ppm) and the maximum rate at which the
|
|
frequency offset is allowed to change (in ppm per second). The smoothing
|
|
process is activated when 1/10000 of the estimated skew of the local clock
|
|
falls below the maximum rate of frequency change.
|
|
|
|
An example suitable for clients using @code{ntpd} and 1024 second polling
|
|
interval could be
|
|
|
|
@example
|
|
smoothtime 400 0.001
|
|
@end example
|
|
|
|
An example suitable for clients using @code{chronyd} on Linux could be
|
|
|
|
@example
|
|
smoothtime 50000 0.01
|
|
@end example
|
|
@c }}}
|
|
@c {{{ stratumweight
|
|
@node stratumweight directive
|
|
@subsection stratumweight
|
|
|
|
The @code{stratumweight} directive sets how much distance should be added
|
|
per stratum to the synchronisation distance when @code{chronyd} selects
|
|
the synchronisation source from available sources.
|
|
|
|
The syntax is
|
|
|
|
@example
|
|
stratumweight <dist-in-seconds>
|
|
@end example
|
|
|
|
By default, the weight is 0.001 seconds. This means that stratum of the
|
|
sources in the selection process matters only when the differences between the
|
|
distances are in milliseconds.
|
|
|
|
@c }}}
|
|
@c {{{ tempcomp
|
|
@node tempcomp directive
|
|
@subsection tempcomp
|
|
Normally, changes in the rate of drift of the system clock are caused mainly by
|
|
changes in the temperature of the crystal oscillator on the mainboard.
|
|
|
|
If there are temperature measurements available from a sensor close to the
|
|
oscillator, the @code{tempcomp} directive can be used to compensate for the
|
|
changes in the temperature and improve the stability and accuracy of the clock.
|
|
|
|
The result depends on many factors, including the resolution of the sensor,
|
|
the amount of noise in the measurements, the polling interval of the time
|
|
source, the compensation update interval, how well is the compensation
|
|
specified, and how close is the sensor to the oscillator. When it's working
|
|
well, the frequency reported in the @file{tracking.log} file is more stable and
|
|
the maximum reached offset is smaller.
|
|
|
|
There are two forms of the directive. The first one has six parameters: a
|
|
path to the file containing the current temperature from the sensor (in
|
|
text format), the compensation update interval (in seconds), and temperature
|
|
coefficients T0, k0, k1, k2.
|
|
|
|
The frequency compensation is calculated (in ppm) as
|
|
|
|
@code{k0 + (T - T0) * k1 + (T - T0)^2 * k2}
|
|
|
|
The result has to be between -10 ppm and 10 ppm, otherwise the measurement is
|
|
considered invalid and will be ignored. The k0 coefficient can be used to get
|
|
the results in that range.
|
|
|
|
An example of use is
|
|
|
|
@example
|
|
tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 26000 0.0 0.000183 0.0
|
|
@end example
|
|
|
|
The measured temperature will be read from the file in the Linux sysfs
|
|
filesystem every 30 seconds. When the temperature is 26000 (26 degrees
|
|
Celsius), the frequency correction will be zero. When it is 27000 (27 degrees
|
|
Celsius), the clock will be set to run 0.183ppm faster, etc.
|
|
|
|
The second form has three parameters, the path to the sensor file, the update
|
|
interval and a path to a file containing a list of (temperature, compensation)
|
|
points, from which the compensation is linearly interpolated or extrapolated.
|
|
|
|
An example is
|
|
|
|
@example
|
|
tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 /etc/chrony.tempcomp
|
|
@end example
|
|
|
|
where the @file{chrony.tempcomp} file could have
|
|
|
|
@example
|
|
20000 1.0
|
|
21000 0.64
|
|
22000 0.36
|
|
23000 0.16
|
|
24000 0.04
|
|
25000 0.0
|
|
26000 0.04
|
|
27000 0.16
|
|
28000 0.36
|
|
29000 0.64
|
|
30000 1.0
|
|
@end example
|
|
|
|
Valid measurements with corresponding compensations are logged to the
|
|
@file{tempcomp.log} file if enabled by the @code{log tempcomp} directive.
|
|
@c }}}
|
|
@c {{{ user
|
|
@node user directive
|
|
@subsection user
|
|
The @code{user} directive sets the name of the user to which will
|
|
@code{chronyd} switch on initialisation to drop root privileges.
|
|
So far, it works only on Linux when compiled with capabilities support.
|
|
Setting the name to root will disable it.
|
|
|
|
The default value is @code{@DEFAULT_USER@}.
|
|
@c }}}
|
|
@c }}}
|
|
@c {{{ S:Running chronyc
|
|
@node Running chronyc
|
|
@section Running chronyc
|
|
@c {{{ Section top
|
|
Chronyc is the program that can be used to reconfigure options within
|
|
the @code{chronyd} program whilst it is running. Chronyc can also be
|
|
used to generate status reports about the operation of @code{chronyd}.
|
|
|
|
@menu
|
|
* Chronyc basic use:: How to run chronyc
|
|
* Chronyc command line options:: Chrony's command line options
|
|
* Security with chronyc:: How chronyd restricts access
|
|
* Chronyc command reference:: All the commands chronyc supports
|
|
@end menu
|
|
@c }}}
|
|
@c {{{ SS:Chronyc basic use
|
|
@node Chronyc basic use
|
|
@subsection Basic use
|
|
The program chronyc is run by entering
|
|
|
|
@example
|
|
chronyc
|
|
@end example
|
|
|
|
at the command line. The prompt @code{chronyc} is displayed whilst
|
|
chronyc is expecting input from the user, when it is being run from a
|
|
terminal. If chronyc's input or output are redirected from/to a file,
|
|
the prompt is now shown.
|
|
|
|
When you are finished entering commands, the commands @code{exit} or
|
|
@code{quit} will terminate the program. (Entering @key{Control-D} will
|
|
also terminate the program.)
|
|
@c }}}
|
|
@c {{{ SS:Command line options
|
|
@node Chronyc command line options
|
|
@subsection Command line options
|
|
Chronyc supports the following command line options.
|
|
|
|
@table @code
|
|
@item -v
|
|
Displays the version number of chronyc on the terminal, and exists.
|
|
@item -h <host>
|
|
This option allows the user to specify which host running the
|
|
@code{chronyd} program is to be contacted. This allows for remote
|
|
configuration, without having to ssh to the other host first.
|
|
|
|
The default is to contact @code{chronyd} running on the same host as
|
|
that where chronyc is being run.
|
|
@item -p <port>
|
|
This option allows the user to specify the UDP port number which the
|
|
target @code{chronyd} is using for its command & monitoring connections.
|
|
This defaults to the compiled-in default; there would rarely be a need
|
|
to change this.
|
|
@item -n
|
|
This option disables resolving IP addresses to hostnames.
|
|
@item -4
|
|
With this option hostnames will be resolved only to IPv4 addresses.
|
|
@item -6
|
|
With this option hostnames will be resolved only to IPv6 addresses.
|
|
@item -m
|
|
With this option multiple commands can be specified on the command line.
|
|
Each argument will be interpreted as a whole command.
|
|
@item -f <conf-file>
|
|
This option can be used to specify an alternate location of the @code{chronyd}
|
|
configuration file (default @file{@SYSCONFDIR@/chrony.conf}). The configuration file is
|
|
needed for the `-a' option.
|
|
@item -a
|
|
With this option @code{chronyc} will try to authenticate automatically on
|
|
start. It will read the configuration file, read the command key from the
|
|
keyfile and run the authhash and password commands.
|
|
@end table
|
|
@c }}}
|
|
@c {{{ SS:Security with chronyc
|
|
@node Security with chronyc
|
|
@subsection Security with chronyc
|
|
Many of the commands available through chronyc have a fair amount of
|
|
power to reconfigure the run-time behaviour of @code{chronyd}. Consequently,
|
|
@code{chronyc} is quite dangerous for the integrity of the target
|
|
system's clock performance. Having access to @code{chronyd} via chronyc is
|
|
more or less equivalent to being able to modify @code{chronyd's} configuration
|
|
file (typically @file{@SYSCONFDIR@/chrony.conf}) and to restart @code{chronyd}.
|
|
|
|
Chronyc also provides a number of monitoring (as opposed to commanding)
|
|
commands, which will not affect the behaviour of @code{chronyd}. However, you
|
|
may still want to restrict access to these commands.
|
|
|
|
In view of this, access to some of the capabilities of chronyc will
|
|
usually be tightly controlled. There are two mechanisms supported:
|
|
|
|
@enumerate 1
|
|
@item
|
|
The set of hosts from which @code{chronyd} will accept commands can be
|
|
restricted. By default, commands will only be accepted from the same
|
|
host that @code{chronyd} is running on.
|
|
@item
|
|
Any command that actually reconfigures some aspect of @code{chronyd's}
|
|
behaviour requires the user of chronyc to know a password. This
|
|
password is specified in @code{chronyd's} keys file (@pxref{keyfile directive})
|
|
and specified via the commandkey option in its configuration file
|
|
(@pxref{commandkey directive}).
|
|
@end enumerate
|
|
|
|
Only the following commands can be used @emph{without} providing a
|
|
password:
|
|
|
|
@itemize @bullet
|
|
@item @code{activity}
|
|
@item @code{authhash}
|
|
@item @code{dns}
|
|
@item @code{exit}
|
|
@item @code{help}
|
|
@item @code{password}
|
|
@item @code{quit}
|
|
@item @code{rtcdata}
|
|
@item @code{sources}
|
|
@item @code{sourcestats}
|
|
@item @code{tracking}
|
|
@item @code{waitsync}
|
|
@end itemize
|
|
|
|
All other commands require a password to have been specified previously,
|
|
because they affect @code{chronyd's} operation.
|
|
@c }}}
|
|
@c {{{ SS:Chronyc command reference
|
|
@node Chronyc command reference
|
|
@subsection Command reference
|
|
@c {{{ Top/menu
|
|
This section describes each of the commands available within the chronyc
|
|
program. Chronyc offers the user a simple command-line driven
|
|
interface.
|
|
|
|
@menu
|
|
* accheck command:: Verifying NTP client access
|
|
* activity command:: Check how many NTP servers/peers are online/offline
|
|
* add peer command:: Add a new NTP peer
|
|
* add server command:: Add a new NTP server
|
|
* allow all command:: Allowing NTP client access
|
|
* allow command:: Allowing NTP client access
|
|
* authhash command:: Set the command authentication hash function
|
|
* burst command:: Initiating a rapid set of measurements
|
|
* clients command:: Show clients that have accessed the server
|
|
* cmdaccheck command:: Verifying command client access
|
|
* cmdallow all command:: Allowing command client access
|
|
* cmdallow command:: Allowing command client access
|
|
* cmddeny all command:: Denying command client access
|
|
* cmddeny command:: Denying command client access
|
|
* cyclelogs command:: Close and re-open open log files
|
|
* delete command:: Remove an NTP server or peer
|
|
* deny all command:: Denying NTP client access
|
|
* deny command :: Denying NTP client access
|
|
* dns command:: Configure how are hostnames and IP addresses resolved
|
|
* dump command:: Dump measurement histories to files
|
|
* exit command:: Exit from chronyc
|
|
* help command:: Generate help summary
|
|
* local command:: Let computer be a server when it is unsynchronised
|
|
* makestep command:: Correct the system clock by stepping instead of slewing
|
|
* manual command:: Enable/disable/configure options for settime
|
|
* maxdelay command:: Set max measurement delay for a source
|
|
* maxdelaydevratio command:: Set max measurement delay for a source as ratio to deviation
|
|
* maxdelayratio command:: Set max measurement delay for a source as ratio
|
|
* maxpoll command:: Set maximum polling interval for a source
|
|
* maxupdateskew command:: Set safety threshold for clock gain/loss rate
|
|
* minpoll command:: Set minimum polling interval for a source
|
|
* minstratum command:: Set minimum stratum for a source
|
|
* offline command:: Warn that connectivity to a source will be lost
|
|
* online command:: Warn that connectivity to a source has been restored
|
|
* password command:: Provide password needed for most commands
|
|
* polltarget command:: Set poll target for a source
|
|
* quit command:: Exit from chronyc
|
|
* reselect command:: Reselect synchronisation source
|
|
* reselectdist command:: Set improvement in distance needed to reselect a source
|
|
* retries command:: Set maximum number of retries
|
|
* rtcdata command:: Display RTC parameters
|
|
* settime command:: Provide a manual input of the current time
|
|
* sources command:: Display information about the current set of sources
|
|
* sourcestats command:: Display the rate & offset estimation performance of sources
|
|
* timeout command:: Set initial response timeout
|
|
* tracking command:: Display system clock performance
|
|
* trimrtc command:: Correct the RTC time to the current system time
|
|
* waitsync command:: Wait until synchronised
|
|
* writertc command:: Write the RTC parameters to file
|
|
@end menu
|
|
@c }}}
|
|
@c {{{ accheck
|
|
@node accheck command
|
|
@subsubsection accheck
|
|
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:
|
|
|
|
@example
|
|
accheck foo.example.net
|
|
accheck 1.2.3.4
|
|
accheck 2001:db8::1
|
|
@end example
|
|
|
|
This command can be used to examine the effect of a series of
|
|
@code{allow}, @code{allow all}, @code{deny} and @code{deny all} commands
|
|
specified either via chronyc, or in @code{chronyd's} configuration file.
|
|
@c }}}
|
|
@c {{{ activity command
|
|
@node activity command
|
|
@subsubsection activity
|
|
This command reports the number of servers/peers that are online and offline.
|
|
If the auto_offline option is used in specifying some of the servers/peers, the
|
|
@code{activity} command may be useful for detecting when all of them have
|
|
entered the offline state after the PPP link has been disconnected.
|
|
|
|
The report shows the number of servers/peers in 5 states:
|
|
@itemize
|
|
@item @code{online} : the server/peer is currently online (i.e. assumed by
|
|
chronyd to be reachable)
|
|
@item @code{offline} : the server/peer is currently offline (i.e. assumed by
|
|
chronyd to be unreachable, and no measurements from it will be attempted.)
|
|
@item @code{burst_online} : a burst command has been initiated for the
|
|
server/peer and is being performed; after the burst is complete, the
|
|
server/peer will be returned to the online state.
|
|
@item @code{burst_offline} : a burst command has been initiated for the
|
|
server/peer and is being performed; after the burst is complete, the
|
|
server/peer will be returned to the offline state.
|
|
@item @code{unresolved} : the name of the server/peer wasn't resolved to an
|
|
address yet; this server is not visible in the @code{sources} and
|
|
@code{sourcestats} reports.
|
|
@end itemize
|
|
@c }}}
|
|
@c {{{ add peer
|
|
@node add peer command
|
|
@subsubsection add peer
|
|
The @code{add peer} command allows a new NTP peer to be added whilst
|
|
@code{chronyd} is running.
|
|
|
|
Following the words @code{add peer}, the syntax of the following
|
|
parameters and options is similar to that for the @code{peer}
|
|
directive in the configuration file (@pxref{peer directive}).
|
|
The following peer options can be set in the command:
|
|
@code{port}, @code{minpoll}, @code{maxpoll}, @code{presend},
|
|
@code{maxdelayratio}, @code{maxdelay}, @code{key}
|
|
|
|
An example of using this command is shown below.
|
|
|
|
@example
|
|
add peer foo.example.net minpoll 6 maxpoll 10 key 25
|
|
@end example
|
|
@c }}}
|
|
@c {{{ add server
|
|
@node add server command
|
|
@subsubsection add server
|
|
The @code{add server} command allows a new NTP server to be added whilst
|
|
@code{chronyd} is running.
|
|
|
|
Following the words @code{add server}, the syntax of the following
|
|
parameters and options is similar to that for the @code{server}
|
|
directive in the configuration file (@pxref{server directive}).
|
|
The following server options can be set in the command:
|
|
@code{port}, @code{minpoll}, @code{maxpoll}, @code{presend},
|
|
@code{maxdelayratio}, @code{maxdelay}, @code{key}
|
|
|
|
An example of using this command is shown below.
|
|
|
|
@example
|
|
add server foo.example.net minpoll 6 maxpoll 10 key 25
|
|
@end example
|
|
@c }}}
|
|
@c {{{ allow all
|
|
@node allow all command
|
|
@subsubsection allow all
|
|
The effect of the allow command is identical to the @code{allow all}
|
|
directive in the configuration file (@pxref{allow directive}).
|
|
@c }}}
|
|
@c {{{ allow
|
|
@node allow command
|
|
@subsubsection allow
|
|
The effect of the allow command is identical to the @code{allow} directive in
|
|
the configuration file (@pxref{allow directive}).
|
|
|
|
The syntax is illustrated in the following examples:
|
|
|
|
@example
|
|
allow foo.example.net
|
|
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
|
|
|
|
The effect of each of these examples is the same as that of the @code{allow}
|
|
directive in the configuration file.
|
|
@c }}}
|
|
@c {{{ authhash
|
|
@node authhash command
|
|
@subsubsection authhash
|
|
This command sets the hash function used for authenticating user commands.
|
|
For successful authentication the hash function has to be the same as the one
|
|
set for the command key in the keys file on the server. It needs to be set
|
|
before the @code{password} command is used. The default hash function is MD5.
|
|
|
|
An example is
|
|
|
|
@example
|
|
authhash SHA1
|
|
@end example
|
|
|
|
The authhash command is run automatically on start if @code{chronyc} was
|
|
started with the `-a' option.
|
|
@c }}}
|
|
@c {{{ burst
|
|
@node burst command
|
|
@subsubsection burst
|
|
The @code{burst} command tells @code{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, @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,
|
|
or offline, if the source had been indicated as being offline.
|
|
(Switching a source between the online and offline states is described
|
|
in @ref{online command}, @ref{offline command}).
|
|
|
|
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>]
|
|
burst <n-good-measurements>/<max-measurements> [<address>]
|
|
@end example
|
|
|
|
The mask and masked-address arguments are optional, in which case
|
|
@code{chronyd} will initiate a burst for all of its currently defined sources.
|
|
|
|
The arguments have the following meaning and format.
|
|
|
|
@table @code
|
|
@item n-good-measurements
|
|
This defines the number of good measurements that @code{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 @code{chronyd} to reject measurements that are likely
|
|
to be bogus.)
|
|
|
|
@item max-measurements
|
|
This defines the maximum number of measurements that @code{chronyd} will
|
|
attempt to make, even if the required number of good measurements has
|
|
not been obtained.
|
|
|
|
@item mask
|
|
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 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.
|
|
|
|
@item address
|
|
This is an IP address or a hostname. The burst command is applied only to that
|
|
source.
|
|
|
|
@end table
|
|
|
|
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
|
|
|
|
@example
|
|
burst 2/10
|
|
@end example
|
|
|
|
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.
|
|
|
|
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 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}.
|
|
|
|
Example of the three-argument form of the command is
|
|
|
|
@example
|
|
burst 2/10 foo.example.net
|
|
@end example
|
|
@c }}}
|
|
@c {{{ clients
|
|
@node clients command
|
|
@comment node-name, next, previous, up
|
|
@subsubsection clients
|
|
This command shows a list of all clients that have accessed the server,
|
|
through either the NTP or command/monitoring ports. There are no arguments.
|
|
|
|
An example of the output is
|
|
|
|
@example
|
|
Hostname Client Peer CmdAuth CmdNorm CmdBad LstN LstC
|
|
========================= ====== ====== ====== ====== ====== ==== ====
|
|
localhost 0 0 15 1 0 29y 0
|
|
aardvark.xxx 4 0 0 0 0 49 29y
|
|
badger.xxx 4 0 0 0 0 6 29y
|
|
@end example
|
|
|
|
Each row shows the data for a single host. Only hosts that have passed
|
|
the host access checks (set with the @code{allow}, @code{deny},
|
|
@code{cmdallow} and @code{cmddeny} commands or configuration file
|
|
directives) are logged.
|
|
|
|
The columns are as follows:
|
|
|
|
@enumerate 1
|
|
@item
|
|
The hostname of the client
|
|
@item
|
|
The number of times the client has accessed the server using an NTP
|
|
client mode packet.
|
|
@item
|
|
The number of times the client has accessed the server using an NTP
|
|
symmetric active mode packet.
|
|
@item
|
|
The number of authenticated command packets that have been processed
|
|
from the client (i.e. those following a successful @code{password}
|
|
command).
|
|
@item
|
|
The number of unauthenticated command packets that have been processed
|
|
from the client.
|
|
@item
|
|
The number of bad command packets received from the client (not all
|
|
forms of bad packet are logged).
|
|
@item
|
|
Time since the last NTP packet was received
|
|
@item
|
|
Time since the last command packet was received
|
|
@end enumerate
|
|
|
|
The last two entries will be shown as the time since 1970 if no packet
|
|
of that type has ever been received.
|
|
@c }}}
|
|
@c {{{ cmdaccheck
|
|
@node cmdaccheck command
|
|
@subsubsection cmdaccheck
|
|
This command is similar to the @code{accheck} command, except that it is
|
|
used to check whether command access is permitted from a named host.
|
|
|
|
Examples of use are as follows:
|
|
|
|
@example
|
|
cmdaccheck foo.example.net
|
|
cmdaccheck 1.2.3.4
|
|
cmdaccheck 2001:db8::1
|
|
@end example
|
|
@c }}}
|
|
@c {{{ cmdallow all
|
|
@node cmdallow all command
|
|
@subsubsection cmdallow all
|
|
This is similar to the @code{allow all} command, except that it is used to@c {{{
|
|
allow particular hosts or subnets to use the chronyc program to interact@c }}}
|
|
with @code{chronyd} on the current host.
|
|
@c }}}
|
|
@c {{{ cmdallow
|
|
@node cmdallow command
|
|
@subsubsection cmdallow
|
|
This is similar to the @code{allow} command, except that it is used to
|
|
allow particular hosts or subnets to use the chronyc program to interact
|
|
with @code{chronyd} on the current host.
|
|
@c }}}
|
|
@c {{{ cmddeny all
|
|
@node cmddeny all command
|
|
@subsubsection cmddeny all
|
|
This is similar to the @code{deny all} command, except that it is used
|
|
to allow particular hosts or subnets to use the chronyc program to
|
|
interact with @code{chronyd} on the current host.
|
|
@c }}}
|
|
@c {{{ cmddeny
|
|
@node cmddeny command
|
|
@subsubsection cmddeny
|
|
This is similar to the @code{deny} command, except that it is used to
|
|
allow particular hosts or subnets to use the chronyc program to interact
|
|
with @code{chronyd} on the current host.
|
|
@c }}}
|
|
@c {{{ cyclelogs
|
|
@node cyclelogs command
|
|
@subsubsection cyclelogs
|
|
The @code{cyclelogs} command causes all of @code{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.
|
|
|
|
@example
|
|
% mv /var/log/chrony/measurements.log /var/log/chrony/measurements1.log
|
|
% chronyc -a cyclelogs
|
|
% ls -l /var/log/chrony
|
|
-rw-r--r-- 1 root root 0 Jun 8 18:17 measurements.log
|
|
-rw-r--r-- 1 root root 12345 Jun 8 18:17 measurements1.log
|
|
% rm -f measurements1.log
|
|
@end example
|
|
@c }}}
|
|
@c {{{ delete
|
|
@node delete command
|
|
@subsubsection delete
|
|
The @code{delete} command allows an NTP server or peer to be removed
|
|
from the current set of sources.
|
|
|
|
The syntax is illustrated in the examples below.
|
|
|
|
@example
|
|
delete foo.example.net
|
|
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
|
|
be deleted.
|
|
@c }}}
|
|
@c {{{ deny all
|
|
@node deny all command
|
|
@subsubsection deny all
|
|
The effect of the allow command is identical to the @code{deny all}
|
|
directive in the configuration file (@pxref{deny directive}).
|
|
@c }}}
|
|
@c {{{ deny
|
|
@node deny command
|
|
@subsubsection deny
|
|
The effect of the allow command is identical to the @code{deny}
|
|
directive in the configuration file (@pxref{deny directive}).
|
|
|
|
The syntax is illustrated in the following examples:
|
|
|
|
@example
|
|
deny foo.example.net
|
|
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 }}}
|
|
@c {{{ dns
|
|
@node dns command
|
|
@subsubsection dns
|
|
The @code{dns} command configures how are hostnames and IP addresses resolved in
|
|
@code{chronyc}. IP addresses can be resolved to hostnames when printing results
|
|
of @code{sources}, @code{sourcestats}, @code{tracking} and @code{clients}
|
|
commands. Hostnames are resolved in commands that take an address as argument.
|
|
|
|
There are five forms of the command:
|
|
|
|
@table @code
|
|
@item dns -n
|
|
Disables resolving IP addresses to hostnames. Raw IP addresses will be
|
|
displayed.
|
|
@item dns +n
|
|
Enables resolving IP addresses to hostnames. This is the default unless
|
|
@code{chronyc} was started with @code{-n} option.
|
|
@item dns -4
|
|
Resolves hostnames only to IPv4 addresses.
|
|
@item dns -6
|
|
Resolves hostnames only to IPv6 addresses.
|
|
@item dns -46
|
|
Resolves hostnames to both address families. This is the default unless
|
|
@code{chronyc} was started with @code{-4} or @code{-6} option.
|
|
@end table
|
|
@c }}}
|
|
@c {{{ dump
|
|
@node dump command
|
|
@subsubsection dump
|
|
The @code{dump} command causes @code{chronyd} to write its current history of
|
|
measurements for each of its sources to dump files, either for
|
|
inspection or to support the @code{-r} option when @code{chronyd} is restarted.
|
|
|
|
The @code{dump} command is somewhat equivalent to the @code{dumponexit}
|
|
directive in the chrony configuration file. @xref{dumponexit directive}.
|
|
|
|
To use the @code{dump}, you probably want to configure the name of the
|
|
directory into which the dump files will be written. This can only be
|
|
done in the configuration file, see @ref{dumpdir directive}.
|
|
@c }}}
|
|
@c {{{ exit
|
|
@node exit command
|
|
@subsubsection exit
|
|
The exit command exits from chronyc and returns the user to the shell
|
|
(same as the quit command).
|
|
@c }}}
|
|
@c {{{ help
|
|
@node help command
|
|
@subsubsection help
|
|
The help command displays a summary of the commands and their arguments.
|
|
@c }}}
|
|
@c {{{ local
|
|
@node local command
|
|
@subsubsection local
|
|
The @code{local} command allows @code{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
|
|
one computer to be a master time server with the other computers slaving
|
|
to it.) The @code{local} command is somewhat equivalent to the
|
|
@code{local} directive in the configuration file, see @ref{local directive}.
|
|
|
|
The syntax is as shown in the following examples.
|
|
|
|
@example
|
|
local stratum 10
|
|
local off
|
|
@end example
|
|
|
|
The first example enables the local reference mode on the host, and sets
|
|
the stratum at which it should claim to be synchronised.
|
|
|
|
The second example disables the local reference mode.
|
|
@c }}}
|
|
@c {{{ makestep
|
|
@node makestep command
|
|
@subsubsection makestep
|
|
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 may be so far adrift that this
|
|
slewing process would take a very long time to correct the system clock.
|
|
|
|
The @code{makestep} command can be used in this situation. There are two forms
|
|
of the command. The first form has no parameters. It tells @code{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
|
|
@code{makestep} directive (@pxref{makestep directive}). It has two parameters,
|
|
stepping threshold (in seconds) and number of future clock updates for which
|
|
will be the threshold active. This can be used with the @code{burst} command
|
|
to quickly make a new measurement and correct the clock by stepping if needed,
|
|
without waiting for @code{chronyd} to complete the measurement and update the
|
|
clock.
|
|
|
|
@example
|
|
makestep 0.1 1
|
|
burst 1/2
|
|
@end example
|
|
|
|
BE WARNED - certain software will be seriously affected by such jumps to
|
|
the system time. (That is the reason why chronyd uses slewing
|
|
normally.)
|
|
@c }}}
|
|
@c {{{ manual
|
|
@node manual command
|
|
@subsubsection manual
|
|
The manual command enables and disables use of the @code{settime}
|
|
command (@pxref{settime command}), and is used to modify the behaviour
|
|
of the manual clock driver.
|
|
|
|
Examples of the command are shown below.
|
|
|
|
@example
|
|
manual on
|
|
manual off
|
|
manual delete 1
|
|
manual list
|
|
manual reset
|
|
@end example
|
|
|
|
The @code{on} form of the command enables use of the @code{settime}
|
|
command.
|
|
|
|
The @code{off} form of the command disables use of the @code{settime}
|
|
command.
|
|
|
|
The @code{list} form of the command lists all the samples currently
|
|
stored in @code{chronyd}. The output is illustrated below.
|
|
|
|
@example
|
|
210 n_samples = 1
|
|
# Date Time(UTC) Slewed Original Residual
|
|
====================================================
|
|
0 27Jan99 22:09:20 0.00 0.97 0.00
|
|
@end example
|
|
|
|
The columns as as follows :
|
|
|
|
@enumerate 1
|
|
@item
|
|
The sample index (used for the @code{manual delete} command)
|
|
@item
|
|
The date and time of the sample
|
|
@item
|
|
The system clock error when the timestamp was entered, adjusted to allow
|
|
for changes made to the system clock since.
|
|
@item
|
|
The system clock error when the timestamp was entered, as it originally
|
|
was (without allowing for changes to the system clock since).
|
|
@item
|
|
The regression residual at this point, in seconds. This allows
|
|
'outliers' to be easily spotted, so that they can be deleted using the
|
|
@code{manual delete} command.
|
|
@end enumerate
|
|
|
|
The @code{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 @code{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 he/she has entered a very poor
|
|
timestamp.
|
|
|
|
The @code{reset} form of the command deletes all samples at once. The
|
|
system clock is left running as it was before the command was entered.
|
|
@c }}}
|
|
@c {{{ maxdelay
|
|
@node maxdelay command
|
|
@subsubsection maxdelay
|
|
This allows the @code{maxdelay} option for one of the sources to be
|
|
modified, in the same way as specifying the @code{maxdelay} option for
|
|
the @code{server} directive in the configuration file (@pxref{server
|
|
directive}).
|
|
|
|
The following examples illustrate the syntax
|
|
|
|
@example
|
|
maxdelay foo.example.net 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.example.net} to 0.3 seconds. The second
|
|
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.)
|
|
@c }}}
|
|
@c {{{ maxdelaydevratio
|
|
@node maxdelaydevratio command
|
|
@subsubsection maxdelaydevratio
|
|
This allows the @code{maxdelaydevratio} option for one of the sources to be
|
|
modified, in the same way as specifying the @code{maxdelaydevratio} option
|
|
for the @code{server} directive in the configuration file (@pxref{server
|
|
directive}).
|
|
|
|
The following examples illustrate the syntax
|
|
|
|
@example
|
|
maxdelaydevratio foo.example.net 0.1
|
|
maxdelaydevratio 1.2.3.4 1.0
|
|
maxdelaydevratio 2001:db8::1 100.0
|
|
@end example
|
|
@c }}}
|
|
@c {{{ maxdelayratio
|
|
@node maxdelayratio command
|
|
@subsubsection maxdelayratio
|
|
This allows the @code{maxdelayratio} option for one of the sources to be
|
|
modified, in the same way as specifying the @code{maxdelayratio} option
|
|
for the @code{server} directive in the configuration file (@pxref{server
|
|
directive}).
|
|
|
|
The following examples illustrate the syntax
|
|
|
|
@example
|
|
maxdelayratio foo.example.net 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.example.net} to be 1.5 times the minimum delay found
|
|
amongst the previous measurements that have been retained. The second
|
|
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.
|
|
@c }}}
|
|
@c {{{ maxpoll
|
|
@node maxpoll command
|
|
@subsubsection maxpoll
|
|
The @code{maxpoll} command is used to modify the minimum polling
|
|
interval for one of the current set of sources. It is equivalent to the
|
|
@code{maxpoll} option in the @code{server} directive in the
|
|
configuration file (@pxref{server directive}).
|
|
|
|
The syntax is as follows
|
|
|
|
@example
|
|
maxpoll <host> <new-maxpoll>
|
|
@end example
|
|
|
|
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).
|
|
|
|
An example is
|
|
|
|
@example
|
|
maxpoll foo.example.net 10
|
|
@end example
|
|
|
|
which sets the maximum polling interval for the host @code{foo.example.net}
|
|
to 1024 seconds.
|
|
|
|
Note that the new maximum polling interval only takes effect after the
|
|
next measurement has been made.
|
|
@c }}}
|
|
@c {{{ maxupdateskew
|
|
@node maxupdateskew command
|
|
@subsubsection maxupdateskew
|
|
This command has the same effect as the @code{maxupdateskew} directive
|
|
in the configuration file, see @ref{maxupdateskew directive}.
|
|
@c }}}
|
|
@c {{{ minpoll
|
|
@node minpoll command
|
|
@subsubsection minpoll
|
|
The @code{minpoll} command is used to modify the minimum polling
|
|
interval for one of the current set of sources. It is equivalent to the
|
|
@code{minpoll} option in the @code{server} directive in the
|
|
configuration file (@pxref{server directive}).
|
|
|
|
The syntax is as follows
|
|
|
|
@example
|
|
minpoll <host> <new-minpoll>
|
|
@end example
|
|
|
|
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).
|
|
|
|
An example is
|
|
|
|
@example
|
|
minpoll foo.example.net 5
|
|
@end example
|
|
|
|
which sets the minimum polling interval for the host @code{foo.example.net}
|
|
to 32 seconds.
|
|
|
|
Note that the new minimum polling interval only takes effect after the
|
|
next measurement has been made.
|
|
@c }}}
|
|
@c {{{ minstratum
|
|
@node minstratum command
|
|
@subsubsection minstratum
|
|
The @code{minstratum} command is used to modify the minimum stratum
|
|
for one of the current set of sources. It is equivalent to the
|
|
@code{minstratum} option in the @code{server} directive in the
|
|
configuration file (@pxref{server directive}).
|
|
|
|
The syntax is as follows
|
|
|
|
@example
|
|
minstratum <host> <new-min-stratum>
|
|
@end example
|
|
|
|
where the host can be specified as either a machine name or
|
|
IP address.
|
|
|
|
An example is
|
|
|
|
@example
|
|
minpoll foo.example.net 5
|
|
@end example
|
|
|
|
which sets the minimum stratum for the host @code{foo.example.net}
|
|
to 5.
|
|
|
|
Note that the new minimum stratum only takes effect after the
|
|
next measurement has been made.
|
|
@c }}}
|
|
@c {{{ offline
|
|
@node offline command
|
|
@subsubsection offline
|
|
The @code{offline} command is used to warn @code{chronyd} that the network
|
|
connection to a particular host or hosts is about to be lost. It should
|
|
be used on computers with a dial-up or similar connection to their time
|
|
sources, to warn @code{chronyd} that the connection is about to be broken.
|
|
|
|
An example of how to use @code{offline} in this case is shown in
|
|
@ref{Advising chronyd of internet availability}.
|
|
|
|
Another case where @code{offline} could be used is where a computer
|
|
serves time to a local group of computers, and has a permanant
|
|
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/loss rate during
|
|
the quiet periods and let the whole network coast through the loaded
|
|
periods. The @code{offline} and @code{online} commands can be used to
|
|
achieve this. The situation is shown in the figure below.
|
|
|
|
@example
|
|
@group
|
|
+----------+
|
|
|Ext source|
|
|
+----------+
|
|
|
|
|
|
|
|
|/| <-- Link with variable
|
|
| reliability
|
|
|
|
|
+-------------------+
|
|
|Local master server|
|
|
+-------------------+
|
|
|
|
|
+---+---+-----+-----+----+----+
|
|
| | | | | | |
|
|
Local clients
|
|
@end group
|
|
@end example
|
|
|
|
|
|
|
|
If the source to which @code{chronyd} is currently synchronised is indicated
|
|
offline in this way, @code{chronyd} will continue to treat it as the
|
|
synchronisation source. If the network connection were broken without
|
|
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 four forms of the @code{offline} command. The first form is a
|
|
wildcard, meaning all sources. The second form allows an IP address mask
|
|
and a masked address to be specified. The third form uses the CIDR
|
|
notation. The fourth form uses an IP address or a hostname. These forms are
|
|
illustrated below.
|
|
|
|
@example
|
|
offline
|
|
offline 255.255.255.0/1.2.3.0
|
|
offline 2001:db8:789a::/48
|
|
offline foo.example.net
|
|
@end example
|
|
|
|
The second form means that the @code{offline} command is to be applied
|
|
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). 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 fourth form means that the command
|
|
is to be applied only to that one source.
|
|
|
|
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
|
|
@node online command
|
|
@subsubsection online
|
|
The @code{online} command is opposite in function to the @code{offline}
|
|
command. It is used to advise @code{chronyd} that network connectivity to a
|
|
particular source or sources has been restored.
|
|
|
|
The syntax is identical to that of the @code{offline} command, see
|
|
@ref{offline command}.
|
|
@c }}}
|
|
@c {{{ password
|
|
@node password command
|
|
@subsubsection password
|
|
The password command is used to allow chronyc to send privileged
|
|
commands to @code{chronyd}. The password can either be entered on the command
|
|
line, or can be entered without echoing. The syntax for entering the
|
|
password on the command line is as follows
|
|
|
|
@example
|
|
password xyzzy
|
|
password ASCII:xyzzy
|
|
password HEX:78797a7a79
|
|
@end example
|
|
|
|
To enter the password without it being echoed, enter
|
|
|
|
@example
|
|
password
|
|
@end example
|
|
|
|
The computer will respond with a @samp{Password:} prompt, at which you
|
|
should enter the password and press return.
|
|
|
|
The password can be encoded as a string of characters not containing a space
|
|
with optional @code{ASCII:} prefix or as a hexadecimal number with @code{HEX:}
|
|
prefix. It has to match @code{chronyd's} currently defined command key
|
|
(@pxref{commandkey directive}).
|
|
|
|
The password command is run automatically on start if @code{chronyc} was
|
|
started with the `-a' option.
|
|
@c }}}
|
|
@c {{{ polltarget
|
|
@node polltarget command
|
|
@subsubsection polltarget
|
|
The @code{polltarget} command is used to modify the poll target for
|
|
one of the current set of sources. It is equivalent to the
|
|
@code{polltarget} option in the @code{server} directive in the
|
|
configuration file (@pxref{server directive}).
|
|
|
|
The syntax is as follows
|
|
|
|
@example
|
|
polltarget <host> <new-poll-target>
|
|
@end example
|
|
|
|
where the host can be specified as either a machine name or
|
|
IP address.
|
|
|
|
An example is
|
|
|
|
@example
|
|
polltarget foo.example.net 12
|
|
@end example
|
|
|
|
which sets the poll target for the host @code{foo.example.net}
|
|
to 12.
|
|
@c }}}
|
|
@c {{{ quit
|
|
@node quit command
|
|
@subsubsection quit
|
|
The quit command exits from chronyc and returns the user to the shell
|
|
(same as the exit command).
|
|
@c }}}
|
|
@c {{{ reselect command
|
|
@node reselect command
|
|
@subsubsection reselect
|
|
To avoid excessive switching between sources, @code{chronyd} may stay
|
|
synchronised to a source even when it is not currently the best one among the
|
|
available sources.
|
|
|
|
The @code{reselect} command can be used to force @code{chronyd} to
|
|
reselect the best synchronisation source.
|
|
@c }}}
|
|
@c {{{ reselectdist command
|
|
@node reselectdist command
|
|
@subsubsection reselectdist
|
|
The @code{reselectdist} command sets the reselect distance. It is equivalent
|
|
to the @code{reselectdist} directive in the configuration file
|
|
(@pxref{reselectdist directive}).
|
|
@c }}}
|
|
@c {{{ retries
|
|
@node retries command
|
|
@subsubsection retries
|
|
The @code{retries} command sets the maximum number of retries for
|
|
@code{chronyc} requests before giving up. The response timeout is controlled
|
|
by @code{timeout} command (@pxref{timeout command}).
|
|
|
|
The default is 2.
|
|
@c }}}
|
|
@c {{{ rtcdata
|
|
@node rtcdata command
|
|
@subsubsection rtcdata
|
|
The @code{rtcdata} command displays the current real time clock RTC parameters.
|
|
|
|
An example output is shown below.
|
|
|
|
@example
|
|
RTC ref time (GMT) : Sat May 30 07:25:56 1998
|
|
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
|
|
@end example
|
|
|
|
The fields have the following meaning
|
|
|
|
@table @code
|
|
@item RTC ref time (GMT)
|
|
This is the RTC reading the last time its error was measured.
|
|
@item Number of samples
|
|
This is the number of previous measurements being used to determine the
|
|
RTC gain/loss rate.
|
|
@item 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.
|
|
@item 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 may be used.
|
|
@item 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
|
|
may (or may not) want to use the @code{trimrtc} command to bring the RTC
|
|
into line with the system clock. (Note, a large error will not affect
|
|
@code{chronyd's} operation, unless it becomes so big as to start causing
|
|
rounding errors.
|
|
@item 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.
|
|
@end table
|
|
@c }}}
|
|
@c {{{ settime
|
|
@node settime command
|
|
@subsubsection settime
|
|
The @code{settime} command allows the current time to be entered
|
|
manually, if this option has been configured into @code{chronyd}. (It may be
|
|
configured either with the @code{manual} directive in the configuration
|
|
file (@pxref{manual directive}), or with the @code{manual} command of
|
|
chronyc (@pxref{manual command}).
|
|
|
|
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 @code{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 @code{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 @code{manual delete} command, where the
|
|
intercept is used to set the current offset (since there is no
|
|
measurement that has just been typed in in that case).
|
|
|
|
The time is parsed by the public domain @file{getdate} algorithm.
|
|
Consequently, you can only specify time to the nearest second.
|
|
|
|
Examples of inputs that are valid are shown below.
|
|
|
|
@example
|
|
settime 16:30
|
|
settime 16:30:05
|
|
settime Nov 21, 1997 16:30:05
|
|
@end example
|
|
|
|
For a full description of @code{getdate}, get hold of the getdate
|
|
documentation (bundled, for example, with the source for GNU tar).
|
|
@c }}}
|
|
@c {{{ sources
|
|
@node sources command
|
|
@subsubsection sources
|
|
This command displays information about the current time sources that
|
|
@code{chronyd} is accessing.
|
|
|
|
The optional argument @code{-v} can be specified, meaning @emph{verbose}. In
|
|
this case, extra caption lines are shown as a reminder of the meanings of the
|
|
columns.
|
|
|
|
@example
|
|
@group
|
|
210 Number of sources = 3
|
|
MS Name/IP address Stratum Poll Reach LastRx Last sample
|
|
===============================================================================
|
|
#* GPS0 0 4 377 11 -479ns[ -621ns] +/- 134ns
|
|
^? foo.example.net 2 6 377 23 -923us[ -924us] +/- 43ms
|
|
^+ bar.example.net 1 6 377 21 -2629us[-2619us] +/- 86ms
|
|
@end group
|
|
@end example
|
|
|
|
The columns are as follows:
|
|
|
|
@table @code
|
|
@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.
|
|
|
|
@item S
|
|
This column indicates the state of the sources. @code{*} indicates the
|
|
source to which @code{chronyd} is currently synchronised. @code{+}
|
|
indicates acceptable sources which are combined with the selected
|
|
source. @code{-} indicates acceptable sources which are excluded by
|
|
the combining algorithm. @code{?} indicates sources to which
|
|
connectivity has been lost or whose packets don't pass all tests.
|
|
@code{x} indicates a clock which @code{chronyd}
|
|
thinks is is a falseticker (i.e. its time is inconsistent with a
|
|
majority of other sources). @code{~} indicates a source whose time
|
|
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, or refid for
|
|
reference clocks.
|
|
|
|
@item 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.
|
|
|
|
@item 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.
|
|
|
|
@code{chronyd} automatically varies the polling rate in response to prevailing
|
|
conditions.
|
|
|
|
@item Reach
|
|
This shows the source's reachability register printed as 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.
|
|
|
|
@item LastRx
|
|
This column shows how long ago the last sample was received from the
|
|
source. This is normally in seconds. The letters @code{m}, @code{h},
|
|
@code{d} or @code{y} indicate minutes, hours, days or years. A value
|
|
of 10 years indicates there were no samples received from this source
|
|
yet.
|
|
|
|
@item 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 may be suffixed by @code{ns} (indicating
|
|
nanoseconds), @code{us} (indicating
|
|
microseconds), @code{ms} (indicating milliseconds), or @code{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. The number following the @code{+/-} indicator
|
|
shows the margin of error in the measurement.
|
|
|
|
Positive offsets indicate that the local clock is fast of the source.
|
|
|
|
@end table
|
|
@c }}}
|
|
@c {{{ sourcestats
|
|
@node sourcestats command
|
|
@subsubsection sourcestats
|
|
|
|
The @code{sourcestats} command displays information about the drift rate
|
|
and offset estimatation process for each of the sources currently being
|
|
examined by @code{chronyd}.
|
|
|
|
The optional argument @code{-v} can be specified, meaning @emph{verbose}. In
|
|
this case, extra caption lines are shown as a reminder of the meanings of the
|
|
columns.
|
|
|
|
An example report is
|
|
|
|
@example
|
|
@group
|
|
210 Number of sources = 1
|
|
Name/IP Address NP NR Span Frequency Freq Skew Offset Std Dev
|
|
===============================================================================
|
|
abc.def.ghi 11 5 46m -0.001 0.045 1us 25us
|
|
@end group
|
|
@end example
|
|
|
|
The columns are as follows
|
|
|
|
@table @code
|
|
@item Name/IP Address
|
|
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
|
|
server. The drift rate and current offset are estimated by performing a
|
|
linear regression through these points.
|
|
|
|
@item 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,
|
|
@code{chronyd} discards older samples and re-runs the regression until
|
|
the number of runs becomes acceptable.
|
|
|
|
@item 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.
|
|
|
|
@item 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.
|
|
|
|
@item Freq Skew
|
|
This is the estimated error bounds on @code{Freq} (again in parts per
|
|
million).
|
|
|
|
@item Offset
|
|
This is the estimated offset of the source.
|
|
|
|
@item Std Dev
|
|
This is the estimated sample standard deviation.
|
|
|
|
@end table
|
|
@c }}}
|
|
@c {{{ timeout
|
|
@node timeout command
|
|
@subsubsection timeout
|
|
The @code{timeout} command sets the initial timeout for @code{chronyc} requests
|
|
in milliseconds. If no response is received from @code{chronyd}, the timeout is
|
|
doubled and the request is resent. The maximum number of retries is configured
|
|
with the @code{retries} command (@pxref{retries command}).
|
|
|
|
By default, the timeout is 1000 milliseconds or 100 milliseconds if
|
|
@code{chronyc} is contacting localhost (i.e. the `-h' option wasn't specified)
|
|
and @code{chronyd} was compiled with asynchronous name resolving.
|
|
@c }}}
|
|
@c {{{ tracking
|
|
@node tracking command
|
|
@subsubsection tracking
|
|
The @code{tracking} command displays parameters about the system's clock
|
|
performance. An example of the output is shown below.
|
|
|
|
@example
|
|
Reference ID : 1.2.3.4 (foo.example.net)
|
|
Stratum : 3
|
|
Ref time (UTC) : Fri Feb 3 15:00:29 2012
|
|
System time : 0.000001501 seconds slow of NTP time
|
|
Last offset : -0.000001632 seconds
|
|
RMS offset : 0.000002360 seconds
|
|
Frequency : 331.898 ppm fast
|
|
Residual freq : 0.004 ppm
|
|
Skew : 0.154 ppm
|
|
Root delay : 0.373169 seconds
|
|
Root dispersion : 0.024780 seconds
|
|
Update interval : 64.2 seconds
|
|
Leap status : Normal
|
|
|
|
@end example
|
|
|
|
The fields are explained as follows.
|
|
|
|
@table @code
|
|
@item Reference ID
|
|
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
|
|
in @code{chronyc} (@pxref{local command}), or the @code{local} directive
|
|
in the @file{@SYSCONFDIR@/chrony.conf} file (@pxref{local directive})).
|
|
|
|
@item 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. @code{foo.example.net} is a stratum-2 and is synchronised from a stratum-1).
|
|
|
|
@item Ref time
|
|
This is the time (UTC) at which the last measurement from the reference
|
|
source was processed.
|
|
|
|
@item System time
|
|
In normal operation, @code{chronyd} @emph{never} steps the system clock,
|
|
because any jump in the timescale can have adverse consequences for
|
|
certain application programs. Instead, any error in the system clock is
|
|
corrected by slightly speeding up or slowing down the system clock until
|
|
the error has been removed, and then returning to the system clock's
|
|
normal speed. A consequence of this is that there will be a period when
|
|
the system clock (as read by other programs using the
|
|
@code{gettimeofday()} system call, or by the @code{date} command in the
|
|
shell) will be different from @code{chronyd's} estimate of the current
|
|
true time (which it reports to NTP clients when it is operating in
|
|
server mode). The value reported on this line is the difference due to
|
|
this effect.
|
|
|
|
On systems other than Linux, @code{chronyd} doesn't
|
|
adjust the fundamental rate of the system clock, so keeps the system
|
|
time correct by periodically making offsets to it as though an error had
|
|
been measured. The build up of these offsets will be observed in this
|
|
report.
|
|
|
|
@item Last offset
|
|
This is the estimated local offset on the last clock update.
|
|
|
|
@item RMS offset
|
|
This is a long-term average of the offset value.
|
|
|
|
@item Frequency
|
|
The `frequency' is the rate by which the system's clock would be would
|
|
be wrong if @code{chronyd} was not correcting it. It is expressed in
|
|
ppm (parts per million). For example, a value of 1ppm 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.
|
|
|
|
As you can see in the example, the clock in the computer is not a very
|
|
good one - it gains about 30 seconds per day!
|
|
|
|
@item 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.
|
|
|
|
@item Skew
|
|
This is the estimated error bound on the the frequency.
|
|
|
|
@item Root delay
|
|
This is the total of the network path delays to the stratum-1 computer
|
|
from which the computer is ultimately synchronised.
|
|
|
|
@item 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
|
|
|
|
@example
|
|
clock_error <= root_dispersion + (0.5 * |root_delay|)
|
|
@end example
|
|
|
|
@item Update interval
|
|
This is the interval between the last two clock updates.
|
|
|
|
@item Leap status
|
|
This is the leap status, which can be @code{Normal}, @code{Insert second},
|
|
@code{Delete second} or @code{Not synchronised}.
|
|
|
|
@end table
|
|
@c }}}
|
|
@c {{{ trimrtc
|
|
@node trimrtc command
|
|
@subsubsection trimrtc
|
|
The @code{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
|
|
resolution of the RTC is only 1 second).
|
|
|
|
The command takes no arguments. It performs the following steps (if the
|
|
RTC is more than 1 second away from the system clock):
|
|
|
|
@enumerate 1
|
|
@item
|
|
Remember the currently estimated gain/loss rate of the RTC and flush the
|
|
previous measurements.
|
|
@item
|
|
Step the real time clock to bring it within a second of the system clock.
|
|
@item
|
|
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)
|
|
@item
|
|
Save the RTC parameters to the RTC file (specified with the
|
|
@code{rtcfile} directive in the configuration file (@pxref{rtcfile
|
|
directive}).
|
|
@end enumerate
|
|
|
|
The last step is done as a precaution against the computer suffering a
|
|
power failure before either the daemon exits or the @code{writertc}
|
|
command is issued.
|
|
|
|
@code{chronyd} will still work perfectly well both whilst operating and
|
|
across machine reboots even if the @code{trimrtc} command is never used
|
|
(and the RTC is allowed to drift away from true time). The
|
|
@code{trimrtc} command is provided as a method by which it can be
|
|
corrected, in a manner compatible with @code{chronyd} using it to
|
|
maintain accurate time across machine reboots.
|
|
|
|
The @code{trimrtc} command can be executed automatically by @code{chronyd}
|
|
with the @code{rtcautotrim} directive (@pxref{rtcautotrim directive}).
|
|
@c }}}
|
|
@c {{{ waitsync
|
|
@node waitsync command
|
|
@subsubsection waitsync
|
|
The @code{waitsync} command waits for @code{chronyd} to synchronise.
|
|
|
|
Up to three optional arguments can be specified, the first is the maximum
|
|
number of tries in 10 second intervals 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
|
|
@code{tracking} command (@pxref{tracking command}) in the @code{System time}
|
|
and @code{Skew} fields. If not specified or zero, the value will not be
|
|
checked.
|
|
|
|
An example is
|
|
|
|
@example
|
|
waitsync 60 0.01
|
|
@end example
|
|
|
|
which will wait up to about 10 minutes for @code{chronyd} to synchronise to a
|
|
source and the remaining correction to be less than 10 milliseconds.
|
|
@c }}}
|
|
@c {{{ writertc
|
|
@node writertc command
|
|
@subsubsection writertc
|
|
The @code{writertc} command writes the currently estimated error and
|
|
gain/loss rate parameters for the RTC to the RTC file (specified with
|
|
the @code{rtcfile} directive (@pxref{rtcfile directive})). This
|
|
information is also written automatically when @code{chronyd} is killed
|
|
(with SIGHUP, SIGINT, SIGQUIT or SIGTERM) or when the @code{trimrtc}
|
|
command is issued.
|
|
@c }}}
|
|
@c }}}
|
|
@c }}}
|
|
@c }}}
|
|
@c {{{ Ch:FAQ
|
|
@node FAQ
|
|
@chapter Frequently asked questions
|
|
|
|
@c {{{ Chapter top
|
|
@menu
|
|
* Administrative issues::
|
|
* Chrony compared to other programs::
|
|
* Configuration issues::
|
|
* Computer is not synchronising::
|
|
* Issues with chronyc::
|
|
* Real-time clock issues::
|
|
* Microsoft Windows::
|
|
* NTP-specific issues::
|
|
* Linux-specific issues::
|
|
* Solaris-specific issues::
|
|
@end menu
|
|
@c }}}
|
|
@c {{{ S:Administrative issues
|
|
@node Administrative issues
|
|
@section Administrative issues
|
|
|
|
@subsection Where can I get chrony source code?
|
|
Tarballs are available via the @code{Download} link on the chrony web site.
|
|
For the current development from the developers' version control system see the
|
|
@code{Git} link on the web site.
|
|
|
|
@subsection Are there any packaged versions of chrony?
|
|
We are aware of packages for Arch, CentOS, Debian, Fedora, Gentoo, Mageia,
|
|
OpenSuse, Slackware, Ubuntu, FreeBSD and NetBSD. We are not involved with how
|
|
these are built or distributed.
|
|
|
|
@subsection Where is the home page?
|
|
It is currently at
|
|
@uref{http://chrony.tuxfamily.org, http://chrony.tuxfamily.org}.
|
|
|
|
@subsection Is there a mailing list?
|
|
Yes, it's currently at @email{chrony-users@@chrony.tuxfamily.org}. There is a
|
|
low-volume list called chrony-announce which is just for announcements of new
|
|
releases or similar matters of high importance. You can join the lists by
|
|
sending a message with the subject subscribe to
|
|
@email{chrony-users-request@@chrony.tuxfamily.org} or
|
|
@email{chrony-announce-request@@chrony.tuxfamily.org} respectively.
|
|
|
|
For those who want to contribute to the development of chrony, there is a
|
|
developers' mailing list. You can subscribe by sending mail with the subject
|
|
subscribe to @email{chrony-dev-request@@chrony.tuxfamily.org}.
|
|
|
|
@subsection What licence is applied to chrony?
|
|
Starting from version 1.15, chrony is licensed under the GNU General Public
|
|
License, Version 2. Versions prior to 1.15 were licensed under a custom
|
|
BSD-like license.
|
|
@c }}}
|
|
@c {{{ S:Chrony compared to other programs
|
|
@node Chrony compared to other programs
|
|
@section Chrony compared to other programs
|
|
@subsection How does chrony compare to ntpd?
|
|
Chrony can usually synchronise the system clock faster and with better time
|
|
accuracy, but it doesn't implement all NTP features, e.g. broadcast/multicast
|
|
mode, or authentication based on public-key cryptography. For a more detailed
|
|
comparison, see section @code{Comparison with ntpd} in the manual.
|
|
|
|
If your computer connects to the 'net only for few minutes at a time, you turn
|
|
your Linux computer off or suspend it frequently, the clock is not very stable
|
|
(e.g. it is a virtual machine), or you want to use NTP on an isolated network
|
|
with no hardware clocks in sight, chrony will probably work much better for
|
|
you.
|
|
|
|
The original reason chrony was written was that ntpd (called xntpd at the
|
|
time) could not to do anything sensible on a PC which was connected to
|
|
the 'net only for about 5 minutes once or twice a day, mainly to
|
|
upload/download email and news. The requirements were
|
|
|
|
@itemize @bullet
|
|
@item slew the time to correct it when going online and NTP servers become
|
|
visible
|
|
@item determine the rate at which the computer gains or loses time and use this
|
|
information to keep it reasonably correct between connects to the 'net. This
|
|
has to be done using a method that does not care about the intermittent
|
|
availability of the references or the fact the computer is turned off between
|
|
groups of measurements.
|
|
@item maintain the time across reboots, by working out the error and drift rate
|
|
of the computer's real-time clock and using this information to set the system
|
|
clock correctly at boot up.
|
|
@end itemize
|
|
|
|
Also, when working with isolated networks with no true time references at all
|
|
ntpd was found to give no help with managing the local clock's gain/loss rate
|
|
on the NTP master node (which was set from watch). Some automated support was
|
|
added to chrony to deal with this.
|
|
|
|
@c }}}
|
|
@c {{{ S:Configuration issues
|
|
@node Configuration issues
|
|
@section Configuration issues
|
|
|
|
@subsection I have several computers on a LAN. Should be all clients of an external server?
|
|
The best configuration is usually to make one computer the master, with the
|
|
others as clients of it. Add a @code{local} directive to the master's
|
|
chrony.conf file. This configuration will be better because
|
|
|
|
@itemize @bullet
|
|
@item the load on the external connection is less
|
|
@item the load on the external NTP server(s) is less
|
|
@item if your external connection goes down, the computers on the LAN will
|
|
maintain a common time with each other.
|
|
@end itemize
|
|
|
|
@subsection Must I specify servers by IP address if DNS is not available on chronyd start?
|
|
No. Starting from version 1.25, @code{chronyd} will keep trying to resolve the
|
|
hostnames specified in the @code{server} and @code{peer} directives in
|
|
increasing intervals until it succeeds. The @code{online} command can be
|
|
issued from @code{chronyc} to try to resolve them immediately.
|
|
|
|
@subsection How can I make chronyd more secure?
|
|
If you don't need to serve time to NTP clients or peers, you can add
|
|
@code{port 0} to the @file{chrony.conf} file to completely disable the NTP
|
|
server functionality and prevent NTP requests from reaching @code{chronyd}.
|
|
Starting from version 2.0, the NTP server port is open only when client access
|
|
is allowed by the @code{allow} directive or command, an NTP peer is configured,
|
|
or the @code{broadcast} directive is used.
|
|
|
|
If you don't need to use @code{chronyc} remotely, you can add the following
|
|
directives to the configuration file to bind the command sockets to the
|
|
loopback interface. This is done by default since version 2.0.
|
|
|
|
@example
|
|
bindcmdaddress 127.0.0.1
|
|
bindcmdaddress ::1
|
|
@end example
|
|
|
|
If you don't need to use @code{chronyc} at all, you can disable the command
|
|
sockets by adding @code{cmdport 0} to the configuration file.
|
|
|
|
On Linux, if @code{chronyd} is compiled with support for Linux capabilities
|
|
(available in the libcap library), you can specify an unprivileged user with
|
|
the `-u' option or @code{user} directive in the @file{chrony.conf} file to drop
|
|
root privileges after start. The configure option @code{--with-user} can be
|
|
used to drop the privileges by default.
|
|
|
|
@subsection How can I improve the accuracy of the system clock with NTP sources?
|
|
Select NTP servers that are well synchronised, stable and close to your network.
|
|
It's better to use more than one server, three or four is usually recommended as
|
|
the minimum, so @code{chronyd} can detect falsetickers and combine measurements
|
|
from multiple sources.
|
|
|
|
There are also useful options which can be set in the @code{server} directive,
|
|
they are @code{minpoll}, @code{maxpoll}, @code{polltarget}, @code{maxdelay},
|
|
@code{maxdelayratio} and @code{maxdelaydevratio}.
|
|
|
|
The first three options set the minimum and maximum allowed polling interval,
|
|
and how should be the actual interval adjusted in the specified range. Their
|
|
default values are 6 (64 seconds) for @code{minpoll}, 10 (1024 seconds) for
|
|
@code{maxpoll} and 6 (samples) for @code{polltarget}. The default values
|
|
should be used for general servers on the internet. With your own NTP servers
|
|
or if have permission to poll some servers more frequently, setting these
|
|
options for shorter polling intervals may significantly improve the accuracy of
|
|
the system clock.
|
|
|
|
The optimal polling interval depends on many factors, including the ratio
|
|
between the wander of the clock and the network jitter (sometimes expressed in
|
|
NTP documents as the Allan intercept), the temperature sensitivity of the
|
|
crystal oscillator and the maximum rate of change of the temperature.
|
|
|
|
An example of the directive for an NTP server on the internet that you are
|
|
allowed to poll frequently could be
|
|
|
|
@example
|
|
server foo.example.net minpoll 4 maxpoll 6 polltarget 16
|
|
@end example
|
|
|
|
An example using very short polling intervals for a server located in the
|
|
same LAN could be
|
|
|
|
@example
|
|
server ntp.local minpoll 2 maxpoll 4 polltarget 30
|
|
@end example
|
|
|
|
The maxdelay options are useful to ignore measurements with larger delay (e.g.
|
|
due to congestion in the network) and improve the stability of the
|
|
synchronisation. The @code{maxdelaydevratio} option could be added to the
|
|
example with local NTP server
|
|
|
|
@example
|
|
server ntp.local minpoll 2 maxpoll 4 polltarget 30 maxdelaydevratio 2
|
|
@end example
|
|
|
|
@c }}}
|
|
@c {{{ S:Computer is not synchronising
|
|
@node Computer is not synchronising
|
|
@section Computer is not synchronising
|
|
|
|
This is the most common problem. There are a number of reasons, see the
|
|
following questions.
|
|
|
|
@subsection Behind a firewall?
|
|
If there is a firewall between you and the NTP server you're trying to use,
|
|
the packets may be blocked. Try using a tool like wireshark or tcpdump to see
|
|
if you're getting responses from the server. If you have an external modem,
|
|
see if the receive light blinks straight after the transmit light (when the
|
|
link is quiet apart from the NTP traffic.) Try adding @code{log measurements}
|
|
to the @file{chrony.conf} file and look in the measurements.log file after
|
|
chrony has been running for a short period. See if any measurements appear.
|
|
|
|
@subsection Do you have a non-permanent (i.e. intermittent) Internet connection?
|
|
Check that you're using chronyc's @code{online} and @code{offline} commands
|
|
appropriately. Again, check in measurements.log to see if you're getting any
|
|
data back from the server.
|
|
|
|
@subsection In measurements.log, do the '7' and '8' flag columns always show zero?
|
|
Do you have a @code{local stratum X} directive in the @file{chrony.conf} file? If X
|
|
is lower than the stratum of the server you're trying to use, this situation
|
|
will arise. You should always make X quite high (e.g. 10) in this directive.
|
|
@c }}}
|
|
@c {{{ S:Issues with chronyc
|
|
@node Issues with chronyc
|
|
@section Issues with chronyc
|
|
|
|
@subsection I keep getting the error @code{506 Cannot talk to daemon}
|
|
When accessing @code{chronyd} remotely, make sure that the @file{chrony.conf}
|
|
file (on the computer where @code{chronyd} is running) has a @code{cmdallow}
|
|
entry for the computer you are running @code{chronyc} on and an appropriate
|
|
@code{bindcmdaddress} directive. This isn't necessary for localhost.
|
|
|
|
Perhaps @code{chronyd} is not running. Try using the ps command (e.g. on
|
|
Linux, 'ps -auxw') to see if it's running. Or try 'netstat -a' and see if the
|
|
ports 123/udp and 323/udp are listening. If @code{chronyd} is not running, you
|
|
may have a problem with the way you are trying to start it (e.g. at boot time).
|
|
|
|
Perhaps you have a firewall set up in a way that blocks packets on port
|
|
323/udp. You need to amend the firewall configuration in this case.
|
|
|
|
@subsection Is the chronyc<->chronyd protocol documented anywhere?
|
|
Only by the source code :-) See cmdmon.c (@code{chronyd} side) and client.c
|
|
(@code{chronyc} side).
|
|
@c }}}
|
|
@c {{{ S:Real-time clock issues
|
|
@node Real-time clock issues
|
|
@section Real-time clock issues
|
|
|
|
@subsection What is the real-time clock (RTC)?
|
|
This is the clock which keeps the time even when your computer is turned off.
|
|
It works with 1 second resolution. @code{chronyd} can monitor the rate at
|
|
which the real-time clock gains or loses time, and compensate for it when you
|
|
set the system time from it at the next reboot. See the documentation for
|
|
details.
|
|
|
|
@subsection I want to use chronyd's real-time clock support. Must I disable hwclock?
|
|
The hwclock program is often set-up by default in the boot and shutdown scripts
|
|
with many Linux installations. If you want to use chronyd's real-time clock
|
|
support, the important thing is to disable hwclock in the shutdown procedure.
|
|
If you don't, it will over-write the RTC with a new value, unknown to
|
|
@code{chronyd}. At the next reboot, @code{chronyd} will compensate this (wrong)
|
|
time with its estimate of how far the RTC has drifted whilst the power was off,
|
|
giving a meaningless initial system time.
|
|
|
|
There is no need to remove hwclock from the boot process, as long as
|
|
@code{chronyd} is started after it has run.
|
|
|
|
@subsection I just keep getting the '513 RTC driver not running' message
|
|
For the real time clock support to work, you need the following three things
|
|
@itemize @bullet
|
|
@item a kernel that is supported (e.g. 2.2 onwards)
|
|
@item enhanced RTC support compiled into the kernel
|
|
@item an @code{rtcfile} directive in your chrony.conf file
|
|
@end itemize
|
|
@c }}}
|
|
@c {{{ S:Microsoft Windows
|
|
@node Microsoft Windows
|
|
@section Microsoft Windows
|
|
|
|
@subsection Does chrony support Windows?
|
|
No. The @code{chronyc} program (the command-line client used for configuring
|
|
@code{chronyd} while it is running) has been successfully built and run under
|
|
Cygwin in the past. @code{chronyd} is not portable, because part of it is very
|
|
system-dependent. It needs adapting to work with Windows' equivalent of the
|
|
adjtimex() call, and it needs to be made to work as an NT service.
|
|
|
|
@subsection Are there any plans to support Windows?
|
|
We have no plans to do this. Anyone is welcome to pick this work up and
|
|
contribute it back to the project.
|
|
@c }}}
|
|
@c {{{ S:NTP-specific issues
|
|
@node NTP-specific issues
|
|
@section NTP-specific issues
|
|
|
|
@subsection Can chrony be driven from broadcast NTP servers?
|
|
No, this NTP mode is not implemented yet.
|
|
|
|
@subsection Can chronyd transmit broadcast NTP packets (e.g. to synchronise other computers on a private LAN)?
|
|
Yes. Starting from version 1.17, chrony has this capability.
|
|
|
|
@subsection Can chrony keep the system clock a fixed offset away from real time?
|
|
This is not possible as the program currently stands.
|
|
|
|
@subsection What happens if the network connection is dropped without using chronyc's 'offline' command first?
|
|
In this case @code{chronyd} will keep trying to access the server(s) that it
|
|
thinks are online. Eventually it will decide that they are unreachable and no
|
|
longer consider itself synchronised to them. If you have other computers on
|
|
your LAN accessing the computer that is affected this way, they too will become
|
|
'unsynchronised', unless you have the 'local' directive set up on the master
|
|
computer.
|
|
|
|
The 'auto_offline' option to the 'server' entry in the chrony.conf file may be
|
|
useful to avoid this situation.
|
|
@c }}}
|
|
@c {{{ S:Linux-specific issues
|
|
@node Linux-specific issues
|
|
@section Linux-specific issues
|
|
|
|
@subsection I get "Could not open /dev/rtc, Device or resource busy" in my syslog file
|
|
Some other program running on the system may be using the device.
|
|
@c }}}
|
|
@c {{{ S:Solaris-specific issues
|
|
@node Solaris-specific issues
|
|
@section Solaris-specific issues
|
|
|
|
@subsection On Solaris 2.8, I get an error message about not being able to open kvm to change dosynctodr
|
|
(The dosynctodr variable controls whether Solaris couples the equivalent of its
|
|
BIOS clock into its system clock at regular intervals). The Solaris port of
|
|
chrony was developed in the Solaris 2.5 era. Some aspect of the Solaris kernel
|
|
has changed which prevents the same technique working. We no longer have root
|
|
access to any Solaris machines to work on this, and we are reliant on somebody
|
|
developing the patch and testing it.
|
|
@c }}}
|
|
@c }}}
|
|
@c {{{ apx:GNU General Public License
|
|
@node GPL
|
|
@appendix GNU General Public License
|
|
|
|
@center GNU GENERAL PUBLIC LICENSE
|
|
@center Version 2, June 1991
|
|
|
|
Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
|
|
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
of this license document, but changing it is not allowed.
|
|
|
|
Preamble
|
|
|
|
The licenses for most software are designed to take away your
|
|
freedom to share and change it. By contrast, the GNU General Public
|
|
License is intended to guarantee your freedom to share and change free
|
|
software--to make sure the software is free for all its users. This
|
|
General Public License applies to most of the Free Software
|
|
Foundation's software and to any other program whose authors commit to
|
|
using it. (Some other Free Software Foundation software is covered by
|
|
the GNU Lesser General Public License instead.) You can apply it to
|
|
your programs, too.
|
|
|
|
When we speak of free software, we are referring to freedom, not
|
|
price. Our General Public Licenses are designed to make sure that you
|
|
have the freedom to distribute copies of free software (and charge for
|
|
this service if you wish), that you receive source code or can get it
|
|
if you want it, that you can change the software or use pieces of it
|
|
in new free programs; and that you know you can do these things.
|
|
|
|
To protect your rights, we need to make restrictions that forbid
|
|
anyone to deny you these rights or to ask you to surrender the rights.
|
|
These restrictions translate to certain responsibilities for you if you
|
|
distribute copies of the software, or if you modify it.
|
|
|
|
For example, if you distribute copies of such a program, whether
|
|
gratis or for a fee, you must give the recipients all the rights that
|
|
you have. You must make sure that they, too, receive or can get the
|
|
source code. And you must show them these terms so they know their
|
|
rights.
|
|
|
|
We protect your rights with two steps: (1) copyright the software, and
|
|
(2) offer you this license which gives you legal permission to copy,
|
|
distribute and/or modify the software.
|
|
|
|
Also, for each author's protection and ours, we want to make certain
|
|
that everyone understands that there is no warranty for this free
|
|
software. If the software is modified by someone else and passed on, we
|
|
want its recipients to know that what they have is not the original, so
|
|
that any problems introduced by others will not reflect on the original
|
|
authors' reputations.
|
|
|
|
Finally, any free program is threatened constantly by software
|
|
patents. We wish to avoid the danger that redistributors of a free
|
|
program will individually obtain patent licenses, in effect making the
|
|
program proprietary. To prevent this, we have made it clear that any
|
|
patent must be licensed for everyone's free use or not licensed at all.
|
|
|
|
The precise terms and conditions for copying, distribution and
|
|
modification follow.
|
|
|
|
GNU GENERAL PUBLIC LICENSE
|
|
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
|
|
|
|
0. This License applies to any program or other work which contains
|
|
a notice placed by the copyright holder saying it may be distributed
|
|
under the terms of this General Public License. The "Program", below,
|
|
refers to any such program or work, and a "work based on the Program"
|
|
means either the Program or any derivative work under copyright law:
|
|
that is to say, a work containing the Program or a portion of it,
|
|
either verbatim or with modifications and/or translated into another
|
|
language. (Hereinafter, translation is included without limitation in
|
|
the term "modification".) Each licensee is addressed as "you".
|
|
|
|
Activities other than copying, distribution and modification are not
|
|
covered by this License; they are outside its scope. The act of
|
|
running the Program is not restricted, and the output from the Program
|
|
is covered only if its contents constitute a work based on the
|
|
Program (independent of having been made by running the Program).
|
|
Whether that is true depends on what the Program does.
|
|
|
|
1. You may copy and distribute verbatim copies of the Program's
|
|
source code as you receive it, in any medium, provided that you
|
|
conspicuously and appropriately publish on each copy an appropriate
|
|
copyright notice and disclaimer of warranty; keep intact all the
|
|
notices that refer to this License and to the absence of any warranty;
|
|
and give any other recipients of the Program a copy of this License
|
|
along with the Program.
|
|
|
|
You may charge a fee for the physical act of transferring a copy, and
|
|
you may at your option offer warranty protection in exchange for a fee.
|
|
|
|
2. You may modify your copy or copies of the Program or any portion
|
|
of it, thus forming a work based on the Program, and copy and
|
|
distribute such modifications or work under the terms of Section 1
|
|
above, provided that you also meet all of these conditions:
|
|
|
|
a) You must cause the modified files to carry prominent notices
|
|
stating that you changed the files and the date of any change.
|
|
|
|
b) You must cause any work that you distribute or publish, that in
|
|
whole or in part contains or is derived from the Program or any
|
|
part thereof, to be licensed as a whole at no charge to all third
|
|
parties under the terms of this License.
|
|
|
|
c) If the modified program normally reads commands interactively
|
|
when run, you must cause it, when started running for such
|
|
interactive use in the most ordinary way, to print or display an
|
|
announcement including an appropriate copyright notice and a
|
|
notice that there is no warranty (or else, saying that you provide
|
|
a warranty) and that users may redistribute the program under
|
|
these conditions, and telling the user how to view a copy of this
|
|
License. (Exception: if the Program itself is interactive but
|
|
does not normally print such an announcement, your work based on
|
|
the Program is not required to print an announcement.)
|
|
|
|
These requirements apply to the modified work as a whole. If
|
|
identifiable sections of that work are not derived from the Program,
|
|
and can be reasonably considered independent and separate works in
|
|
themselves, then this License, and its terms, do not apply to those
|
|
sections when you distribute them as separate works. But when you
|
|
distribute the same sections as part of a whole which is a work based
|
|
on the Program, the distribution of the whole must be on the terms of
|
|
this License, whose permissions for other licensees extend to the
|
|
entire whole, and thus to each and every part regardless of who wrote it.
|
|
|
|
Thus, it is not the intent of this section to claim rights or contest
|
|
your rights to work written entirely by you; rather, the intent is to
|
|
exercise the right to control the distribution of derivative or
|
|
collective works based on the Program.
|
|
|
|
In addition, mere aggregation of another work not based on the Program
|
|
with the Program (or with a work based on the Program) on a volume of
|
|
a storage or distribution medium does not bring the other work under
|
|
the scope of this License.
|
|
|
|
3. You may copy and distribute the Program (or a work based on it,
|
|
under Section 2) in object code or executable form under the terms of
|
|
Sections 1 and 2 above provided that you also do one of the following:
|
|
|
|
a) Accompany it with the complete corresponding machine-readable
|
|
source code, which must be distributed under the terms of Sections
|
|
1 and 2 above on a medium customarily used for software interchange; or,
|
|
|
|
b) Accompany it with a written offer, valid for at least three
|
|
years, to give any third party, for a charge no more than your
|
|
cost of physically performing source distribution, a complete
|
|
machine-readable copy of the corresponding source code, to be
|
|
distributed under the terms of Sections 1 and 2 above on a medium
|
|
customarily used for software interchange; or,
|
|
|
|
c) Accompany it with the information you received as to the offer
|
|
to distribute corresponding source code. (This alternative is
|
|
allowed only for noncommercial distribution and only if you
|
|
received the program in object code or executable form with such
|
|
an offer, in accord with Subsection b above.)
|
|
|
|
The source code for a work means the preferred form of the work for
|
|
making modifications to it. For an executable work, complete source
|
|
code means all the source code for all modules it contains, plus any
|
|
associated interface definition files, plus the scripts used to
|
|
control compilation and installation of the executable. However, as a
|
|
special exception, the source code distributed need not include
|
|
anything that is normally distributed (in either source or binary
|
|
form) with the major components (compiler, kernel, and so on) of the
|
|
operating system on which the executable runs, unless that component
|
|
itself accompanies the executable.
|
|
|
|
If distribution of executable or object code is made by offering
|
|
access to copy from a designated place, then offering equivalent
|
|
access to copy the source code from the same place counts as
|
|
distribution of the source code, even though third parties are not
|
|
compelled to copy the source along with the object code.
|
|
|
|
4. You may not copy, modify, sublicense, or distribute the Program
|
|
except as expressly provided under this License. Any attempt
|
|
otherwise to copy, modify, sublicense or distribute the Program is
|
|
void, and will automatically terminate your rights under this License.
|
|
However, parties who have received copies, or rights, from you under
|
|
this License will not have their licenses terminated so long as such
|
|
parties remain in full compliance.
|
|
|
|
5. You are not required to accept this License, since you have not
|
|
signed it. However, nothing else grants you permission to modify or
|
|
distribute the Program or its derivative works. These actions are
|
|
prohibited by law if you do not accept this License. Therefore, by
|
|
modifying or distributing the Program (or any work based on the
|
|
Program), you indicate your acceptance of this License to do so, and
|
|
all its terms and conditions for copying, distributing or modifying
|
|
the Program or works based on it.
|
|
|
|
6. Each time you redistribute the Program (or any work based on the
|
|
Program), the recipient automatically receives a license from the
|
|
original licensor to copy, distribute or modify the Program subject to
|
|
these terms and conditions. You may not impose any further
|
|
restrictions on the recipients' exercise of the rights granted herein.
|
|
You are not responsible for enforcing compliance by third parties to
|
|
this License.
|
|
|
|
7. If, as a consequence of a court judgment or allegation of patent
|
|
infringement or for any other reason (not limited to patent issues),
|
|
conditions are imposed on you (whether by court order, agreement or
|
|
otherwise) that contradict the conditions of this License, they do not
|
|
excuse you from the conditions of this License. If you cannot
|
|
distribute so as to satisfy simultaneously your obligations under this
|
|
License and any other pertinent obligations, then as a consequence you
|
|
may not distribute the Program at all. For example, if a patent
|
|
license would not permit royalty-free redistribution of the Program by
|
|
all those who receive copies directly or indirectly through you, then
|
|
the only way you could satisfy both it and this License would be to
|
|
refrain entirely from distribution of the Program.
|
|
|
|
If any portion of this section is held invalid or unenforceable under
|
|
any particular circumstance, the balance of the section is intended to
|
|
apply and the section as a whole is intended to apply in other
|
|
circumstances.
|
|
|
|
It is not the purpose of this section to induce you to infringe any
|
|
patents or other property right claims or to contest validity of any
|
|
such claims; this section has the sole purpose of protecting the
|
|
integrity of the free software distribution system, which is
|
|
implemented by public license practices. Many people have made
|
|
generous contributions to the wide range of software distributed
|
|
through that system in reliance on consistent application of that
|
|
system; it is up to the author/donor to decide if he or she is willing
|
|
to distribute software through any other system and a licensee cannot
|
|
impose that choice.
|
|
|
|
This section is intended to make thoroughly clear what is believed to
|
|
be a consequence of the rest of this License.
|
|
|
|
8. If the distribution and/or use of the Program is restricted in
|
|
certain countries either by patents or by copyrighted interfaces, the
|
|
original copyright holder who places the Program under this License
|
|
may add an explicit geographical distribution limitation excluding
|
|
those countries, so that distribution is permitted only in or among
|
|
countries not thus excluded. In such case, this License incorporates
|
|
the limitation as if written in the body of this License.
|
|
|
|
9. The Free Software Foundation may publish revised and/or new versions
|
|
of the General Public License from time to time. Such new versions will
|
|
be similar in spirit to the present version, but may differ in detail to
|
|
address new problems or concerns.
|
|
|
|
Each version is given a distinguishing version number. If the Program
|
|
specifies a version number of this License which applies to it and "any
|
|
later version", you have the option of following the terms and conditions
|
|
either of that version or of any later version published by the Free
|
|
Software Foundation. If the Program does not specify a version number of
|
|
this License, you may choose any version ever published by the Free Software
|
|
Foundation.
|
|
|
|
10. If you wish to incorporate parts of the Program into other free
|
|
programs whose distribution conditions are different, write to the author
|
|
to ask for permission. For software which is copyrighted by the Free
|
|
Software Foundation, write to the Free Software Foundation; we sometimes
|
|
make exceptions for this. Our decision will be guided by the two goals
|
|
of preserving the free status of all derivatives of our free software and
|
|
of promoting the sharing and reuse of software generally.
|
|
|
|
NO WARRANTY
|
|
|
|
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
|
|
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
|
|
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
|
|
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
|
|
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
|
|
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
|
|
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
|
|
REPAIR OR CORRECTION.
|
|
|
|
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
|
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
|
|
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
|
|
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
|
|
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
|
|
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
|
|
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
|
|
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
|
|
POSSIBILITY OF SUCH DAMAGES.
|
|
|
|
END OF TERMS AND CONDITIONS
|
|
|
|
How to Apply These Terms to Your New Programs
|
|
|
|
If you develop a new program, and you want it to be of the greatest
|
|
possible use to the public, the best way to achieve this is to make it
|
|
free software which everyone can redistribute and change under these terms.
|
|
|
|
To do so, attach the following notices to the program. It is safest
|
|
to attach them to the start of each source file to most effectively
|
|
convey the exclusion of warranty; and each file should have at least
|
|
the "copyright" line and a pointer to where the full notice is found.
|
|
|
|
<one line to give the program's name and a brief idea of what it does.>
|
|
Copyright (C) <year> <name of author>
|
|
|
|
This program is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 2 of the License, or
|
|
(at your option) any later version.
|
|
|
|
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.
|
|
|
|
Also add information on how to contact you by electronic and paper mail.
|
|
|
|
If the program is interactive, make it output a short notice like this
|
|
when it starts in an interactive mode:
|
|
|
|
Gnomovision version 69, Copyright (C) year name of author
|
|
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
|
|
This is free software, and you are welcome to redistribute it
|
|
under certain conditions; type `show c' for details.
|
|
|
|
The hypothetical commands `show w' and `show c' should show the appropriate
|
|
parts of the General Public License. Of course, the commands you use may
|
|
be called something other than `show w' and `show c'; they could even be
|
|
mouse-clicks or menu items--whatever suits your program.
|
|
|
|
You should also get your employer (if you work as a programmer) or your
|
|
school, if any, to sign a "copyright disclaimer" for the program, if
|
|
necessary. Here is a sample; alter the names:
|
|
|
|
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
|
|
`Gnomovision' (which makes passes at compilers) written by James Hacker.
|
|
|
|
<signature of Ty Coon>, 1 April 1989
|
|
Ty Coon, President of Vice
|
|
|
|
This General Public License does not permit incorporating your program into
|
|
proprietary programs. If your program is a subroutine library, you may
|
|
consider it more useful to permit linking proprietary applications with the
|
|
library. If this is what you want to do, use the GNU Lesser General
|
|
Public License instead of this License.
|
|
@c }}}
|
|
@contents
|
|
@bye
|
|
@c vim:cms=@c\ %s:fdm=marker:fdc=5:syntax=off
|
|
|