+++ /dev/null
-\input texinfo
-@c {{{ Main header stuff
-@afourwide
-@paragraphindent 0
-@setfilename chrony.info
-@settitle User guide for the chrony suite version @CHRONY_VERSION@
-@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-2015 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
-* 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
-@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, Mac OS X and Solaris.
-Closely related systems may work too. Porting the software to other systems
-(particularly to those supporting an @code{adjtime} or @code{ntp_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 how
-they 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 in that case it has to use a different means of
-adjusting the clock (daemon loop instead of kernel discipline), which may
-have a negative effect on accuracy of the clock.
-@item
-@code{chronyd} can adjust the rate of the clock in a larger range, which
-allows it to operate even on machines with broken or unstable clock
-(e.g. in some virtual machines).
-@item
-@code{chronyd} is smaller, it uses less memory and it wakes up the CPU only
-when necessary, which is better for power saving.
-@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 server/client. However, the broadcast and multicast
-modes are inherently less accurate and less secure (even with authentication)
-than the ordinary server/client mode and should generally be avoided.
-
-@item
-@code{ntpd} supports the Autokey protocol (RFC 5906) to authenticate servers
-with public-key cryptography. Note that the protocol has been shown to be
-insecure and it will be probably replaced with an implementation of the Network
-Time Security (NTS) specification.
-
-@item
-@code{ntpd} supports the orphan mode, which allows synchronisation to a common
-timescale in isolated networks with multiple servers. With @code{chronyd}
-there can be only one master and all other computers have to be directly or
-indirectly synchronised to it.
-
-@item
-@code{ntpd} has been ported to more operating systems.
-
-@item
-@code{ntpd} includes a large number of reference clock drivers. @code{chronyd}
-relies on other programs (e.g. @code{gpsd}) to access the timing data via the
-@code{SHM} or @code{SOCK} driver.
-@end itemize
-
-A comparison of NTP implementations that includes more features and also
-their performance is on the @uref{http://chrony.tuxfamily.org/comparison.html,
-chrony comparison} page.
-
-@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 }}}
-@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.
-
-On Linux, if development files for the libcap library are available,
-@code{chronyd} will be built with support for dropping root privileges.
-On other systems no extra library is needed. The default user which
-@code{chronyd} should run as can be specified with the @code{--with-user}
-option of the configure script.
-
-If development files for the editline or readline library are available,
-@code{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 and manpages.
-
-To install the plain text, HTML and info versions of the manual, 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 1.0 3
-rtcsync
-@end example
-
-Then, @code{chronyd} can be run. For security reasons, it's recommended to
-create an unprivileged user for @code{chronyd} and specify it with the
-@code{-u} command-line option or the @code{user} directive in the configuration
-file, or set the default user with the @code{--with-user} configure option
-before building.
-@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 1.0 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. The configuration file
-could in this case look like
-
-@example
-pool pool.ntp.org iburst
-driftfile @CHRONYVARDIR@/drift
-makestep 1.0 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 from @code{chronyc} that the link to the internet is present.
-
-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
-driftfile @CHRONYVARDIR@/drift
-makestep 1.0 3
-rtcsync
-@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 tell @code{chronyd} when to start and finish sampling the servers, the
-@code{online} and @code{offline} commands of @code{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 @code{chronyc} has been
-installed at its default location @file{@BINDIR@/chronyc}.
-
-In the file @file{/etc/ppp/ip-up} we add the command sequence
-
-@example
-@BINDIR@/chronyc online
-@end example
-
-and in the file @file{/etc/ppp/ip-down} we add the sequence
-
-@example
-@BINDIR@/chronyc 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.
-
-The @code{smoothtime} directive (@pxref{smoothtime directive}) is useful when
-the clocks of the clients need to stay close together when the local time is
-adjusted by the @code{settime} command. The smoothing process needs to be
-activated by the @code{smoothtime activate} command when the local time is
-ready to be served. After that point, any adjustments will be smoothed out.
-
-A typical configuration file for the master (called @code{master}) might be
-(assuming the clients are in the 192.168.165.x subnet)
-
-@example
-driftfile @CHRONYVARDIR@/drift
-local stratum 8
-manual
-allow 192.168.165
-smoothtime 400 0.01
-@end example
-
-For the clients the configuration file might be
-
-@example
-server master iburst
-driftfile @CHRONYVARDIR@/drift
-logdir /var/log/chrony
-log measurements statistics tracking
-@end example
-@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
-makestep 1.0 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 online
-@end example
-
-and the relevant part of the @file{/etc/ppp/ip-down} script is
-
-@example
-@BINDIR@/chronyc -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 should be used only on systems where the kernel
-can maintain clock compensation whilst not under @code{chronyd's}
-control (i.e. Linux, FreeBSD, NetBSD and Solaris).
-@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 or
-to the last modification time of the file specified by the @code{driftfile}
-directive. Real-time clocks are supported only on Linux.
-
-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 the last modification time of the drift file is later than the current time
-and the RTC time, the system time will be set to it to restore the time when
-@code{chronyd} was previously stopped. This is useful on computers that have
-no RTC or the RTC is broken (e.g. it has no battery).
-@item -u <user>
-This option sets the name of the system user to which @code{chronyd} will
-switch after start in order to drop root privileges. It overrides the
-@code{user} directive (default @code{@DEFAULT_USER@}).
-
-On Linux, @code{chronyd} needs to be compiled with support for the
-@code{libcap} library. On Mac OS X, FreeBSD, NetBSD and Solaris @code{chronyd}
-forks into two processes. The child process retains root privileges, but can
-only perform a very limited range of privileged system calls on behalf of the
-parent.
-@item -F <level>
-This option configures a system call filter when @code{chronyd} is compiled with
-support for the Linux secure computing (seccomp) facility. In level 1 the
-process is killed when a forbidden system call is made, in level -1 the SYSSIG
-signal is thrown instead and in level 0 the filter is disabled (default 0).
-
-It's recommended to enable the filter only when it's known to work on the
-version of the system where @code{chrony} is installed as the filter needs to
-allow also system calls made from libraries that @code{chronyd} is using (e.g.
-libc) and different versions or implementations of the libraries may make
-different system calls. If the filter is missing some system call,
-@code{chronyd} could be killed even in normal operation.
-@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>
-On Linux, this option will select the SCHED_FIFO real-time scheduler at the
-specified priority (which must be between 0 and 100). On Mac OS X, this option
-must have either a value of 0 (the default) to disable the thread time
-constraint policy or 1 for the policy to be enabled. Other systems do not
-support this option.
-@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 monitoring access to chronyc on other computers
-* cmddeny directive:: Deny monitoring access to chronyc on other computers
-* cmdport directive:: Set port to use for runtime monitoring
-* cmdratelimit directive:: Limit command response rate
-* combinelimit directive:: Limit sources included in combining algorithm
-* 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
-* 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
-* maxdistance directive:: Set maximum allowed distance of sources
-* 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
-* ratelimit directive:: Limit NTP response rate
-* 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 monitoring command packets
-(issued by @code{chronyc}). This provides an additional level of access
-restriction above that available through @code{cmddeny} mechanism.
-
-This directive can also change the path of the Unix domain command socket,
-which is used by @code{chronyc} to send configuration commands. The socket
-must be in a directory that is accessible only by the root or chrony user. The
-directory will be created on start if it doesn't exist. The default path of
-the socket is @code{@CHRONYSOCKDIR@/chronyd.sock}.
-
-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.
-
-An example that sets the path of the Unix domain command socket is
-@example
-bindcmdaddress /var/run/chrony/chronyd.sock
-@end example
-@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 amount of memory that @code{chronyd} is
-allowed to allocate for logging of client accesses. The default limit is
-524288 bytes, which allows monitoring of several thousands of addresses at the
-same time.
-
-In older @code{chrony} versions if the limit was set to 0, the memory
-allocation was unlimited.
-
-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 monitoring access (rather than NTP client access) to a particular
-subnet or host. (By 'monitoring access' is meant that @code{chronyc} can be
-run on those hosts and retrieve monitoring data from @code{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 monitoring 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 monitoring 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
-monitoring (via the @code{chronyc} program) 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 from the internet.
-(It does not disable the Unix domain command socket.)
-
-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 {{{ cmdratelimit
-@node cmdratelimit directive
-@subsection cmdratelimit
-This directive enables response rate limiting for command packets. It's
-similar to the @code{ratelimit} directive (@pxref{ratelimit directive}), except
-responses to the localhost are never limited and the default interval is 1 (2
-seconds), default burst is 16, and default leak rate is 2.
-
-An example of use of the command is
-
-@example
-cmdratelimit interval 2
-@end example
-@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 {{{ corrtimeratio
-@node corrtimeratio directive
-@subsection corrtimeratio
-When @code{chronyd} is slewing the system clock to correct an offset, the rate
-at which it is slewing adds to the frequency error of the clock. On Linux,
-FreeBSD, NetBSD and Solaris this rate can be controlled.
-
-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 (Linux, FreeBSD, NetBSD, Solaris) have operating system
-support for setting the rate of gain or loss to compensate for known errors.
-(On Mac OS X, @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 {{{ 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 on Linux. @code{chronyd} parses the
-file to find out if the RTC keeps local time or UTC. It overrides the
-@code{rtconutc} directive (@pxref{rtconutc directive}).
-
-The default value is @file{@DEFAULT_HWCLOCK_FILE@}.
-
-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 or
-multiple configuration files when a wildcard pattern is specified. This can be
-useful when maintaining configuration on multiple hosts to keep the differences
-in separate files.
-
-An example of the command is
-
-@example
-include @SYSCONFDIR@/chrony.d/*.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 authentication of NTP packets.
-
-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, name of an authentication hash function (optional)
-and a password. The ID can be any unsigned integer in the range 1 through
-2**32-1. The default hash function is MD5. Depending on how @code{chronyd}
-was compiled, other supported functions may be SHA1, SHA256, SHA384, SHA512,
-RMD128, RMD160, RMD256, RMD320, TIGER and WHIRLPOOL. The password can be
-specified as a string of characters not containing white space with an optional
-@code{ASCII:} prefix, or as a hexadecimal number with the @code{HEX:} prefix.
-The maximum length of the line is 2047 characters.
-
-The password is used with the hash function to generate and verify a message
-authentication code (MAC) in NTP packets. It's recommended to use SHA1 or a
-stronger hash function with random passwords specified in the hexadecimal
-format that have at least 128 bits. @code{chronyd} will log a warning to
-syslog on start if a source is specified in the configuration file with a key
-that has password shorter than 80 bits.
-
-The @code{keygen} command of @code{chronyc} (@pxref{keygen command}) can be
-used to generate random keys for the key file. By default, it generates
-160-bit MD5 or SHA1 keys.
-@c }}}
-@c {{{ leapsecmode
-@node leapsecmode directive
-@subsection leapsecmode
-A leap second is an adjustment that is occasionally applied to UTC to keep it
-close to the mean solar time. When a leap second is inserted, the last day of
-June or December has an extra second 23:59:60.
-
-For computer clocks that is a problem. The Unix time is defined as number of
-seconds since 00:00:00 UTC on 1 January 1970 without leap seconds. The system
-clock cannot have time 23:59:60, every minute has 60 seconds and every day has
-86400 seconds by definition. The inserted leap second is skipped and the clock
-is suddenly ahead of UTC by one second. The @code{leapsecmode} directive
-selects how that error is corrected. There are four options:
-
-@table @code
-@item system
-When inserting a leap second, the kernel steps the system clock backwards by
-one second when the clock gets to 00:00:00 UTC. When deleting a leap second,
-it steps forward by one second when the clock gets to 23:59:59 UTC. This is
-the default mode when the system driver supports leap seconds (i.e. on
-Linux, FreeBSD, NetBSD and Solaris).
-@item step
-This is similar to the @code{system} mode, except the clock is stepped by
-@code{chronyd} instead of the kernel. It can be useful to avoid bugs in the
-kernel code that would be executed in the @code{system} mode. This is the
-default mode when the system driver doesn't support leap seconds.
-@item slew
-The clock is corrected by slewing started at 00:00:00 UTC when a leap second is
-inserted or 23:59:59 UTC when a leap second is deleted. This may be preferred
-over the @code{system} and @code{step} modes 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} value (@pxref{maxslewrate directive}) the correction takes
-12 seconds.
-@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
-
-When serving time to NTP clients that can't be configured to correct their
-clocks for a leap second by slewing or they would correct them at slightly
-different rates when it's necessary to keep them close together, the
-@code{slew} mode can be combined with the @code{smoothtime} directive
-(@pxref{smoothtime directive}) to enable a server leap smear.
-
-When smearing a leap second, the leap status is suppressed on the server and
-the served time is corrected slowly be slewing instead of stepping. The clients
-don't need any special configuration as they don't know there is any leap
-second and they follow the server time which eventually brings them back to
-UTC. Care must be taken to ensure they use for synchronization only NTP
-servers which smear the leap second in exactly the same way.
-
-This feature needs to be used carefully, because the server is intentionally
-not serving its best estimate of the true time.
-
-A recommended configuration to enable a server leap smear is:
-
-@example
-leapsecmode slew
-maxslewrate 1000
-smoothtime 400 0.001 leaponly
-@end example
-
-The first directive is necessary to disable the clock step which would reset
-the smoothing process. The second directive limits the slewing rate of the
-local clock to 1000 ppm, which improves the stability of the smoothing process
-when the local correction starts and ends. The third directive enables the
-server time smoothing process. It will start when the clock gets to 00:00:00
-UTC and it will take 17 hours 34 minutes to finish. The frequency offset will
-be changing by 0.001 ppm per second and will reach maximum of 31.623 ppm. The
-@code{leaponly} option makes the duration of the leap smear constant and allows
-the clients to safely synchronise with multiple identically configured leap
-smearing servers.
-@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 sets the threshold for the adjustment of the system clock
-that will generate a syslog message.
-
-By default, the threshold is 1 second.
-
-An example of use is
-
-@example
-logchange 0.1
-@end example
-
-which would cause a syslog message to be generated a system clock error
-of over 0.1 seconds starts to be compensated.
-
-Clock errors detected via NTP packets, reference clocks, or timestamps entered
-via the @code{settime} command of @code{chronyc} are logged.
-@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.
-
-This directive can't be used when a system call filter is enabled by the
-@code{-F} option as the @code{chronyd} process will not be allowed to fork
-and execute the sendmail binary.
-@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 0.1 10
-@end example
-
-This would step system clock if the adjustment is larger than 0.1
-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 {{{ maxdistance
-@node maxdistance directive
-@subsection maxdistance
-The @code{maxdistance} directive sets the maximum allowed root distance of the
-sources to not be rejected by the source selection algorithm. The distance
-includes the accumulated dispersion, which may be large when the source is no
-longer synchronised, and half of the total round-trip delay to the primary
-source.
-
-By default, the maximum root distance is 3 seconds.
-
-Setting @code{maxdistance} to a larger value can be useful to allow
-synchronisation with a server that only has a very infrequent connection to its
-sources and can accumulate a large dispersion between updates of its clock.
-
-The syntax is
-
-@example
-maxdistance <seconds>
-@end example
-@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 (i.e.
-Linux, FreeBSD, NetBSD, Solaris).
-
-For each system there is a maximum frequency offset of the clock that
-can be set by the driver. On Linux it's 100000 ppm, on FreeBSD and NetBSD
-it's 5000 ppm and on Solaris it is 32500 ppm. Also, due to a kernel
-limitation, setting @code{maxslewrate} on FreeBSD and NetBSD to a value between
-500 ppm and 5000 ppm will effectively set it to 500 ppm.
-
-By default, the maximum slew rate is set to 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.
-
-When a key is specified by the @code{key} option to enable authentication, both
-peers must be configured to use the same key and the same key number.
-
-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 {{{ ratelimit
-@node ratelimit directive
-@subsection ratelimit
-This directive enables response rate limiting for NTP packets. Its purpose is
-to reduce network traffic with misconfigured or broken NTP clients that are
-polling the server too frequently. The limits are applied to individual IP
-addresses. If multiple clients share one IP address (e.g. multiple hosts
-behind NAT), the sum of their traffic will be limited. If a client that
-increases its polling rate when it doesn't receive a reply is detected, its
-rate limiting will be temporarily suspended to avoid increasing the overall
-amount of traffic. The maximum number of IP addresses which can be monitored
-at the same time depends on the memory limit set by the @code{clientloglimit}
-directive.
-
-The @code{ratelimit} directive supports a number of subfields (which
-may be defined in any order):
-
-@table @code
-@item interval
-This option sets the minimum interval between responses. It is defined as a
-power of 2 in seconds. The default value is 3 (8 seconds). The minimum value
-is -4 and the maximum value is 12.
-@item burst
-This option sets the maximum number of responses that can be send in a burst,
-temporarily exceeding the limit specified by the @code{interval} option. This
-is useful for clients that make rapid measurements on start (e.g.
-@code{chronyd} with the @code{iburst} option). The default value is 8. The
-minimum value is 1 and the maximum value is 255.
-@item leak
-This option sets the rate at which responses are randomly allowed even if the
-limits specified by the @code{interval} and @code{burst} options are exceeded.
-This is necessary to prevent an attacker who is sending requests with a spoofed
-source address from completely blocking responses to that address. The leak
-rate is defined as a power of 1/2 and it is 3 by default, i.e. on average at
-least every eighth request has a response. The minimum value is 1 and the
-maximum value is 4.
-@end table
-
-An example use of the command is
-
-@example
-ratelimit interval 4 burst 4
-@end example
-
-This would reduce the response rate for IP addresses that send packets on
-average more frequently than once per 16 seconds and/or send packets in bursts
-with more than 4 packets.
-@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 trust
-Assume time from this source is always true. It can be rejected as a
-falseticker in the source selection only if another source with this option
-doesn't agree with it.
-@item require
-Require that at least one of the sources specified with this option is
-selectable (i.e. recently reachable and not a falseticker) before updating the
-clock. Together with the @code{trust} option this may be useful to allow a
-trusted, but not very precise, reference clock to be safely combined with
-unauthenticated NTP sources in order to improve the accuracy of the clock.
-They can be selected and used for synchronisation only if they agree with
-the trusted and required source.
-@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 enables a mode where the system time is
-periodically copied to the real time clock (RTC).
-
-On Linux the RTC copy is performed by the kernel every 11 minutes. This
-directive cannot be used when the normal RTC tracking is enabled,
-i.e. when the @code{rtcfile} directive is used.
-
-On Mac OS X, chronyd will perform the RTC copy every 60 minutes when the
-system clock is in a synchronised state.
-
-On other systems this directive does nothing.
-@c }}}
-@c {{{ sched_priority
-@node sched_priority directive
-@subsection sched_priority
-
-On Linux, the @code{sched_priority} directive will select the SCHED_FIFO
-real-time scheduler at the specified priority (which must be between 0 and
-100). On Mac OS X, this option must have either a value of 0 (the default) to
-disable the thread time constraint policy or 1 for the policy to be enabled.
-Other systems do not support this option.
-
-On Linux, this directive uses the 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.
-
-On Mac OS X, this directive uses the thread_policy_set() kernel call to specify
-real-time scheduling. As noted for Linux, you should not use this directive
-unless you really need it.
-@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 trust
-Assume time from this source is always true. It can be rejected as a
-falseticker in the source selection only if another source with this option
-doesn't agree with it.
-
-@item require
-Require that at least one of the sources specified with this option is
-selectable (i.e. recently reachable and not a falseticker) before updating the
-clock. Together with the @code{trust} option this may be useful to allow a
-trusted authenticated source to be safely combined with unauthenticated sources
-in order to improve the accuracy of the clock. They can be selected and used
-for synchronisation only if they agree with the trusted and required source.
-
-@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.
-
-BE WARNED - the server is intentionally not serving its best estimate of the
-true 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 implemented with a quadratic spline function with two
-or three pieces. It's independent from any slewing applied to the local system
-clock, but the accumulated offset and frequency will be reset when the clock is
-corrected by stepping, e.g. by the @code{makestep} directive or command. The
-process can be reset without stepping the clock by the @code{smoothtime reset}
-command (@pxref{smoothtime command}).
-
-The first two arguments of the directive are 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).
-@code{leaponly} is an optional third argument which enables a mode where only
-leap seconds are smoothed out and normal offset/frequency changes are ignored.
-The @code{leaponly} option is useful in a combination with the
-@code{leapsecmode slew} option (@pxref{leapsecmode directive}) to allow clients
-use multiple time smoothing servers safely.
-
-The smoothing process is activated automatically when 1/10000 of the estimated
-skew of the local clock falls below the maximum rate of frequency change. It
-can be also activated manually by the @code{smoothtime activate} command,
-which is particularly useful when the clock is synchronized only with manual
-input and the skew is always larger than the threshold. The @code{smoothing}
-command (@pxref{smoothing command}) can be used to monitor the process.
-
-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 system user to which
-@code{chronyd} will switch after start in order to drop root privileges.
-
-On Linux, @code{chronyd} needs to be compiled with support for the
-@code{libcap} library. On Mac OS X, FreeBSD, NetBSD and Solaris @code{chronyd}
-forks into two processes. The child process retains root privileges, but can
-only perform a very limited range of privileged system calls on behalf of the
-parent.
-
-The default value is @code{@DEFAULT_USER@}. The configure script has a
-@code{--with-user} option, which sets the default value.
-@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 not 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 (or comma-separated list of
-addresses) running the @code{chronyd} program is to be contacted. This allows
-for remote monitoring, 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 -d
-This option enables printing of debugging messages (if compiled with debugging
-support).
-@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 is ignored and is provided only for compatibility.
-@item -a
-This option is ignored and is provided only for compatibility.
-@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 @code{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}.
-
-@code{chronyc} also provides a number of monitoring (as opposed to
-commanding or configuration) commands, which will not affect the behaviour of
-@code{chronyd}. However, you may still want to restrict access to these
-commands.
-
-There are two ways how @code{chronyc} can access @code{chronyd}. One is the
-Internet Protocol (IPv4 or IPv6) and the other is a Unix domain socket, which
-is accessible only locally by the root or chrony user (by default
-@code{@CHRONYSOCKDIR@/chronyd.sock}).
-
-Only the following monitoring commands are allowed from the internet:
-
-@itemize @bullet
-@item @code{activity}
-@item @code{manual list}
-@item @code{rtcdata}
-@item @code{smoothing}
-@item @code{sources}
-@item @code{sourcestats}
-@item @code{tracking}
-@item @code{waitsync}.
-@end itemize
-
-The set of hosts from which @code{chronyd} will accept these commands can be
-restricted. By default, the commands will be accepted only from the localhost
-(127.0.0.1 or ::1).
-
-All other commands are allowed only through the Unix domain socket. When sent
-over the internet, @code{chronyd} will respond with a @code{Not authorised}
-error, even if it's from the localhost.
-
-In @code{chrony} versions before 2.2 the commands had to be authenticated with
-a password and they were allowed from the internet, but that is no longer
-supported.
-
-By default, @code{chronyc} tries to connect to the Unix domain socket first.
-If that fails (e.g. because @code{chronyc} is running under a non-root user),
-it will try to connect to 127.0.0.1 and then ::1.
-@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
-* burst command:: Initiating a rapid set of measurements
-* clients command:: Show clients that have accessed the server
-* cmdaccheck command:: Verifying monitoring client access
-* cmdallow all command:: Allowing monitoring client access
-* cmdallow command:: Allowing monitoring client access
-* cmddeny all command:: Denying monitoring client access
-* cmddeny command:: Denying monitoring 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
-* keygen command:: Generate key for key file
-* 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
-* polltarget command:: Set poll target for a source
-* quit command:: Exit from chronyc
-* refresh command:: Refresh IP addresses
-* 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
-* serverstats command:: Display statistics of the server
-* settime command:: Provide a manual input of the current time
-* smoothing command:: Display current time smoothing state
-* smoothtime command:: Reset/activate server time smoothing
-* 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 {{{ 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 clients that have accessed the server,
-through either the NTP or command/monitoring ports. It doesn't include
-accesses over the Unix domain comamnd socket. There are no arguments.
-
-An example of the output is
-
-@example
-Hostname NTP Drop Int IntL Last Cmd Drop Int Last
-===============================================================================
-localhost 2 0 2 - 133 15 0 -1 7
-foo.example.net 12 0 6 - 23 0 0 - -
-@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 intervals are displayed as a power of 2 in
-seconds.
-
-The columns are as follows:
-
-@enumerate 1
-@item
-The hostname of the client
-@item
-The number of NTP packets received from the client.
-@item
-The number of NTP packets dropped to limit the response rate.
-@item
-The average interval between NTP packets.
-@item
-The average interval between NTP packets after limiting the response rate.
-@item
-Time since the last NTP packet was received
-@item
-The number of command packets received from the client.
-@item
-The number of command packets dropped to limit the response rate.
-@item
-The average interval between command packets.
-@item
-Time since the last command packet was received.
-@end enumerate
-@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 monitoring 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
-allow particular hosts or subnets to use @code{chronyc} to monitor 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 @code{chronyc} to monitor 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 @code{chronyc} to monitor @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 @code{chronyc} to monitor @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 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 {{{ keygen
-@node keygen command
-@subsubsection keygen
-The @code{keygen} command generates a key that can be added to the
-key file (@pxref{keyfile directive}) to allow NTP authentication between
-server and client, or peers. The key is generated from the @code{/dev/urandom}
-device and it's printed to standard output.
-
-The command has three optional arguments. The first argument is the key number
-(by default 1), which will be specified with the @code{key} option of the
-@code{server} or @code{peer} directives in the configuration file. The second
-argument is the hash function (by default SHA1 or MD5 if SHA1 is not available)
-and the third argument is the number of bits the key should have, between 80
-and 4096 bits (by default 160 bits).
-
-An example is
-
-@example
-keygen 73 SHA1 256
-@end example
-
-which generates a 256-bit SHA-1 key with number 73. The printed line would
-then be securely transferred and added to key files on both server and client,
-or peers.
-@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 can
-be used on computers with intermittent 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
-
-
-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 {{{ 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 {{{ refresh command
-@node refresh command
-@subsubsection refresh
-The @code{refresh} command can be used to force @code{chronyd} to resolve the
-names of configured sources to IP addresses again, e.g. after suspending and
-resuming the machine in a different network.
-
-Sources that stop responding will be replaced with newly resolved addresses
-automatically after 8 polling intervals, but this command may still be useful
-to replace them immediately and not wait until they are marked as unreachable.
-@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 {{{ serverstats command
-@node serverstats command
-@subsubsection serverstats command
-The @code{serverstats} command displays how many valid NTP and command requests
-@code{chronyd} as a server received from clients, how many of them were dropped
-to limit the response rate as configured by the @code{ratelimit} and
-@code{cmdratelimit} directives, and how many client log records were dropped
-due to the memory limit configured by the @code{clientloglimit} directive. An
-example of the output is shown below.
-
-@example
-NTP packets received : 1598
-NTP packets dropped : 8
-Command packets received : 19
-Command packets dropped : 0
-Client log records dropped : 0
-@end example
-@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 {{{ smoothing
-@node smoothing command
-@subsubsection smoothing
-The @code{smoothing} command displays the current state of the NTP server time
-smoothing. An example of the output is shown below.
-
-@example
-Active : Yes
-Offset : +1.000268817 seconds
-Frequency : -0.142859 ppm
-Wander : -0.010000 ppm per second
-Last update : 17.8 seconds ago
-Remaining time : 19988.4 seconds
-@end example
-
-The fields are explained as follows.
-
-@table @code
-@item Active
-This shows if the server time smoothing is currently active. Possible values
-are @code{Yes} and @code{No}. If the @code{leaponly} option is included in the
-@code{smoothtime} directive, @code{(leap second only)} will be shown on the
-line.
-
-@item Offset
-This is the current offset applied to the time sent to NTP clients. Positive
-value means the clients are getting time that's ahead of true time.
-
-@item Frequency
-The current frequency offset of the served time. Negative value means the time
-observed by clients is running slower than true time.
-
-@item Wander
-The current frequency wander of the served time. Negative value means the time
-observed by clients is slowing down.
-
-@item Last update
-This field shows how long ago was the time smoothing process updated, e.g.
-@code{chronyd} accumulated a new measurement.
-
-@item Remaining time
-The time it would take for the smoothing process to get to zero offset and
-frequency if there were no more updates.
-@end table
-@c }}}
-@c {{{ smoothtime
-@node smoothtime command
-@subsubsection smoothtime
-The @code{smoothtime} command can be used to reset or activate the server time
-smoothing process if it is configured with the @code{smoothtime} directive
-(@pxref{smoothtime directive}).
-
-The syntax is as follows
-
-@example
-smoothtime reset
-smoothtime activate
-@end example
-
-@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.
-@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.
-
-@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 four optional arguments can be specified, the first is the maximum
-number of tries 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.
-
-The fourth argument is the interval in which the check is repeated. The
-interval is 10 seconds by default.
-
-An example is
-
-@example
-waitsync 60 0.01
-@end example
-
-which will wait up to about 10 minutes (60 times 10 seconds) 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 {{{ 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
-
--- /dev/null
+// This file is part of chrony
+//
+// Copyright (C) Richard P. Curnow 1997-2003
+// Copyright (C) Miroslav Lichvar 2009-2016
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of version 2 of the GNU General Public License as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful, but
+// WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along
+// with this program; if not, write to the Free Software Foundation, Inc.,
+// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+= chrony.conf(5)
+:doctype: manpage
+:man manual: Configuration Files
+:man source: chrony @CHRONY_VERSION@
+
+== NAME
+chrony.conf - chronyd configuration file
+
+== SYNOPSIS
+*chrony.conf*
+
+== DESCRIPTION
+
+This file configures the *chronyd* daemon. The compiled-in location is
+_@SYSCONFDIR@/chrony.conf_, but other locations can be specified on the
+*chronyd* command line with the *-f* option.
+
+Each directive in the configuration file is placed on a separate line. The
+following sections describe each of the directives in turn. The directives can
+occur in any order in the file and they are not case-sensitive.
+
+The configuration directives can also be specified directly on the *chronyd*
+command line. In this case each argument is parsed as a new line and the
+configuration file is ignored.
+
+While the number of supported directives is large, only a few of them are
+typically needed. See the <<examples,*EXAMPLES*>> section for configuration in
+typical operating scenarios.
+
+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: *!*, *;*, *#*, *%*. Any line with this format will be ignored.
+
+== DIRECTIVES
+
+=== Time sources
+
+[[server]]*server* _hostname_ [_option_]...::
+The *server* directive specifies an NTP server which can be used as a time
+source. 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 *server* directive is immediately followed by either the name of the
+server, or its IP address. The *server* directive supports the following
+options:
++
+*minpoll* _poll_:::
+Although *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 *minpoll 5* would mean that the
+polling interval cannot drop below 32 seconds. The default is 6 (64 seconds).
+*maxpoll* _poll_:::
+In a similar way, the user may wish to constrain the maximum polling interval.
+Again this is specified as a power of 2, *maxpoll 9* indicates that the polling
+interval must stay at or below 512 seconds. The default is 10 (1024 seconds).
+*iburst*:::
+If this option is set, the interval between the first four polls will be 2
+seconds instead of _minpoll_. This is useful to get quickly the first update of
+the clock after *chronyd* is started.
+*key* _id_:::
+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, which is specified by the
+<<keyfile,*keyfile*>> directive.
++
+If the key option is present, *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.
+*maxdelay* _delay_:::
+*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 the round-trip delay, *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*
+option. For example, *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.
+*maxdelayratio* _ratio_:::
+This option is similar to the maxdelay option above. *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.
+*maxdelaydevratio* _ratio_:::
+If a measurement has a ratio of the increase in the round-trip delay from the
+minimum delay amongst the previous measurements to the standard deviation of
+the previous measurements that is greater than the specified ratio, it will be
+rejected. The default is 10.0.
+*minsamples* _samples_:::
+Set the minimum number of samples kept for this source. This overrides the
+<<minsamples,*minsamples*>> directive.
+*maxsamples* _samples_:::
+Set the maximum number of samples kept for this source. This overrides the
+<<maxsamples,*maxsamples*>> directive.
+*offline*:::
+If the server will not be reachable when *chronyd* is started, the *offline*
+option may be specified. *chronyd* will not try to poll the server until it is
+enabled to do so (by using the <<chronyc.adoc#online,*online*>> command in
+*chronyc*).
+*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 <<chronyc.adoc#offline,*offline*>> command from *chronyc*
+when disconnecting the network link. (It will still be necessary to use the
+<<chronyc.adoc#online,*online*>> command when the link has been established, to
+enable measurements to start.)
+*prefer*:::
+Prefer this source over sources without prefer option.
+*noselect*:::
+Never select this source. This is particularly useful for monitoring.
+*trust*:::
+Assume time from this source is always true. It can be rejected as a
+falseticker in the source selection only if another source with this option
+doesn't agree with it.
+*require*:::
+Require that at least one of the sources specified with this option is
+selectable (i.e. recently reachable and not a falseticker) before updating the
+clock. Together with the *trust* option this may be useful to allow a trusted
+authenticated source to be safely combined with unauthenticated sources in
+order to improve the accuracy of the clock. They can be selected and used for
+synchronisation only if they agree with the trusted and required source.
+*polltarget* _target_:::
+Target number of measurements to use for the regression algorithm which
+*chronyd* will try to maintain by adjusting the polling interval between
+*minpoll* and *maxpoll*. A higher target makes *chronyd* prefer shorter polling
+intervals. The default is 6 and a useful range is from 6 to 60.
+*port* _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).
+*presend* _poll_:::
+If the timing measurements being made by *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 *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 *server* directive:
++
+----
+presend 9
+----
++
+when the polling interval is 512 seconds or more, an extra NTP client packet
+will be sent to the server a short time (4 seconds) before making the actual
+measurement.
+*minstratum* _stratum_:::
+When the synchronisation source is selected from available sources, sources
+with lower stratum are normally slightly preferred. This option can be used to
+increase stratum of the source to the specified minimum, so *chronyd* will
+avoid selecting that source. This is useful with low stratum sources that are
+known to be unreliable or inaccurate and which should be used only when other
+sources are unreachable.
+*version* _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.
+
+[[pool]]*pool* _hostname_ [_option_]...::
+The syntax of this directive is similar to that for the <<server,*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 <<server,*server*>> directive can be used in this
+directive too. There is one option specific to the *pool* directive:
+*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, *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 *maxsources*, the other sources will be
+removed. When a pool source is unreachable or marked as a falseticker,
+*chronyd* will try to replace the source with a newly resolved address of the
+pool.
++
+An example of the *pool* directive is
++
+----
+pool pool.ntp.org iburst maxsources 3
+----
+
+[[peer]]*peer* _hostname_ [_option_]...::
+The syntax of this directive is identical to that for the <<server,*server*>>
+directive, except that it is used to specify an NTP peer rather than an NTP
+server.
++
+When a key is specified by the *key* option to enable authentication, both
+peers must be configured to use the same key and the same key number.
++
+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 synchronise to
+each other.
++
+This attack can be prevented by enabling authentication with the *key* option,
+or using the <<server,*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.
+
+[[initstepslew]]*initstepslew* _step-threshold_ [_hostname_]...::
+In normal operation, *chronyd* slews the time when it needs to adjust the
+system clock. For example, to correct a system clock which is 1 second slow,
+*chronyd* slightly increases the amount by which the system clock is advanced
+on each clock interrupt, until the error is removed. 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 *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 *initstepslew* directive is to allow *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 *chronyd* whilst the system is in
+normal operation.
++
+The *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. *chronyd* then enters its normal operating mode.
++
+An example of use of the directive is
++
+----
+initstepslew 30 foo.example.net bar.example.net
+----
++
+where 2 NTP servers are used to make the measurement. The _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 *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,*local*>> directive, the master can be set up with
+an *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 *initstepslew* directive is functionally similar to a combination of the
+<<makestep,*makestep*>> and <<server,*server*>> directives with the *iburst*
+option. The main difference is that the *initstepslew* servers are used only
+before normal operation begins and that the foreground *chronyd* process waits
+for *initstepslew* to finish before exiting. This is useful to prevent programs
+started in the boot sequence after *chronyd* from reading the clock before it's
+stepped.
+
+[[refclock]]*refclock* _driver_ _parameter_ [_option_]...::
+The *refclock* directive specifies a hardware reference clock to be used as a
+time source. It has two mandatory parameters, a driver name and a
+driver-specific parameter.
++
+There are currently four drivers included:
++
+*PPS*:::
+Driver for the kernel PPS (pulse per second) API. The parameter is the path to
+the PPS device (typically _/dev/pps?_). The assert events are used for
+synchronisation by default. String *:clear* can be appended to the path to use
+the clear events instead.
++
+As PPS refclocks don't supply full time, *chronyd* needs to be configured with
+another time source (NTP or non-PPS refclock) in order to complete samples from
+the PPS refclock. An alternative is to enable the <<local,*local*>> directive
+to allow synchronisation with some unknown but constant offset.
+For example:
++
+----
+refclock PPS /dev/pps0 lock NMEA
+refclock SHM 0 offset 0.5 delay 0.2 refid NMEA noselect
+----
++
+*SHM*:::
+NTP shared memory driver. This driver uses a shared memory segment to receive
+samples from another process. The parameter is the number of the shared memory
+segment, typically 0, 1, 2 or 3. For example:
++
+----
+refclock SHM 1 poll 3 refid GPS1
+----
++
+A driver option in form of *:perm=NNN* can be appended to the segment number to
+create the segment with permissions other than the default 0600.
++
+Examples of applications that can be used as SHM refclocks are
+http://www.catb.org/gpsd/[*gpsd*],
+http://www.buzzard.me.uk/jonathan/radioclock.html[*radioclk*], and
+https://www.vanheusden.com/time/omnisync/[*omnisync*].
++
+*SOCK*:::
+Unix domain socket driver. It is similar to the SHM driver, but samples are
+received from a Unix domain socket instead of shared memory and the messages
+have a different format. The parameter is the path to the socket, which
+*chronyd* creates on start. An advantage over the SHM driver is that SOCK does
+not require polling and it can receive PPS samples with incomplete time. The
+format of the messages is described in the _refclock_sock.c_ file in the chrony
+source code.
++
+An application which supports the SOCK protocol is the *gpsd* daemon. The path
+where *gpsd* expects the socket to be created is described in the *gpsd(8)* man
+page. For example:
++
+----
+refclock SOCK /var/run/chrony.ttyS0.sock
+----
++
+*PHC*:::
+PTP hardware clock (PHC) driver. The parameter is the path to the device of
+the PTP clock, which for example can be synchronised by *ptp4l* from
+http://linuxptp.sourceforge.net[*linuxptp*]. PTP clocks are typically kept in
+TAI instead of UTC, so the *offset* option should be used to compensate for the
+current UTC/TAI offset. For example:
++
+----
+refclock PHC /dev/ptp0 poll 3 dpoll -2 offset -36
+----
++
+::
+The *refclock* directive also supports a number of options:
++
+*poll* _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
+*chronyd* to react faster to changes in the frequency of the system clock, but
+it may have a negative effect on its accuracy if the samples have a lot of
+jitter.
+*dpoll* _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).
+*refid* _refid_:::
+This option is used to specify the reference ID of the refclock, as up to four
+ASCII characters. The default refid is composed from the first three characters
+of the driver name and the number of the refclock. Each refclock must have an
+unique refid.
+*lock* _refid_:::
+This option can be used to lock a PPS refclock to another refclock, which is
+specified by its reference ID. In this mode received PPS samples are paired
+directly with raw samples from the specified refclock.
+*rate* _rate_:::
+This option sets the rate of the pulses in the PPS signal (in Hz). This option
+controls how the pulses will be completed with real time. To actually receive
+more than one pulse per second, a negative *dpoll* has to be specified (-3 for
+a 5Hz signal). The default is 1.
+*offset* _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.
+*delay* _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
+source selection or to make it prefer other sources. The default is 1e-9 (1
+nanosecond).
+*precision* _precision_:::
+This option sets the 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.
+*maxdispersion* _dispersion_:::
+Maximum allowed dispersion for filtered samples (in seconds). Samples with
+larger estimated dispersion are ignored. By default, this limit is disabled.
+*filter* _samples_:::
+This option sets the length of the median filter which is used to reduce the
+noise in the measurements. With each poll about 40 percent of the stored
+samples are discarded and one final sample is calculated as an average of the
+remaining samples. If the length is 4 or more, at least 4 samples have to be
+collected between polls. For lengths below 4, the filter has to be full. The
+default is 64.
+*prefer*:::
+Prefer this source over sources without prefer option.
+*noselect*:::
+Never select this source. This is useful for monitoring or with sources which
+are not very accurate, but are locked with a PPS refclock.
+*trust*:::
+Assume time from this source is always true. It can be rejected as a
+falseticker in the source selection only if another source with this option
+doesn't agree with it.
+*require*:::
+Require that at least one of the sources specified with this option is
+selectable (i.e. recently reachable and not a falseticker) before updating the
+clock. Together with the *trust* option this may be useful to allow a trusted,
+but not very precise, reference clock to be safely combined with
+unauthenticated NTP sources in order to improve the accuracy of the clock. They
+can be selected and used for synchronisation only if they agree with the
+trusted and required source.
+*minsamples* _samples_:::
+Set the minimum number of samples kept for this source. This overrides the
+<<minsamples,*minsamples*>> directive.
+*maxsamples* _samples_:::
+Set the maximum number of samples kept for this source. This overrides the
+<<maxsamples,*maxsamples*>> directive.
+
+[[manual]]*manual*::
+The *manual* directive enables support at run-time for the
+<<chronyc.adoc#settime,*settime*>> command in *chronyc*. If no *manual*
+directive is included, any attempt to use the *settime* command in *chronyc*
+will be met with an error message.
++
+Note that the *settime* command can be enabled at run-time using
+the <<chronyc.adoc#manual,*manual*>> command in *chronyc*. (The idea of the two
+commands is that the *manual* command controls the manual clock driver's
+behaviour, whereas the *settime* command allows samples of manually entered
+time to be provided.)
+
+[[acquisitionport]]*acquisitionport* _port_::
+By default, *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 *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 some firewalls. If set to 0, the source
+port of the socket will be chosen arbitrarily.
++
+It may be set to the same port as is used by the NTP server (which can be
+configured with the <<port,*port*>> directive) to use only one socket for all
+NTP packets.
++
+An example of the *acquisitionport* directive is
++
+----
+acquisitionport 1123
+----
++
+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.
+
+[[bindacqaddress]]*bindacqaddress* _address_::
+The *bindacqaddress* directive sets the network interface to which will
+*chronyd* bind its NTP client sockets. The syntax is similar to the
+<<bindaddress,*bindaddress*>> and <<bindcmdaddress,*bindcmdaddress*>>
+directives.
++
+For each of IPv4 and IPv6 protocols, only one *bindacqaddress* directive can be
+specified.
+
+[[dumpdir]]*dumpdir* _directory_::
+To compute the rate of gain or loss of time, *chronyd* has to store a
+measurement history for each of the time sources it uses.
++
+Certain systems (Linux, FreeBSD, NetBSD, Solaris) have operating system support
+for setting the rate of gain or loss to compensate for known errors. (On Mac OS
+X, *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 *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* directive in the configuration file, or the
+<<chronyc.adoc#dump,*dump*>> command in *chronyc*), the *dumpdir* directive
+should be used to define the directory where the measurement histories are
+saved.
++
+An example of the directive is
++
+----
+dumpdir @CHRONYVARDIR@
+----
++
+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
+_/var/lib/chrony/1.2.3.4.dat_.
+
+[[dumponexit]]*dumponexit*::
+If this directive is present, it indicates that *chronyd* should save the
+measurement history for each of its time sources recorded whenever the program
+exits. (See the <<dumpdir,*dumpdir*>> directive above.)
+
+[[maxsamples]]*maxsamples* _samples_::
+The *maxsamples* directive sets the default maximum number of samples that
+*chronyd* should keep for each source. This setting can be overridden for
+individual sources in the <<server,*server*>> and <<refclock,*refclock*>>
+directives. The default value is 0, which disables the configurable limit. The
+useful range is 4 to 64.
+
+[[minsamples]]*minsamples* _samples_::
+The *minsamples* directive sets the default minimum number of samples that
+*chronyd* should keep for each source. This setting can be overridden for
+individual sources in the <<server,*server*>> and <<refclock,*refclock*>>
+directives. The default value is 0. The useful range is 4 to 64.
+
+=== Source selection
+
+[[combinelimit]]*combinelimit* _limit_::
+When *chronyd* has multiple sources available for synchronisation, it has to
+select one source as the synchronisation 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 *combinelimit* directive limits which sources are included in the combining
+algorithm. Their synchronisation 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.
+
+[[maxdistance]]*maxdistance* _distance_::
+The *maxdistance* directive sets the maximum allowed root distance of the
+sources to not be rejected by the source selection algorithm. The distance
+includes the accumulated dispersion, which may be large when the source is no
+longer synchronised, and half of the total round-trip delay to the primary
+source.
++
+By default, the maximum root distance is 3 seconds.
++
+Setting *maxdistance* to a larger value can be useful to allow synchronisation
+with a server that only has a very infrequent connection to its sources and can
+accumulate a large dispersion between updates of its clock.
+
+[[minsources]]*minsources* _sources_::
+The *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.
+
+[[reselectdist]]*reselectdist* _distance_::
+When *chronyd* selects a synchronisation source from available sources, it
+will prefer the one with the shortest 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 *reselectdist* directive. By default, the
+distance is 100 microseconds.
+
+[[stratumweight]]*stratumweight* _distance_::
+The *stratumweight* directive sets how much distance should be added per
+stratum to the synchronisation distance when *chronyd* selects the
+synchronisation source from available sources.
++
+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.
+
+=== System clock
+
+[[corrtimeratio]]*corrtimeratio* _ratio_::
+When *chronyd* is slewing the system clock to correct an offset, the rate at
+which it is slewing adds to the frequency error of the clock. On Linux,
+FreeBSD, NetBSD and Solaris this rate can be controlled.
++
+The *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 *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 maximum allowed slew rate can be set by the <<maxslewrate,*maxslewrate*>>
+directive. The current remaining correction is shown in the
+<<chronyc.adoc#tracking,*tracking*>> report as the *System time* value.
+
+[[driftfile]]*driftfile* _file_::
+One of the main activities of the *chronyd* program is to work out the rate at
+which the system clock gains or loses time relative to real time.
++
+Whenever *chronyd* computes a new value of the gain/loss rate, it is desirable
+to record it somewhere. This allows *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* directive allows a file to be specified into which *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 directive is
++
+----
+driftfile @CHRONYVARDIR@/drift
+----
+
+[[fallbackdrift]]*fallbackdrift* _min-interval_ _max-interval_::
+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
++
+----
+fallbackdrift 16 19
+----
++
+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.
+
+[[leapsecmode]]*leapsecmode* _mode_::
+A leap second is an adjustment that is occasionally applied to UTC to keep it
+close to the mean solar time. When a leap second is inserted, the last day of
+June or December has an extra second 23:59:60.
++
+For computer clocks that is a problem. The Unix time is defined as number of
+seconds since 00:00:00 UTC on 1 January 1970 without leap seconds. The system
+clock cannot have time 23:59:60, every minute has 60 seconds and every day has
+86400 seconds by definition. The inserted leap second is skipped and the clock
+is suddenly ahead of UTC by one second. The *leapsecmode* directive selects how
+that error is corrected. There are four options:
++
+*system*:::
+When inserting a leap second, the kernel steps the system clock backwards by
+one second when the clock gets to 00:00:00 UTC. When deleting a leap second, it
+steps forward by one second when the clock gets to 23:59:59 UTC. This is the
+default mode when the system driver supports leap seconds (i.e. on Linux,
+FreeBSD, NetBSD and Solaris).
+*step*:::
+This is similar to the *system* mode, except the clock is stepped by
+*chronyd* instead of the kernel. It can be useful to avoid bugs in the kernel
+code that would be executed in the *system* mode. This is the default mode
+when the system driver doesn't support leap seconds.
+*slew*:::
+The clock is corrected by slewing started at 00:00:00 UTC when a leap second
+is inserted or 23:59:59 UTC when a leap second is deleted. This may be
+preferred over the *system* and *step* modes 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
+<<maxslewrate,*maxslewrate*>> value the correction takes 12 seconds.
+*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.
+::
++
+When serving time to NTP clients that can't be configured to correct their
+clocks for a leap second by slewing or they would correct them at slightly
+different rates when it's necessary to keep them close together, the *slew*
+mode can be combined with the <<smoothtime,*smoothtime*>> directive to enable a
+server leap smear.
++
+When smearing a leap second, the leap status is suppressed on the server and
+the served time is corrected slowly be slewing instead of stepping. The clients
+don't need any special configuration as they don't know there is any leap
+second and they follow the server time which eventually brings them back to
+UTC. Care must be taken to ensure they use for synchronisation only NTP servers
+which smear the leap second in exactly the same way.
++
+This feature must be used carefully, because the server is intentionally not
+serving its best estimate of the true time.
++
+A recommended configuration to enable a server leap smear is:
++
+----
+leapsecmode slew
+maxslewrate 1000
+smoothtime 400 0.001 leaponly
+----
++
+The first directive is necessary to disable the clock step which would reset
+the smoothing process. The second directive limits the slewing rate of the
+local clock to 1000 ppm, which improves the stability of the smoothing process
+when the local correction starts and ends. The third directive enables the
+server time smoothing process. It will start when the clock gets to 00:00:00
+UTC and it will take 17 hours 34 minutes to finish. The frequency offset will
+be changing by 0.001 ppm per second and will reach a maximum of 31.623 ppm. The
+*leaponly* option makes the duration of the leap smear constant and allows the
+clients to safely synchronise with multiple identically configured leap
+smearing servers.
+
+[[leapsectz]]*leapsectz* _timezone_::
+This directive is used to set the name of the timezone in the system tz
+database which *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. This typically works with the *right/UTC*
+timezone.
++
+This directive is mainly useful with reference clocks which don't provide the
+leap second information. It is not necessary to restart *chronyd* if the tz
+database is updated with a new leap second at least 12 hours before the event.
++
+An example of the directive is
++
+----
+leapsectz right/UTC
+----
++
+The following shell command verifies that the timezone contains leap seconds
+and can be used with this directive
++
+----
+$ TZ=right/UTC date -d 'Dec 31 2008 23:59:60'
+Wed Dec 31 23:59:60 UTC 2008
+----
+
+[[makestep]]*makestep* _threshold_ _limit_::
+Normally *chronyd* will cause the system to gradually correct any time offset,
+by slowing down or speeding up the clock as required. In certain situations,
+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 *chronyd* to step system clock if the adjustment is
+larger than a threshold value, but only if there were no more clock updates
+since *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
+<<initstepslew,*initstepslew*>> directive works only with NTP sources.
++
+An example of the use of this directive is
++
+----
+makestep 0.1 3
+----
++
+This would step system clock if the adjustment is larger than 0.1 seconds, but
+only in the first three clock updates.
+
+[[maxchange]]*maxchange* _offset_ _start_ _ignore_::
+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 *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
++
+----
+maxchange 1000 1 2
+----
++
+After the first clock update, *chronyd* will check the offset on every clock
+update, it will ignore two adjustments larger than 1000 seconds and exit on
+another one.
+
+[[maxclockerror]]*maxclockerror* _error-in-ppm_::
+The *maxclockerror* directive sets the maximum assumed frequency error that the
+system clock can gain on its own between clock updates. It describes the
+stability of the clock.
++
+By default, the maximum error is 1 ppm.
++
+Typical values for _error-in-ppm_ might be 10 for a low quality clock and 0.1
+for a high quality clock using a temperature compensated crystal oscillator.
+
+[[maxupdateskew]]*maxupdateskew* _skew-in-ppm_::
+One of *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 *maxupdateskew* directive sets the threshold for determining whether an
+estimate may be so unreliable that it should not be used. By default, the
+threshold is 1000 ppm.
++
+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, *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 *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.
+
+[[maxslewrate]]*maxslewrate* _rate-in-ppm_::
+The *maxslewrate* directive sets the maximum rate at which *chronyd* is allowed
+to slew the time. It limits the slew rate controlled by the correction time
+ratio (which can be set by the <<corrtimeratio,*corrtimeratio*>> directive) and
+is effective only on systems where *chronyd* is able to control the rate (i.e.
+Linux, FreeBSD, NetBSD, Solaris).
++
+For each system there is a maximum frequency offset of the clock that
+can be set by the driver. On Linux it's 100000 ppm, on FreeBSD and NetBSD
+it's 5000 ppm and on Solaris it is 32500 ppm. Also, due to a kernel
+limitation, setting *maxslewrate* on FreeBSD and NetBSD to a value between 500
+ppm and 5000 ppm will effectively set it to 500 ppm.
++
+By default, the maximum slew rate is set to 83333.333 ppm (one twelfth).
+
+[[tempcomp]]
+*tempcomp* _file_ _interval_ _T0_ _k0_ _k1_ _k2_::
+*tempcomp* _file_ _interval_ _points-file_::
+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 *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 _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
++
+----
+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 adjusted to
+keep the compensation in that range.
++
+An example of use is
++
+----
+tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 26000 0.0 0.000183 0.0
+----
++
+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
++
+----
+tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 /etc/chrony.tempcomp
+----
++
+where the _/etc/chrony.tempcomp_ file could have
++
+----
+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
+----
++
+Valid measurements with corresponding compensations are logged to the
+_tempcomp.log_ file if enabled by the <<log,*log tempcomp*>> directive.
+
+=== NTP server
+
+[[allow]]*allow* [*all*] [_subnet_]::
+The *allow* directive 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. *chronyd* operates
+purely as an NTP client. If the *allow* directive is used, *chronyd* will be
+both a client of its servers, and a server to other clients.
++
+Examples of use of the directive are as follows:
++
+----
+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
+----
++
+The first directive allows the named node to be an NTP client of this computer.
+The second directive 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 directive 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, *allow all*, has a greater effect, depending on
+the ordering of directives in the configuration file. To illustrate the effect,
+consider the two examples
++
+----
+allow 1.2.3.4
+deny 1.2.3
+allow 1.2
+----
++
+and
++
+----
+allow 1.2.3.4
+deny 1.2.3
+allow all 1.2
+----
++
+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 *allow all 1.2* directives overrides the effect of
+_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 *chronyc* with the
+<<chronyc.adoc#allow,*allow all*>> command.
++
+Note, if the <<initstepslew,*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.
+
+[[deny]]*deny* [*all*] [_subnet_]::
+This is similar to the <<allow,*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 *deny all* directive with similar behaviour to the *allow all*
+directive.
+
+[[bindaddress]]*bindaddress* _address_::
+The *bindaddress* directive allows you to restrict the network interface to
+which *chronyd* will listen for NTP requests. This provides an additional level
+of access restriction above that available through the <<deny,*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
++
+----
+bindaddress 192.168.1.1
+----
++
+to the configuration file.
++
+For each of IPv4 and IPv6 protocols, only one *bindaddress* directive can be
+specified. Therefore, it's not useful on computers which should serve NTP on
+multiple network interfaces.
+
+[[broadcast]]*broadcast* _interval_ _address_ [_port_]::
+The *broadcast* directive is used to declare a broadcast address to which
+chronyd should send packets in the 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
++
+----
+broadcast 30 192.168.1.255
+broadcast 60 192.168.2.255 12123
+broadcast 60 ff02::101
+----
++
+In the first example, the destination port defaults to 123/udp (the normal NTP
+port). In the second example, the destination 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 *broadcast* directive if you have more than 1 network
+interface onto which you wish to send NTP broadcast packets.
++
+*chronyd* itself cannot 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
+implementations.
++
+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 <<allow,*allow*>> directive.
+
+[[clientloglimit]]*clientloglimit* _limit_::
+This directive specifies the maximum amount of memory that *chronyd* is allowed
+to allocate for logging of client accesses. The default limit is 524288 bytes,
+which allows monitoring of several thousands of addresses at the same time.
++
+In older *chrony* versions if the limit was set to 0, the memory allocation was
+unlimited.
++
+An example of the use of this directive is
++
+----
+clientloglimit 1048576
+----
+
+[[noclientlog]]*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 <<chronyc.adoc#clients,*clients*>> command in *chronyc*.
+
+[[local]]*local* *stratum* _stratum_::
+The *local* directive is used to allow *chronyd* to appear synchronised to real
+time (from the viewpoint of clients polling it), even if it has no current
+synchronisation source.
++
+This directive 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 directive is
++
+----
+local stratum 10
+----
++
+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* directive
+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.
+
+[[port]]*port* _port_::
+This option allows you to configure the port on which *chronyd* will listen for
+NTP requests. The port will be open only when an address is allowed by the
+<<allow,*allow*>> directive or the <<chronyc.adoc#allow,*allow*>> command in
+*chronyc*, an NTP peer is configured, or the broadcast server mode is enabled.
++
+The default value is 123, the standard NTP port. If set to 0, *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
+<<acquisitionport,*acquisitionport*>> directive.
+
+[[ratelimit]]*ratelimit* [_option_]...::
+This directive enables response rate limiting for NTP packets. Its purpose is
+to reduce network traffic with misconfigured or broken NTP clients that are
+polling the server too frequently. The limits are applied to individual IP
+addresses. If multiple clients share one IP address (e.g. multiple hosts behind
+NAT), the sum of their traffic will be limited. If a client that increases its
+polling rate when it doesn't receive a reply is detected, its rate limiting
+will be temporarily suspended to avoid increasing the overall amount of
+traffic. The maximum number of IP addresses which can be monitored at the same
+time depends on the memory limit set by the <<clientloglimit,*clientloglimit*>>
+directive.
++
+The *ratelimit* directive supports a number of options (which may be defined
+in any order):
++
+*interval*:::
+This option sets the minimum interval between responses. It is defined as a
+power of 2 in seconds. The default value is 3 (8 seconds). The minimum value
+is -4 and the maximum value is 12.
+*burst*:::
+This option sets the maximum number of responses that can be send in a burst,
+temporarily exceeding the limit specified by the *interval* option. This is
+useful for clients that make rapid measurements on start (e.g. *chronyd* with
+the *iburst* option). The default value is 8. The minimum value is 1 and the
+maximum value is 255.
+*leak*:::
+This option sets the rate at which responses are randomly allowed even if the
+limits specified by the *interval* and *burst* options are exceeded. This is
+necessary to prevent an attacker who is sending requests with a spoofed
+source address from completely blocking responses to that address. The leak
+rate is defined as a power of 1/2 and it is 3 by default, i.e. on average at
+least every eighth request has a response. The minimum value is 1 and the
+maximum value is 4.
+::
++
+An example use of the directive is
++
+----
+ratelimit interval 4 burst 4
+----
++
+This would reduce the response rate for IP addresses that send packets on
+average more frequently than once per 16 seconds and/or send packets in bursts
+with more than 4 packets.
+
+[[smoothtime]]*smoothtime* _max-freq_ _max-wander_ [*leaponly*]::
+The *smoothtime* directive can be used to enable smoothing of the time that
+*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.
++
+BE WARNED - the server is intentionally not serving its best estimate of the
+true 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 implemented with a quadratic spline function with two
+or three pieces. It's independent from any slewing applied to the local system
+clock, but the accumulated offset and frequency will be reset when the clock is
+corrected by stepping, e.g. by the <<makestep,*makestep*>> directive or the
+<<chronyc.adoc#makestep,*makestep*>> command in *chronyc*. The process can be
+reset without stepping the clock by the <<chronyc.adoc#smoothtime,*smoothtime
+reset*>> command.
++
+The first two arguments of the directive are 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). *leaponly*
+is an optional third argument which enables a mode where only leap seconds are
+smoothed out and normal offset/frequency changes are ignored. The *leaponly*
+option is useful in a combination with the <<leapsecmode,*leapsecmode slew*>>
+directive to allow the clients to use multiple time smoothing servers safely.
++
+The smoothing process is activated automatically when 1/10000 of the estimated
+skew of the local clock falls below the maximum rate of frequency change. It
+can be also activated manually by the <<chronyc.adoc#smoothtime,*smoothtime
+activate*>> command, which is particularly useful when the clock is
+synchronised only with manual input and the skew is always larger than the
+threshold. The <<chronyc.adoc#smoothing,*smoothing*>> command can be used to
+monitor the process.
++
+An example suitable for clients using *ntpd* and 1024 second polling interval
+could be
++
+----
+smoothtime 400 0.001
+----
++
+An example suitable for clients using *chronyd* on Linux could be
++
+----
+smoothtime 50000 0.01
+----
+
+=== Command and monitoring access
+
+[[bindcmdaddress]]*bindcmdaddress* _address_::
+The *bindcmdaddress* directive allows you to specify the network interface on
+which *chronyd* will listen for monitoring command packets (issued by
+*chronyc*). This provides an additional level of access restriction above that
+available through <<cmddeny,*cmddeny*>> mechanism.
++
+This directive can also change the path of the Unix domain command socket,
+which is used by *chronyc* to send configuration commands. The socket must be
+in a directory that is accessible only by the root or _chrony_ user. The
+directory will be created on start if it doesn't exist. The compiled-in default
+path of the socket is _@CHRONYSOCKDIR@/chronyd.sock_.
++
+By default, *chronyd* binds to the loopback interface (with addresses
+_127.0.0.1_ and _::1_). This blocks all access except from localhost. To listen
+for command packets on all interfaces, you can add the lines
++
+----
+bindcmdaddress 0.0.0.0
+bindcmdaddress ::
+----
++
+to the configuration file.
++
+For each of IPv4 and IPv6 protocols, only one *bindcmdaddress* directive can be
+specified.
++
+An example that sets the path of the Unix domain command socket is
++
+----
+bindcmdaddress /var/run/chrony/chronyd.sock
+----
+
+[[cmdallow]]*cmdallow* [*all*] [_subnet_]::
+This is similar to the <<allow,*allow*>> directive, except that it allows
+monitoring access (rather than NTP client access) to a particular subnet or
+host. (By '`monitoring access`' is meant that *chronyc* can be run on those
+hosts and retrieve monitoring data from *chronyd* on this computer.)
++
+The syntax is identical to the *allow* directive.
++
+There is also a *cmdallow all* directive with similar behaviour to the *allow
+all* directive (but applying to monitoring access in this case, of course).
++
+Note that *chronyd* has to be configured with the
+<<bindcmdaddress,*bindcmdaddress*>> directive to not listen only on the
+loopback interface to actually allow remote access.
+
+[[cmddeny]]*cmddeny* [*all*] [_subnet_]::
+This is similar to the <<cmdallow,*cmdallow*>> directive, except that it denies
+monitoring access to a particular subnet or host, rather than allowing it.
++
+The syntax is identical.
++
+There is also a *cmddeny all* directive with similar behaviour to the *cmdallow
+all* directive.
+
+[[cmdport]]*cmdport* _port_::
+The *cmdport* directive allows the port that is used for run-time monitoring
+(via the *chronyc* program) to be altered from its default (323). If set to 0,
+*chronyd* will not open the port, this is useful to disable the *chronyc*
+access from the internet. (It does not disable the Unix domain command socket.)
++
+An example shows the syntax
++
+----
+cmdport 257
+----
++
+This would make *chronyd* use 257/udp as its command port. (*chronyc* would
+need to be run with the *-p 257* switch to inter-operate correctly.)
+
+[[cmdratelimit]]*cmdratelimit* [_option_]...::
+This directive enables response rate limiting for command packets. It's
+similar to the <<ratelimit,*ratelimit*>> directive, except responses to the
+localhost are never limited and the default interval is 1 (2 seconds), default
+burst is 16, and default leak rate is 2.
++
+An example of use of the directive is
++
+----
+cmdratelimit interval 2
+----
+
+=== Real-time clock (RTC)
+
+[[hwclockfile]]*hwclockfile* _file_::
+The *hwclockfile* directive sets the location of the adjtime file which is
+used by the *hwclock* program on Linux. *chronyd* parses the file to find out
+if the RTC keeps local time or UTC. It overrides the <<rtconutc,*rtconutc*>>
+directive.
++
+The compiled-in default value is '_@DEFAULT_HWCLOCK_FILE@_'.
++
+An example of the directive is
++
+----
+hwclockfile /etc/adjtime
+----
+
+[[rtcautotrim]]*rtcautotrim* _threshold_::
+The *rtcautotrim* directive is used to keep the RTC close to the system clock
+automatically. When the system clock is synchronised and the estimated error
+between the two clocks is larger than the specified threshold, *chronyd* will
+trim the RTC as if the <<chronyc.adoc#trimrtc,*trimrtc*>> command in *chronyc*
+was issued.
++
+This directive is effective only with the <<rtcfile,*rtcfile*>> directive.
++
+An example of the use of this directive is
++
+----
+rtcautotrim 30
+----
++
+This would set the threshold error to 30 seconds.
+
+[[rtcdevice]]*rtcdevice* _device_::
+The *rtcdevice* directive sets the path to the device file for accessing the
+RTC. The default path is _/dev/rtc_.
+
+[[rtcfile]]*rtcfile* _file_::
+The *rtcfile* directive defines the name of the file in which *chronyd* can
+save parameters associated with tracking the accuracy of the RTC.
++
+An example of the directive is
++
+----
+rtcfile @CHRONYVARDIR@/rtc
+----
++
+*chronyd* saves information in this file when it exits and when the *writertc*
+command is issued in *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 RTC
+facilities (the <<rtcfile,*rtcfile*>> directive and the *-s* command-line
+option to *chronyd*) if the following three conditions apply:
++
+. You are running Linux.
+. The kernel is compiled with extended real-time clock support (i.e. the
+ _/dev/rtc_ device is capable of doing useful things).
+. You don't have other applications that need to make use of _/dev/rtc_ at all.
+
+[[rtconutc]]*rtconutc*::
+*chronyd* assumes by default that the RTC keeps local time (including any
+daylight saving changes). This is convenient on PCs running Linux which are
+dual-booted with Windows.
++
+If you keep the RTC 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 *rtconutc* directive appears, it means the RTC is required to keep UTC.
+The directive takes no arguments. It is equivalent to specifying the *-u*
+switch to the Linux *hwclock* program.
++
+Note that this setting is overridden when the <<hwclockfile,*hwclockfile*>>
+directive is specified.
+
+[[rtcsync]]*rtcsync*::
+The *rtcsync* directive enables a mode where the system time is periodically
+copied to the RTC and *chronyd* doesn't try to track its drift. This directive
+cannot be used with the <<rtcfile,*rtcfile*>> directive.
++
+On Linux, the RTC copy is performed by the kernel every 11 minutes.
++
+On Mac OS X, <<chronyd,*chronyd*>> will perform the RTC copy every 60 minutes
+when the system clock is in a synchronised state.
++
+On other systems this directive does nothing.
+
+=== Logging
+
+[[log]]*log* [_option_]...::
+The *log* directive indicates that certain information is to be logged.
+The log files are written to the directory specified by the <<logdir,*logdir*>>
+directive. A banner is periodically written to the files to indicate the
+meanings of the columns.
++
+*measurements*:::
+This option logs the raw NTP measurements and related information to a file
+called _measurements.log_. An example line (which actually appears as a single
+line in the file) from the log file is shown below.
++
+----
+2015-10-13 05:40:50 203.0.113.15 N 2 111 111 1111 10 10 1.0 \
+ -4.966e-03 2.296e-01 1.577e-05 1.615e-01 7.446e-03
+----
++
+The columns are as follows (the quantities in square brackets are the values
+from the example line above):
++
+. Date [2015-10-13]
+. Hour:Minute:Second. Note that the date/time pair is expressed in UTC, not the
+ local time zone. [05:40:50]
+. IP address of server/peer from which measurement comes [203.0.113.15]
+. Leap status (_N_ means normal, _+_ means that the last minute of the current
+ month has 61 seconds, _-_ means that the last minute of the month has 59
+ seconds, _?_ means the remote computer is not currently synchronised.) [N]
+. Stratum of remote computer. [2]
+. RFC 5905 tests 1 through 3 (1=pass, 0=fail) [111]
+. RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111]
+. 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]
+. Local poll [10]
+. Remote poll [10]
+. '`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]
+. The estimated local clock error (_theta_ in RFC 5905). Positive indicates
+ that the local clock is slow of the remote source. [-4.966e-03]
+. The peer delay (_delta_ in RFC 5905). [2.296e-01]
+. The peer dispersion (`epsilon' in RFC 5905). [1.577e-05]
+. The root delay (_DELTA_ in RFC 5905). [1.615e-01]
+. The root dispersion (_EPSILON_ in RFC 5905). [7.446e-03]
++
+*statistics*:::
+This option logs information about the regression processing to a file called
+_statistics.log_. An example line (which actually appears as a single line in
+the file) from the log file is shown below.
++
+----
+2015-07-22 05:40:50 203.0.113.15 6.261e-03 -3.247e-03 \
+ 2.220e-03 1.874e-06 1.080e-06 7.8e-02 16 0 8
+----
++
+The columns are as follows (the quantities in square brackets are the values
+from the example line above):
++
+. Date [2015-07-22]
+. Hour:Minute:Second. Note that the date/time pair is expressed in
+ UTC, not the local time zone. [05:40:50]
+. IP address of server/peer from which measurement comes [203.0.113.15]
+. The estimated standard deviation of the measurements from the source (in
+ seconds). [6.261e-03]
+. The estimated offset of the source (in seconds, positive means the local
+ clock is estimated to be fast, in this case). [-3.247e-03]
+. The estimated standard deviation of the offset estimate (in seconds).
+ [2.220e-03]
+. 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, _not_ to the local clock without any compensation.
+ [1.874e-06]
+. The estimated error in the rate value (in seconds per second). [1.080e-06].
+. 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]
+. The number of measurements currently being used for the regression
+ algorithm. [16]
+. 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]
+. 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]
++
+*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_. An example line (which
+actually appears as a single line in the file) from the log file is shown
+below.
++
+----
+2015-02-23 05:40:50 203.0.113.15 3 340.529 1.606 1.046e-03 N \
+ 4 6.849e-03 -4.670e-04
+----
++
+The columns are as follows (the quantities in square brackets are the
+values from the example line above) :
++
+. Date [2015-02-03]
+. Hour:Minute:Second. Note that the date/time pair is expressed in UTC, not the
+ local time zone. [05:40:50]
+. The IP address of the server/peer to which the local system is synchronised.
+ [203.0.113.15]
+. The stratum of the local system. [3]
+. The local system frequency (in ppm, positive means the local system runs fast
+ of UTC). [340.529]
+. The error bounds on the frequency (in ppm). [1.606]
+. 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]
+. Leap status (_N_ means normal, _+_ means that the last minute of this month
+ has 61 seconds, _-_ means that the last minute of the month has 59 seconds,
+ _?_ means the clock is not currently synchronised.) [N]
+. The number of combined sources. [4]
+. The estimated standard deviation of the combined offset (in seconds).
+ [6.849e-03]
+. The remaining offset correction from the previous update (in seconds,
+ positive means the system clock is slow of UTC). [-4.670e-04]
++
+*rtc*:::
+This option logs information about the system's real-time clock. An example
+line (which actually appears as a single line in the file) from the _rtc.log_
+file is shown below.
++
+----
+2015-07-22 05:40:50 -0.037360 1 -0.037434\
+ -37.948 12 5 120
+----
++
+The columns are as follows (the quantities in square brackets are the
+values from the example line above):
++
+. Date [2015-07-22]
+. Hour:Minute:Second. Note that the date/time pair is expressed in UTC, not the
+ local time zone. [05:40:50]
+. The measured offset between the RTC and the system clock in seconds.
+ Positive indicates that the RTC is fast of the system time [-0.037360].
+. Flag indicating whether the regression has produced valid coefficients.
+ (1 for yes, 0 for no). [1]
+. 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]
+. 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]
+. The number of measurements used in the regression. [12]
+. 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]
+. The measurement interval used prior to the measurement being made (in
+ seconds). [120]
++
+*refclocks*:::
+This option logs the raw and filtered reference clock measurements to a file
+called _refclocks.log_. An example line (which actually appears as a single
+line in the file) from the log file is shown below.
++
+----
+2009-11-30 14:33:27.000000 PPS2 7 N 1 4.900000e-07 -6.741777e-07 1.000e-06
+----
++
+The columns are as follows (the quantities in square brackets are the values
+from the example line above):
++
+. Date [2009-11-30]
+. Hour:Minute:Second.Microsecond. Note that the date/time pair is expressed in
+ UTC, not the local time zone. [14:33:27.000000]
+. Reference ID of the refclock from which the measurement came. [PPS2]
+. Sequence number of driver poll within one polling interval for raw samples,
+ or _-_ for filtered samples. [7]
+. Leap status (_N_ means normal, _+_ means that the last minute of the current
+ month has 61 seconds, _-_ means that the last minute of the month has 59
+ seconds). [N]
+. Flag indicating whether the sample comes from PPS source. (1 for yes,
+ 0 for no, or _-_ for filtered sample). [1]
+. Local clock error measured by refclock driver, or _-_ for filtered sample.
+ [4.900000e-07]
+. Local clock error with applied corrections. Positive indicates that the local
+ clock is slow. [-6.741777e-07]
+. Assumed dispersion of the sample. [1.000e-06]
++
+*tempcomp*:::
+This option logs the temperature measurements and system rate compensations to
+a file called _tempcomp.log_. An example line (which actually appears as a
+single line in the file) from the log file is shown below.
++
+----
+2015-04-19 10:39:48 2.8000e+04 3.6600e-01
+----
++
+The columns are as follows (the quantities in square brackets are the values
+from the example line above):
++
+. Date [2015-04-19]
+. Hour:Minute:Second. Note that the date/time pair is expressed in UTC, not the
+ local time zone. [10:39:48]
+. Temperature read from tempcomp file. [2.8000e+04]
+. Applied compensation in ppm, positive means the system clock is running
+ faster than it would be without the compensation. [3.6600e-01]
++
+::
+An example of the directive is
++
+----
+log measurements statistics tracking
+----
+
+[[logbanner]]*logbanner* _entries_::
+A banner is periodically written to the log files enabled by the <<log,*log*>>
+directive to indicate the meanings of the columns.
++
+The *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.
+
+[[logchange]]*logchange* _threshold_::
+This directive sets the threshold for the adjustment of the system clock that
+will generate a syslog message. Clock errors detected via NTP packets,
+reference clocks, or timestamps entered via the
+<<chronyc.adoc#settime,*settime*>> command of *chronyc* are logged.
++
+By default, the threshold is 1 second.
++
+An example of use is
++
+----
+logchange 0.1
+----
++
+which would cause a syslog message to be generated a system clock error of over
+0.1 seconds starts to be compensated.
+
+[[logdir]]*logdir* _directory_::
+This directive allows the directory where log files are written to be
+specified.
++
+An example of the use of this directive is
++
+----
+logdir /var/log/chrony
+----
+
+[[mailonchange]]*mailonchange* _email_ _threshold_::
+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
++
+----
+mailonchange root@localhost 0.5
+----
++
+This would send a mail message to root if a change of more than 0.5 seconds
+were applied to the system clock.
++
+This directive can't be used when a system call filter is enabled by the *-F*
+option as the *chronyd* process will not be allowed to fork and execute the
+sendmail binary.
+
+=== Miscellaneous
+
+[[include]]*include* _pattern_::
+The *include* directive includes a configuration file or multiple configuration
+files if a wildcard pattern is specified. This can be useful when maintaining
+configuration on multiple hosts to keep the differences in separate files.
++
+An example of the directive is
++
+----
+include @SYSCONFDIR@/chrony.d/*.conf
+----
+
+[[keyfile]]*keyfile* _file_::
+This directive is used to specify the location of the file containing ID/key
+pairs for authentication of NTP packets.
++
+The format of the directive is shown in the example below
++
+----
+keyfile @SYSCONFDIR@/chrony.keys
+----
++
+The argument is simply the name of the file containing the ID/key pairs. The
+format of the file is shown below
++
+----
+10 tulip
+11 hyacinth
+20 MD5 ASCII:crocus
+25 SHA1 HEX:1dc764e0791b11fa67efc7ecbc4b0d73f68a070c
+ ...
+----
++
+Each line consists of an ID, name of an authentication hash function (optional)
+and a password. The ID can be any unsigned integer in the range 1 through
+2^32-1. The default hash function is *MD5*. Depending on how *chronyd*
+was compiled, other supported functions may be *SHA1*, *SHA256*, *SHA384*,
+*SHA512*, *RMD128*, *RMD160*, *RMD256*, *RMD320*, *TIGER* and *WHIRLPOOL*. The
+password can be specified as a string of characters not containing white space
+with an optional *ASCII:* prefix, or as a hexadecimal number with the *HEX:*
+prefix. The maximum length of the line is 2047 characters.
++
+The password is used with the hash function to generate and verify a message
+authentication code (MAC) in NTP packets. It's recommended to use SHA1 or a
+stronger hash function with random passwords specified in the hexadecimal
+format that have at least 128 bits. *chronyd* will log a warning to
+syslog on start if a source is specified in the configuration file with a key
+that has password shorter than 80 bits.
++
+The <<chronyc.adoc#keygen,*keygen*>> command of *chronyc* can be used to
+generate random keys for the key file. By default, it generates 160-bit MD5 or
+SHA1 keys.
+
+[[lock_all]]*lock_all*::
+The *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 *chronyd* from ever being swapped out. This
+should result in lower and more consistent latency. It should not have
+significant impact on performance as *chronyd's* memory usage is modest. The
+*mlockall(2)* man page has more details.
+
+[[pidfile]]*pidfile* _file_::
+*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 _/var/run/chronyd.pid_. The *pidfile* directive
+allows the name to be changed, e.g.
++
+----
+pidfile /run/chronyd.pid
+----
+
+[[sched_priority]]*sched_priority* _priority_::
+On Linux, the *sched_priority* directive will select the SCHED_FIFO real-time
+scheduler at the specified priority (which must be between 0 and 100). On Mac
+OS X, this option must have either a value of 0 (the default) to disable the
+thread time constraint policy or 1 for the policy to be enabled. Other systems
+do not support this option.
++
+On Linux, this directive uses the *sched_setscheduler()* system call to
+instruct the kernel to use the SCHED_FIFO first-in, first-out real-time
+scheduling policy for *chronyd* with the specified priority. This means that
+whenever *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 *chronyd* resource requirements are modest, but it should
+result in lower and more consistent latency since *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(2)* man page has more
+details.
++
+On Mac OS X, this directive uses the *thread_policy_set()* kernel call to
+specify real-time scheduling. As noted for Linux, you should not use this
+directive unless you really need it.
+
+[[user]]*user* _user_::
+The *user* directive sets the name of the system user to which *chronyd* will
+switch after start in order to drop root privileges.
++
+On Linux, *chronyd* needs to be compiled with support for the *libcap* library.
+On Mac OS X, FreeBSD, NetBSD and Solaris *chronyd* forks into two processes.
+The child process retains root privileges, but can only perform a very limited
+range of privileged system calls on behalf of the parent.
++
+The compiled-in default value is _@DEFAULT_USER@_.
+
+[[examples]]
+== EXAMPLES
+
+=== NTP client with permanent connection to NTP servers
+
+This section shows how to configure *chronyd* 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 servers
+you wish to use. You may be able to find names of suitable servers by one of
+the following methods:
+
+* Your institution may already operate servers on its network.
+ Contact your system administrator to find out.
+* Your ISP probably has one or more NTP servers available for its
+ customers.
+* 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.
+* Use public servers from the http://www.pool.ntp.org/[pool.ntp.org] project.
+
+Assuming that your NTP servers are called _foo.example.net_, _bar.example.net_
+and _baz.example.net_, your _chrony.conf_ file could contain as a minimum
+
+----
+server foo.example.net
+server bar.example.net
+server baz.example.net
+----
+
+However, you will probably want to include some of the other directives. The
+<<driftfile,*driftfile*>>, <<makestep,*makestep*>> and <<rtcsync,*rtcsync*>>
+may be particularly useful. Also, the *iburst* option of the
+<<server,*server*>> directive is useful to speed up the initial
+synchronisation. The smallest useful configuration file would look something
+like
+
+----
+server foo.example.net iburst
+server bar.example.net iburst
+server baz.example.net iburst
+driftfile @CHRONYVARDIR@/drift
+makestep 1.0 3
+rtcsync
+----
+
+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 <<pool,*pool*>>
+directive instead of multiple *server* directives. The configuration file could
+in this case look like
+
+----
+pool pool.ntp.org iburst
+driftfile @CHRONYVARDIR@/drift
+makestep 1.0 3
+rtcsync
+----
+
+=== NTP client with infrequent connection to NTP servers
+
+This section shows how to configure *chronyd* for computers that have
+occasional connections to NTP servers. In this case, you will need some
+additional configuration to tell *chronyd* when the connection 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 _foo.example.net_,
+_bar.example.net_ and _baz.example.net_, your _chrony.conf_ file would now
+contain
+
+----
+server foo.example.net offline
+server bar.example.net offline
+server baz.example.net offline
+driftfile @CHRONYVARDIR@/drift
+makestep 1.0 3
+rtcsync
+----
+
+The *offline* keyword indicates that the servers start in an offline state, and
+that they should not be contacted until *chronyd* receives notification from
+*chronyc* that the link to the Internet is present. To tell *chronyd* when to
+start and finish sampling the servers, the <<chronyc.adoc#online,*online*>> and
+<<chronyc.adoc#offline,*offline*>> commands of *chronyc* need to be used.
+
+To give an example of their use, assuming that *pppd* is the program being
+used to connect to the Internet and that *chronyc* has been installed at
+_@BINDIR@/chronyc_, the script _/etc/ppp/ip-up_ would include
+
+----
+@BINDIR@/chronyc online
+----
+
+and the script _/etc/ppp/ip-down_ would include
+
+----
+@BINDIR@/chronyc offline
+----
+
+*chronyd*'s polling of the servers would now only occur whilst the machine is
+actually connected to the Internet.
+
+=== Isolated networks
+
+This section shows how to configure *chronyd* 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. *chronyd* includes support for this,
+in the form of the <<manual,*manual*>> directive and the
+<<chronyc.adoc#settime,*settime*>> command in the *chronyc* program.
+
+The <<smoothtime,*smoothtime*>> directive is useful when the clocks of the
+clients need to stay close together when the local time is adjusted by the
+<<chronyc.adoc#settime,*settime*>> command. The smoothing process needs to be
+activated by the <<chronyc.adoc#smoothtime,*smoothtime activate*>> command when
+the local time is ready to be served. After that point, any adjustments will be
+smoothed out.
+
+A typical configuration file for the master (called *master*) might be
+(assuming the clients are in the 192.168.165.x subnet)
+
+----
+driftfile @CHRONYVARDIR@/drift
+local stratum 8
+manual
+allow 192.168.165.0/24
+smoothtime 400 0.01
+----
+
+The configuration file on clients might be
+
+----
+server master iburst
+driftfile @CHRONYVARDIR@/drift
+logdir /var/log/chrony
+log measurements statistics tracking
+----
+
+=== RTC tracking
+
+This section considers a computer which has occasional connections to the
+Internet and is turned off between '`sessions`'. In this case, *chronyd* relies
+on the computer's RTC to maintain the time between the periods when it is
+powered up. 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
+RTC. On 2.6 and later kernels, if your motherboard has a HPET, you will need to
+enable the *HPET_EMULATE_RTC* option in your kernel configuration. Otherwise,
+*chronyd* will not be able to interact with the RTC device and will give up
+using it.
+
+When the computer is connected to the Internet, *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, *chronyd* makes measurements of the RTC (via
+the _/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.
+
+When the computer is powered down, the measurement histories for all the NTP
+servers are saved to files (if the <<dumponexit,*dumponexit*>> directive is
+specified in the configuration file), and the RTC tracking information is also
+saved to a file (if the <<rtcfile,*rtcfile*>> directive has been specified).
+These pieces of information are also saved if the <<chronyc.adoc#dump,*dump*>>
+and <<chronyc.adoc#writertc,*writertc*>> commands respectively are issued
+through *chronyc*.
+
+When the computer is rebooted, *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 *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 *trimrtc* command in *chronyc*. Because of this,
+*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 *dump* and
+*writertc* commands in the same place as the *offline* command is issued to
+take *chronyd* offline; because *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 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). *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 *log rtc* facility in the configuration
+file; this option should not be used if you want your disc to spin down.
+
+To illustrate how a computer might be configured for this case, example
+configuration files are shown.
+
+For the _chrony.conf_ file, the following can be used as an 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
+makestep 1.0 3
+maxupdateskew 100.0
+dumponexit
+dumpdir @CHRONYVARDIR@
+rtcfile @CHRONYVARDIR@/rtc
+----
+
+*pppd* is used for connecting to the Internet. This runs two scripts
+_/etc/ppp/ip-up_ and _/etc/ppp/ip-down_ when the link goes online and offline
+respectively.
+
+The relevant part of the _/etc/ppp/ip-up_ file is
+
+----
+@BINDIR@/chronyc online
+----
+
+and the relevant part of the _/etc/ppp/ip-down_ script is
+
+----
+@BINDIR@/chronyc -m offline dump writertc
+----
+
+*chronyd* is started during the boot sequence with the *-r* and *-s* options.
+It may need to be started before any software that depends on the system clock
+not jumping or moving backwards, depending on the directives in *chronyd*'s
+configuration file.
+
+For the system shutdown, *chronyd* should receive a SIGTERM several seconds
+before the final SIGKILL; the SIGTERM causes the measurement histories and RTC
+information to be saved out.
+
+== SEE ALSO
+
+<<chronyc.adoc#,*chronyc(1)*>>, <<chronyd.adoc#,*chronyd(8)*>>
+
+== BUGS
+
+For instructions on how to report bugs, please visit
+http://chrony.tuxfamily.org/.
+
+== AUTHORS
+
+chrony was written by Richard Curnow, Miroslav Lichvar and others.
--- /dev/null
+// This file is part of chrony
+//
+// Copyright (C) Richard P. Curnow 1997-2003
+// Copyright (C) Miroslav Lichvar 2009-2016
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of version 2 of the GNU General Public License as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful, but
+// WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along
+// with this program; if not, write to the Free Software Foundation, Inc.,
+// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+= chronyc(1)
+:doctype: manpage
+:man manual: User manual
+:man source: chrony @CHRONY_VERSION@
+
+== NAME
+
+chronyc - command-line interface for chrony daemon
+
+== SYNOPSIS
+
+*chronyc* [_OPTION_]... [_COMMAND_]...
+
+== DESCRIPTION
+
+*chronyc* is a command-line interface program which can be used to monitor
+*chronyd*'s performance and to change various operating parameters whilst it is
+running.
+
+If no commands are specified on the command line, *chronyc* will expect input
+from the user. The prompt _chronyc>_ will be displayed when it is being run
+from a terminal. If *chronyc*'s input or output are redirected from/to a file,
+the prompt is not shown.
+
+There are two ways how *chronyc* can access *chronyd*. One is the Internet
+Protocol (IPv4 or IPv6) and the other is a Unix domain socket, which is
+accessible locally by the root or _chrony_ user. By default, *chronyc* first
+tries to connect to the Unix domain socket. The compiled-in default path is
+_@CHRONYSOCKDIR@/chronyd.sock_. If that fails (e.g. because *chronyc* is
+running under a non-root user), it will try to connect to 127.0.0.1 and then
+::1.
+
+Only the following monitoring commands, which don't affect the behaviour of
+*chronyd*, are allowed from the internet: *activity*, *manual list*,
+*rtcdata*, *smoothing*, *sources*, *sourcestats*, *tracking*, *waitsync*. The
+set of hosts from which *chronyd* will accept these commands can be configured
+with the <<chrony.conf.adoc#cmdallow,*cmdallow*>> directive in the *chronyd*'s
+configuration file or the <<cmdallow,*cmdallow*>> command in *chronyc*. By
+default, the commands are accepted only from the localhost (127.0.0.1 or ::1).
+
+All other commands are allowed only through the Unix domain socket. When sent
+over the internet, *chronyd* will respond with a '`Not authorised`' error, even
+if it's from the localhost. In chrony versions before 2.2 they were allowed
+from the internet if they were authenticated with a password, but that is no
+longer supported.
+
+Having full access to *chronyd* via *chronyc* is more or less equivalent to
+being able to modify the *chronyd*'s configuration file and restart it.
+
+== OPTIONS
+
+*-4*::
+With this option hostnames will be resolved only to IPv4 addresses.
+
+*-6*::
+With this option hostnames will be resolved only to IPv6 addresses.
+
+*-n*::
+This option disables resolving of IP addresses to hostnames (e.g. to avoid slow
+DNS lookups).
+
+*-d*::
+This option enables printing of debugging messages if *chronyc* was compiled
+with debugging support).
+
+*-m*::
+Normally, all arguments on the command line are interpreted as one command.
+With this option multiple commands can be specified. Each argument will be
+interpreted as a whole command.
+
+*-h* _host_::
+This option allows the user to specify which host (or comma-separated list of
+addresses) running the *chronyd* program is to be contacted. This allows for
+remote monitoring, without having to ssh to the other host first.
++
+The default is to contact *chronyd* running on the same host as that where
+*chronyc* is being run.
+
+*-p* _port_::
+This option allows the user to specify the UDP port number which the target
+*chronyd* is using for its monitoring connections. This defaults to 323; there
+would rarely be a need to change this.
+
+*-f* _file_::
+This option is ignored and is provided only for compatibility.
+
+*-a*::
+This option is ignored and is provided only for compatibility.
+
+*-v*::
+With this option *chronyc* displays its version number on the terminal and
+exits.
+
+== COMMANDS
+
+This section describes each of the commands available within the *chronyc*
+program.
+
+=== System clock
+
+[[tracking]]*tracking*::
+The *tracking* command displays parameters about the system's clock
+performance. An example of the output is shown below.
++
+----
+Reference ID : 203.0.113.15 (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
+----
++
+The fields are explained as follows:
++
+*Reference ID*:::
+This is the reference ID and name (or IP address) of the server to which the
+computer is currently synchronised. For IPv4 addresses, the reference ID is
+equal to the address and for IPv6 addresses it's the first 32 bits of the MD5
+sum of the address.
++
+If it is _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
+<<local,*local*>> command in *chronyc*, or the
+<<chrony.conf.adoc#local,*local*>> directive in the configuration file.
+*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. _foo.example.net_ is a
+stratum-2 and is synchronised from a stratum-1).
+*Ref time*:::
+This is the time (UTC) at which the last measurement from the reference
+source was processed.
+*System time*:::
+In normal operation, *chronyd* by default 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)
+will be different from *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.
+*Last offset*:::
+This is the estimated local offset on the last clock update.
+*RMS offset*:::
+This is a long-term average of the offset value.
+*Frequency*:::
+The '`frequency`' is the rate by which the system's clock would be would be
+wrong if *chronyd* was not correcting it. It is expressed in ppm (parts per
+million). For example, a value of 1 ppm 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 would gain about 30 seconds per day if it wasn't corrected!
+*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.
+*Skew*:::
+This is the estimated error bound on the the frequency.
+*Root delay*:::
+This is the total of the network path delays to the stratum-1 computer from
+which the computer is ultimately synchronised.
+*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
++
+----
+clock_error <= root_dispersion + (0.5 * |root_delay|)
+----
+*Update interval*:::
+This is the interval between the last two clock updates.
+*Leap status*:::
+This is the leap status, which can be _Normal_, _Insert second_, _Delete
+second_ or _Not synchronised_.
+
+[[makestep]]*makestep*::
+*makestep* _threshold_ _limit_::
+Normally *chronyd* will cause the system to gradually correct any time offset,
+by slowing down or speeding up the clock as required. In certain situations,
+the system clock may be so far adrift that this slewing process would take a
+very long time to correct the system clock.
++
+The *makestep* command can be used in this situation. There are two forms of
+the command. The first form has no parameters. It tells *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
+<<chrony.conf.adoc#makestep,*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 <<burst,*burst*>>
+command to quickly make a new measurement and correct the clock by stepping if
+needed, without waiting for *chronyd* to complete the measurement and update
+the clock.
++
+----
+makestep 0.1 1
+burst 1/2
+----
++
+BE WARNED - certain software will be seriously affected by such jumps to the
+system time. (That is the reason why *chronyd* uses slewing normally.)
+
+[[maxupdateskew]]*maxupdateskew* _skew-in-ppm_::
+This command has the same effect as the
+<<chrony.conf.adoc#maxupdateskew,*maxupdateskew*>> directive in the
+configuration file.
+
+[[waitsync]]*waitsync* [_max-tries_ [_max-correction_ [_max-skew_ [_interval_]]]]::
+The *waitsync* command waits for *chronyd* to synchronise.
++
+Up to four optional arguments can be specified. The first is the maximum number
+of tries 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
+<<tracking,*tracking*>> command in the *System time* and *Skew* fields. If not
+specified or zero, the value will not be checked.
++
+The fourth argument is the interval specified in seconds in which the check is
+repeated. The interval is 10 seconds by default.
++
+An example is
++
+----
+waitsync 60 0.01
+----
++
+which will wait up to about 10 minutes (60 times 10 seconds) for *chronyd* to
+synchronise to a source and the remaining correction to be less than 10
+milliseconds.
+
+=== Time sources
+
+[[sources]]*sources* [*-v*]::
+This command displays information about the current time sources that *chronyd*
+is accessing.
++
+The optional argument *-v* can be specified, meaning _verbose_. In this case,
+extra caption lines are shown as a reminder of the meanings of the columns.
++
+----
+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
+----
++
+The columns are as follows:
++
+*M*:::
+This indicates the mode of the source. _^_ means a server, _=_ means a peer
+and _#_ indicates a locally connected reference clock.
+*S*:::
+This column indicates the state of the source.
+* _*_ indicates the source to which *chronyd* is currently synchronised.
+* _+_ indicates acceptable sources which are combined with the selected
+ source.
+* _-_ indicates acceptable sources which are excluded by the combining
+ algorithm.
+* _?_ indicates sources to which connectivity has been lost or whose packets
+ don't pass all tests. It's also shown at start-up, until at least 3 samples
+ have been gathered from it.
+* _x_ indicates a clock which *chronyd* thinks is a falseticker (i.e. its
+ time is inconsistent with a majority of other sources).
+* _~_ indicates a source whose time appears to have too much variability.
+*Name/IP address*:::
+This shows the name or the IP address of the source, or refid for reference
+clocks.
+*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.
+*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. *chronyd* automatically varies
+the polling rate in response to prevailing conditions.
+*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.
+*LastRx*:::
+This column shows how long ago the last sample was received from the source.
+This is normally in seconds. The letters _m_, _h_, _d_ or _y_ indicate
+minutes, hours, days or years.
+*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 _ns_ (indicating nanoseconds), _us_
+(indicating microseconds), _ms_ (indicating milliseconds), or _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 _+/-_ indicator shows the margin of error in
+the measurement. Positive offsets indicate that the local clock is fast of
+the source.
+
+[[sourcestats]]*sourcestats* [*-v*]::
+The *sourcestats* command displays information about the drift rate and offset
+estimation process for each of the sources currently being examined by
+*chronyd*.
++
+The optional argument *-v* can be specified, meaning _verbose_. In this case,
+extra caption lines are shown as a reminder of the meanings of the columns.
++
+An example report is
++
+----
+210 Number of sources = 1
+Name/IP Address NP NR Span Frequency Freq Skew Offset Std Dev
+===============================================================================
+foo.example.net 11 5 46m -0.001 0.045 1us 25us
+----
++
+The columns are as follows:
++
+*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.
+*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.
+*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, *chronyd* discards older
+samples and re-runs the regression until the number of runs becomes
+acceptable.
+*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.
+*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.
+*Freq Skew*:::
+This is the estimated error bounds on *Freq* (again in parts per million).
+*Offset*:::
+This is the estimated offset of the source.
+*Std Dev*:::
+This is the estimated sample standard deviation.
+
+[[reselect]]*reselect*::
+To avoid excessive switching between sources, *chronyd* may stay synchronised
+to a source even when it is not currently the best one among the available
+sources.
++
+The *reselect* command can be used to force *chronyd* to reselect the best
+synchronisation source.
+
+[[reselectdist]]*reselectdist* _distance_::
+The *reselectdist* command sets the reselection distance. It is equivalent to
+the <<chrony.conf.adoc#reselectdist,*reselectdist*>> directive in the
+configuration file.
+
+=== NTP sources
+
+[[activity]]*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
+*activity* command may be useful for detecting when all of them have entered
+the offline state after the network link has been disconnected.
++
+The report shows the number of servers/peers in 5 states:
++
+*online*:::
+the server/peer is currently online (i.e. assumed by chronyd to be reachable)
+*offline*:::
+the server/peer is currently offline (i.e. assumed by chronyd to be
+unreachable, and no measurements from it will be attempted.)
+*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.
+*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.
+*unresolved*:::
+the name of the server/peer wasn't resolved to an address yet; this server is
+not visible in the *sources* and *sourcestats* reports.
+
+[[add_peer]]*add peer* _address_ [_option_]...::
+The *add peer* command allows a new NTP peer to be added whilst
+*chronyd* is running.
++
+Following the words *add peer*, the syntax of the following
+parameters and options is similar to that for the
+<<chrony.conf.adoc#peer,*peer*>> directive in the configuration file.
+The following peer options can be set in the command: *port*, *minpoll*,
+*maxpoll*, *presend*, *maxdelayratio*, *maxdelay*, *key*.
++
+An example of using this command is shown below.
++
+----
+add peer foo.example.net minpoll 6 maxpoll 10 key 25
+----
+
+[[add_server]]*add server* _address_ [_option_]...::
+The *add server* command allows a new NTP server to be added whilst
+*chronyd* is running.
++
+Following the words *add server*, the syntax of the following parameters and
+options is similar to that for the <<chrony.conf.adoc#server,*server*>>
+directive in the configuration file.
+The following server options can be set in the command: *port*, *minpoll*,
+*maxpoll*, *presend*, *maxdelayratio*, *maxdelay*, *key*.
++
+An example of using this command is shown below.
++
+----
+add server foo.example.net minpoll 6 maxpoll 10 key 25
+----
+
+[[delete]]*delete* _address_::
+The *delete* command allows an NTP server or peer to be removed
+from the current set of sources.
+
+[[burst]]
+*burst* _good_/_max_ [_mask_/_masked-address_]::
+*burst* _good_/_max_ [_masked-address_/_masked-bits_]::
+*burst* _good_/_max_ [_address_]::
+The *burst* command tells *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, *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. (A source can be switched between the online
+and offline states with the <<online,*online*>> and <<offline,*offline*>>
+commands.)
++
+The _mask_ and _masked-address_ arguments are optional, in which case *chronyd*
+will initiate a burst for all of its currently defined sources.
++
+The arguments have the following meaning and format:
++
+_good_:::
+This defines the number of good measurements that *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 *chronyd* to reject measurements that are likely to be bogus.)
+_max_:::
+This defines the maximum number of measurements that *chronyd* will attempt
+to make, even if the required number of good measurements has not been
+obtained.
+_mask_:::
+This is an IP address with which the IP address of each of *chronyd*'s
+sources is to be masked.
+_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.
+_masked-bits_:::
+This can be used with _masked-address_ for CIDR notation, which is a shorter
+alternative to the form with mask.
+_address_:::
+This is an IP address or a hostname. The burst command is applied only to
+that source.
+::
++
+If no _mask_ or _masked-address_ arguments are provided, every source will be
+matched.
++
+An example of the two-argument form of the command is
++
+----
+burst 2/10
+----
++
+This will cause *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
++
+----
+burst 2/10 255.255.0.0/1.2.0.0
+burst 2/10 2001:db8:789a::/48
+----
++
+In the first case, the two out of ten sampling will only be applied to sources
+whose IPv4 addresses are of the form _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 _2001:db8:789a_.
++
+Example of the three-argument form of the command is
++
+----
+burst 2/10 foo.example.net
+----
+
+[[maxdelay]]*maxdelay* _address_ _delay_::
+This allows the *maxdelay* option for one of the sources to be modified, in the
+same way as specifying the *maxdelay* option for the
+<<chrony.conf.adoc#server,*server*>> directive in the configuration file.
+
+[[maxdelaydevratio]]*maxdelaydevratio* _address_ _ratio_::
+This allows the *maxdelaydevratio* option for one of the sources to be
+modified, in the same way as specifying the *maxdelaydevratio* option for the
+<<chrony.conf.adoc#server,*server*>> directive in the configuration file.
+
+[[maxdelayratio]]*maxdelayratio* _address_ _ratio_::
+This allows the *maxdelayratio* option for one of the sources to be modified,
+in the same way as specifying the *maxdelayratio* option for the
+<<chrony.conf.adoc#server,*server*>> directive in the configuration file.
+
+[[maxpoll]]*maxpoll* _address_ _maxpoll_::
+The *maxpoll* command is used to modify the maximum polling interval for one of
+the current set of sources. It is equivalent to the *maxpoll* option in the
+<<chrony.conf.adoc#server,*server*>> directive in the configuration file.
++
+Note that the new maximum polling interval only takes effect after the next
+measurement has been made.
+
+[[minpoll]]*minpoll* _address_ _minpoll_::
+The *minpoll* command is used to modify the minimum polling interval for one of
+the current set of sources. It is equivalent to the *minpoll* option in the
+<<chrony.conf.adoc#server,*server*>> directive in the configuration file.
++
+Note that the new minimum polling interval only takes effect after the next
+measurement has been made.
+
+[[minstratum]]*minstratum* _address_ _minstratum_::
+The *minstratum* command is used to modify the minimum stratum for one of the
+current set of sources. It is equivalent to the *minstratum* option in the
+<<chrony.conf.adoc#server,*server*>> directive in the configuration file.
+
+[[offline]]
+*offline* [_address_]::
+*offline* [_masked-address_/_masked-bits_]::
+*offline* [_mask_/_masked-address_]::
+The *offline* command is used to warn *chronyd* that the network connection to
+a particular host or hosts is about to be lost, e.g. on computers with
+intermittent connection to their time sources.
++
+Another case where *offline* could be used is where a computer serves time to a
+local group of computers, and has a permanent 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 *offline* and *online* commands can be used to achieve
+this.
++
+There are four forms of the *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.
++
+----
+offline
+offline 255.255.255.0/1.2.3.0
+offline 2001:db8:789a::/48
+offline foo.example.net
+----
++
+The second form means that the *offline* command is to be applied to any source
+whose IPv4 address is in the _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 _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
++
+----
+offline 0.0.0.0/0.0.0.0
+offline ::/0
+----
+
+[[online]]
+*online* [_address_]::
+*online* [_masked-address_/_masked-bits_]::
+*online* [_mask_/_masked-address_]::
+The *online* command is opposite in function to the <<offline,*offline*>>
+command. It is used to advise *chronyd* that network connectivity to a
+particular source or sources has been restored.
++
+The syntax is identical to that of the <<offline,*offline*>> command.
+
+[[polltarget]]*polltarget* _address_ _polltarget_::
+The *polltarget* command is used to modify the poll target for one of the
+current set of sources. It is equivalent to the *polltarget* option in the
+<<chrony.conf.adoc#server,*server*>> directive in the configuration file.
+
+[[refresh]]*refresh*::
+The *refresh* command can be used to force *chronyd* to resolve the names of
+configured sources to IP addresses again, e.g. after suspending and resuming
+the machine in a different network.
++
+Sources that stop responding will be replaced with newly resolved addresses
+automatically after 8 polling intervals, but this command may still be useful
+to replace them immediately and not wait until they are marked as unreachable.
+
+=== Manual time input
+
+[[manual]]
+*manual* *on*::
+*manual* *off*::
+*manual* *delete* _index_::
+*manual* *list*::
+*manual* *reset*::
+The manual command enables and disables use of the <<settime,*settime*>>
+command, and is used to modify the behaviour of the manual clock driver.
++
+The *on* form of the command enables use of the *settime* command.
++
+The *off* form of the command disables use of the *settime* command.
++
+The *list* form of the command lists all the samples currently stored in
+*chronyd*. The output is illustrated below.
++
+----
+210 n_samples = 1
+# Date Time(UTC) Slewed Original Residual
+====================================================
+ 0 27Jan99 22:09:20 0.00 0.97 0.00
+----
++
+The columns as as follows:
++
+. The sample index (used for the *manual delete* command).
+. The date and time of the sample.
+. The system clock error when the timestamp was entered, adjusted to allow
+ for changes made to the system clock since.
+. The system clock error when the timestamp was entered, as it originally was
+ (without allowing for changes to the system clock since).
+. The regression residual at this point, in seconds. This allows '`outliers`'
+ to be easily spotted, so that they can be deleted using the *manual delete*
+ command.
+::
++
+The *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 *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 s/he has entered a very poor
+timestamp.
++
+The *reset* form of the command deletes all samples at once. The system clock
+is left running as it was before the command was entered.
+
+[[settime]]*settime* _time_::
+The *settime* command allows the current time to be entered manually, if this
+option has been configured into *chronyd*. (It may be configured either with
+the <<chrony.conf.adoc#manual,*manual*>> directive in the configuration file,
+or with the <<manual,*manual*>> command of *chronyc*.)
++
+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 *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 *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
+<<manual,*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 _getdate_ algorithm. Consequently, you
+can only specify time to the nearest second.
++
+Examples of inputs that are valid are shown below.
++
+----
+settime 16:30
+settime 16:30:05
+settime Nov 21, 2015 16:30:05
+----
++
+For a full description of getdate, get hold of the getdate documentation
+(bundled, for example, with the source for GNU tar).
+
+=== NTP access
+
+[[accheck]]*accheck* _address_::
+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:
++
+----
+accheck foo.example.net
+accheck 1.2.3.4
+accheck 2001:db8::1
+----
++
+This command can be used to examine the effect of a series of *allow*, *allow
+all*, *deny* and *deny all* commands specified either via *chronyc*, or in
+*chronyd*'s configuration file.
+
+[[clients]]*clients*::
+This command shows a list of clients that have accessed the server, through
+either the NTP or command/monitoring ports. It doesn't include accesses over
+the Unix domain comamnd socket. There are no arguments.
++
+An example of the output is
++
+----
+Hostname NTP Drop Int IntL Last Cmd Drop Int Last
+===============================================================================
+localhost 2 0 2 - 133 15 0 -1 7
+foo.example.net 12 0 6 - 23 0 0 - -
+----
++
+Each row shows the data for a single host. Only hosts that have passed the host
+access checks (set with the <<allow,*allow*>>, <<deny,*deny*>>,
+<<cmdallow,*cmdallow*>> and <<cmddeny,*cmddeny*>> commands or configuration
+file directives) are logged. The intervals are displayed as a power of 2 in
+seconds.
++
+The columns are as follows:
++
+. The hostname of the client.
+. The number of NTP packets received from the client.
+. The number of NTP packets dropped to limit the response rate.
+. The average interval between NTP packets.
+. The average interval between NTP packets after limiting the response rate.
+. Time since the last NTP packet was received
+. The number of command packets received from the client.
+. The number of command packets dropped to limit the response rate.
+. The average interval between command packets.
+. Time since the last command packet was received.
+
+[[serverstats]]*serverstats*::
+The *serverstats* command displays how many valid NTP and command requests
+*chronyd* as a server received from clients, how many of them were dropped to
+limit the response rate as configured by the
+<<chrony.conf.adoc#ratelimit,*ratelimit*>> and
+<<chrony.conf.adoc#cmdratelimit,*cmdratelimit*>> directives, and how many
+client log records were dropped due to the memory limit configured by the
+<<chrony.conf.adoc#clientloglimit,*clientloglimit*>> directive. An example of
+the output is shown below.
++
+----
+NTP packets received : 1598
+NTP packets dropped : 8
+Command packets received : 19
+Command packets dropped : 0
+Client log records dropped : 0
+----
+
+[[allow]]*allow* [*all*] [_subnet_]::
+The effect of the allow command is identical to the
+<<chrony.conf.adoc#allow,*allow*>> directive in the configuration file.
++
+The syntax is illustrated in the following examples:
++
+----
+allow foo.example.net
+allow all 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
+allow all
+----
+
+[[deny]]*deny* [*all*] [_subnet_]::
+The effect of the allow command is identical to the
+<<chrony.conf.adoc#deny,*deny*>> directive in the configuration file.
++
+The syntax is illustrated in the following examples:
++
+----
+deny foo.example.net
+deny all 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
+deny all
+----
+
+[[local]]
+*local* *stratum* _stratum_::
+*local* *off*::
+The *local* command allows *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 *local*
+command is somewhat equivalent to the <<chrony.conf.adoc#local,*local*>>
+directive in the configuration file.
++
+The first form enables the local reference mode on the host, and sets the
+stratum at which it should claim to be synchronised.
++
+The second form disables the local reference mode.
+
+[[smoothing]]*smoothing*::
+The *smoothing* command displays the current state of the NTP server time
+smoothing, which can be enabled with the
+<<chrony.conf.adoc#smoothtime,*smoothtime*>> directive. An example of the
+output is shown below.
++
+----
+Active : Yes
+Offset : +1.000268817 seconds
+Frequency : -0.142859 ppm
+Wander : -0.010000 ppm per second
+Last update : 17.8 seconds ago
+Remaining time : 19988.4 seconds
+----
++
+The fields are explained as follows:
++
+*Active*:::
+This shows if the server time smoothing is currently active. Possible values
+are _Yes_ and _No_. If the *leaponly* option is included in the *smoothtime*
+directive, _(leap second only)_ will be shown on the line.
+*Offset*:::
+This is the current offset applied to the time sent to NTP clients. Positive
+value means the clients are getting time that's ahead of true time.
+*Frequency*:::
+The current frequency offset of the served time. Negative value means the
+time observed by clients is running slower than true time.
+*Wander*:::
+The current frequency wander of the served time. Negative value means the
+time observed by clients is slowing down.
+*Last update*:::
+This field shows how long ago was the time smoothing process updated, e.g.
+*chronyd* accumulated a new measurement.
+*Remaining time*:::
+The time it would take for the smoothing process to get to zero offset and
+frequency if there were no more updates.
+
+[[smoothtime]]
+*smoothtime* *activate*::
+*smoothtime* *reset*::
+The *smoothtime* command can be used to activate or reset the server time
+smoothing process if it is configured with the
+<<chrony.conf.adoc#smoothtime,*smoothtime*>> directive.
+
+=== Monitoring access
+
+[[cmdaccheck]]*cmdaccheck* _address_::
+This command is similar to the <<accheck,*accheck*>> command, except that it is
+used to check whether monitoring access is permitted from a named host.
++
+Examples of use are as follows:
++
+----
+cmdaccheck foo.example.net
+cmdaccheck 1.2.3.4
+cmdaccheck 2001:db8::1
+----
+
+[[cmdallow]]*cmdallow* [*all*] [_subnet_]::
+This is similar to the <<allow,*allow*>> command, except that it is used to
+allow particular hosts or subnets to use *chronyc* to monitor with *chronyd* on
+the current host.
+
+[[cmddeny]]*cmddeny* [*all*] [_subnet_]::
+This is similar to the <<deny,*deny*>> command, except that it is used to allow
+particular hosts or subnets to use *chronyc* to monitor *chronyd* on the
+current host.
+
+=== Real-time clock (RTC)
+
+[[rtcdata]]*rtcdata*::
+The *rtcdata* command displays the current RTC parameters.
++
+An example output is shown below.
++
+----
+RTC ref time (GMT) : Sat May 30 07:25:56 2015
+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
+----
++
+The fields have the following meaning
++
+*RTC ref time (GMT)*:::
+This is the RTC reading the last time its error was measured.
+*Number of samples*:::
+This is the number of previous measurements being used to determine the RTC
+gain/loss rate.
+*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.
+*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.
+*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 <<trimrtc,*trimrtc*>> command to bring the
+RTC into line with the system clock. (Note, a large error will not affect
+*chronyd*'s operation, unless it becomes so big as to start causing rounding
+errors.)
+*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.
+
+[[trimrtc]]*trimrtc*::
+The *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 command takes no arguments. It performs the following steps (if the RTC is
+more than 1 second away from the system clock):
++
+. Remember the currently estimated gain/loss rate of the RTC and flush the
+ previous measurements.
+. Step the real-time clock to bring it within a second of the system clock.
+. 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).
+. Save the RTC parameters to the RTC file (specified with the
+ <<chrony.conf.adoc#rtcfile,*rtcfile*>> directive in the configuration file).
+::
++
+The last step is done as a precaution against the computer suffering a power
+failure before either the daemon exits or the <<writertc,*writertc*>> command
+is issued.
++
+*chronyd* will still work perfectly well both whilst operating and across
+machine reboots even if the *trimrtc* command is never used (and the RTC is
+allowed to drift away from true time). The *trimrtc* command is provided as a
+method by which it can be corrected, in a manner compatible with *chronyd*
+using it to maintain accurate time across machine reboots.
++
+The *trimrtc* command can be executed automatically by *chronyd* with the
+<<chrony.conf.adoc#rtcautotrim,*rtcautotrim*>> directive in the configuration
+file.
+
+[[writertc]]*writertc*::
+The *writertc* command writes the currently estimated error and gain/loss rate
+parameters for the RTC to the RTC file (specified with the
+<<chrony.conf.adoc#rtcfile,*rtcfile*>> directive). This information is also
+written automatically when *chronyd* is killed (by the SIGHUP, SIGINT, SIGQUIT
+or SIGTERM signals) or when the <<trimrtc,*trimrtc*>> command is issued.
+
+=== Other daemon commands
+
+[[cyclelogs]]*cyclelogs*::
+The *cyclelogs* command causes all of *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.
++
+----
+# mv /var/log/chrony/measurements.log /var/log/chrony/measurements1.log
+# chronyc 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
+----
+
+[[dump]]*dump*::
+The *dump* command causes *chronyd* to write its current history of
+measurements for each of its sources to dump files, either for inspection or to
+support the *-r* option when *chronyd* is restarted.
++
+The *dump* command is somewhat equivalent to the
+<<chrony.conf.adoc#dumponexit,*dumponexit*>> directive in the configuration
+file.
++
+To use the *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 with the <<chrony.conf.adoc#dumpdir,*dumpdir*>>
+directive.
+
+=== Client commands
+
+[[dns]]*dns* _option_::
+The *dns* command configures how are hostnames and IP addresses resolved in
+*chronyc*. IP addresses can be resolved to hostnames when printing results of
+<<sources,*sources*>>, <<sourcestats,*sourcestats*>>, <<tracking,*tracking*>>
+and <<clients,*clients*>> commands. Hostnames are resolved in commands that
+take an address as argument.
++
+There are five options:
++
+*dns -n*:::
+Disables resolving IP addresses to hostnames. Raw IP addresses will be
+displayed.
+*dns +n*:::
+Enables resolving IP addresses to hostnames. This is the default unless
+*chronyc* was started with *-n* option.
+*dns -4*:::
+Resolves hostnames only to IPv4 addresses.
+*dns -6*:::
+Resolves hostnames only to IPv6 addresses.
+*dns -46*:::
+Resolves hostnames to both address families. This is the default behaviour
+unless *chronyc* was started with the *-4* or *-6* option.
+
+[[timeout]]*timeout* _timeout_::
+The *timeout* command sets the initial timeout for *chronyc* requests in
+milliseconds. If no response is received from *chronyd*, the timeout is doubled
+and the request is resent. The maximum number of retries is configured with the
+<<retries,*retries*>> command.
++
+By default, the timeout is 1000 milliseconds.
+
+[[retries]]*retries* _retries_::
+The *retries* command sets the maximum number of retries for *chronyc* requests
+before giving up. The response timeout is controlled by the
+<<timeout,*timeout*>> command.
++
+The default is 2.
+
+[[keygen]]*keygen* [_id_ [_type_ [_bits_]]]::
+The *keygen* command generates a key that can be added to the
+key file (specified with the <<chrony.conf.adoc#keyfile,*keyfile*>> directive)
+to allow NTP authentication between server and client, or peers. The key is
+generated from the _/dev/urandom_ device and it's printed to standard output.
++
+The command has three optional arguments. The first argument is the key number
+(by default 1), which will be specified with the *key* option of the *server*
+or *peer* directives in the configuration file. The second argument is the hash
+function (by default SHA1 or MD5 if SHA1 is not available) and the third
+argument is the number of bits the key should have, between 80 and 4096 bits
+(by default 160 bits).
++
+An example is
++
+----
+keygen 73 SHA1 256
+----
++
+which generates a 256-bit SHA-1 key with number 73. The printed line would
+then be securely transferred and added to the key files on both server and
+client, or peers.
+
+[[exit]]*exit*::
+[[quit]]*quit*::
+The *exit* and *quit* commands exit from *chronyc* and return the user to the shell.
+
+[[help]]*help*::
+The *help* command displays a summary of the commands and their arguments.
+
+== SEE ALSO
+
+<<chrony.conf.adoc#,*chrony.conf(5)*>>, <<chronyd.adoc#,*chronyd(8)*>>
+
+== BUGS
+
+For instructions on how to report bugs, please visit
+http://chrony.tuxfamily.org/.
+
+== AUTHORS
+
+chrony was written by Richard Curnow, Miroslav Lichvar and others.
projects / thirdparty / chrony.git / commitdiff
