diff --git a/Makefile.in b/Makefile.in index c87f67f..b8fde5e 100644 --- a/Makefile.in +++ b/Makefile.in @@ -24,9 +24,6 @@ SYSCONFDIR=@SYSCONFDIR@ BINDIR=@BINDIR@ SBINDIR=@SBINDIR@ -MANDIR=@MANDIR@ -INFODIR=@INFODIR@ -DOCDIR=@DOCDIR@ LOCALSTATEDIR=@LOCALSTATEDIR@ CHRONYVARDIR=@CHRONYVARDIR@ @@ -75,10 +72,10 @@ $(HASH_OBJ) : $(patsubst %.o,%.c,$(HASH_OBJ)) distclean : clean -rm -f .DS_Store -rm -f Makefile - -rm -f chrony.conf.5 chrony.texi chronyc.1 chronyd.8 + $(MAKE) -C doc distclean clean : - -rm -f *.o *.s chronyc chronyd core *~ chrony.info chrony.html chrony.txt + -rm -f *.o *.s chronyc chronyd core *~ -rm -rf .deps -rm -rf *.dSYM @@ -96,9 +93,6 @@ install: chronyd chronyc [ -d $(DESTDIR)$(SYSCONFDIR) ] || mkdir -p $(DESTDIR)$(SYSCONFDIR) [ -d $(DESTDIR)$(SBINDIR) ] || mkdir -p $(DESTDIR)$(SBINDIR) [ -d $(DESTDIR)$(BINDIR) ] || mkdir -p $(DESTDIR)$(BINDIR) - [ -d $(DESTDIR)$(MANDIR)/man1 ] || mkdir -p $(DESTDIR)$(MANDIR)/man1 - [ -d $(DESTDIR)$(MANDIR)/man5 ] || mkdir -p $(DESTDIR)$(MANDIR)/man5 - [ -d $(DESTDIR)$(MANDIR)/man8 ] || mkdir -p $(DESTDIR)$(MANDIR)/man8 [ -d $(DESTDIR)$(CHRONYVARDIR) ] || mkdir -p $(DESTDIR)$(CHRONYVARDIR) if [ -f $(DESTDIR)$(SBINDIR)/chronyd ]; then rm -f $(DESTDIR)$(SBINDIR)/chronyd ; fi if [ -f $(DESTDIR)$(BINDIR)/chronyc ]; then rm -f $(DESTDIR)$(BINDIR)/chronyc ; fi @@ -106,12 +100,13 @@ install: chronyd chronyc chmod 755 $(DESTDIR)$(SBINDIR)/chronyd cp chronyc $(DESTDIR)$(BINDIR)/chronyc chmod 755 $(DESTDIR)$(BINDIR)/chronyc - cp chronyc.1 $(DESTDIR)$(MANDIR)/man1 - chmod 644 $(DESTDIR)$(MANDIR)/man1/chronyc.1 - cp chronyd.8 $(DESTDIR)$(MANDIR)/man8 - chmod 644 $(DESTDIR)$(MANDIR)/man8/chronyd.8 - cp chrony.conf.5 $(DESTDIR)$(MANDIR)/man5 - chmod 644 $(DESTDIR)$(MANDIR)/man5/chrony.conf.5 + $(MAKE) -C doc install + +docs : + $(MAKE) -C doc docs + +install-docs : + $(MAKE) -C doc install-docs %.o : %.c $(CC) $(CFLAGS) $(CPPFLAGS) -c $< @@ -123,28 +118,6 @@ check : chronyd chronyc $(MAKE) -C test/unit check cd test/simulation && ./run -install-docs : docs - [ -d $(DESTDIR)$(DOCDIR) ] || mkdir -p $(DESTDIR)$(DOCDIR) - cp chrony.txt $(DESTDIR)$(DOCDIR)/chrony.txt - chmod 644 $(DESTDIR)$(DOCDIR)/chrony.txt - cp chrony.html $(DESTDIR)$(DOCDIR)/chrony.html - chmod 644 $(DESTDIR)$(DOCDIR)/chrony.html - [ -d $(DESTDIR)$(INFODIR) ] || mkdir -p $(DESTDIR)$(INFODIR) - cp chrony.info* $(DESTDIR)$(INFODIR) - chmod 644 $(DESTDIR)$(INFODIR)/chrony.info* - -docs : chrony.txt chrony.html chrony.info - -chrony.txt : chrony.texi - makeinfo --no-headers --number-sections -o chrony.txt chrony.texi - -chrony.html : chrony.texi - command -v texi2html > /dev/null 2>&1 && texi2html chrony.texi || \ - makeinfo --no-split --html --number-sections -o chrony.html chrony.texi - -chrony.info : chrony.texi - makeinfo chrony.texi - Makefile : Makefile.in configure @echo @echo Makefile needs to be regenerated, run ./configure diff --git a/README b/README index d343d2a..1855898 100644 --- a/README +++ b/README @@ -84,6 +84,12 @@ chrony-dev-request@chrony.tuxfamily.org as applicable. +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! + License ======= @@ -105,6 +111,10 @@ Miroslav Lichvar Acknowledgements ================ +In writing the 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 the details of the protocol. + The following people have provided patches and other major contributions to the program : diff --git a/chrony.conf.5.in b/chrony.conf.5.in deleted file mode 100644 index 92ae6fd..0000000 --- a/chrony.conf.5.in +++ /dev/null @@ -1,67 +0,0 @@ -.TH chrony.conf 5 "@MAN_DATE@" "chrony @VERSION@" "Configuration Files" -.SH NAME -chrony.conf \- chronyd configuration file - -.SH SYNOPSIS -.B @SYSCONFDIR@/chrony.conf - -.SH DESCRIPTION -\fIchrony\fR is a pair of programs for maintaining the accuracy of computer -clocks. \fIchronyd\fR is a background daemon program that can be started at -boot time. - -Assuming that you have found some servers, you need to set up a -configuration file to run \fIchrony\fR. The (compiled-in) default location -for this file is \fB@SYSCONFDIR@/chrony.conf\fR. Assuming that your NTP -servers are called `foo.example.net', `bar.example.net' and `baz.example.net', -your \fBchrony.conf\fR file could contain as a minimum - -.EX - server foo.example.net - server bar.example.net - server baz.example.net -.EE - -However, you will probably want to include some of the other directives -described in detail in the documentation supplied with the distribution -(\fIchrony.txt\fR and \fIchrony.texi\fR). The following directives may be -particularly useful : `driftfile', `makestep', `rtcsync'. Also, the `iburst' -server option is useful to speed up the initial synchronization. The smallest -useful configuration file would look something like - -.EX - server foo.example.net iburst - server bar.example.net iburst - server baz.example.net iburst - driftfile @CHRONYVARDIR@/drift - makestep 1.0 3 - rtcsync -.EE - -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' directive -instead of multiple `server' directives. The configuration file could in this -case look like - -.EX - pool pool.ntp.org iburst - driftfile @CHRONYVARDIR@/drift - makestep 1.0 3 - rtcsync -.EE - -.SH "SEE ALSO" -.BR chronyc(1), -.BR chronyd(8) - -.I http://chrony.tuxfamily.org/ - -.SH AUTHOR -Richard Curnow - -This man-page was written by Jan Schaumann as part of "The Missing -Man Pages Project". Please see \fIhttp://www.netmeister.org/misc/m2p2/index.html\fR -for details. - -The complete chrony documentation is supplied in texinfo format. - diff --git a/chrony.texi.in b/chrony.texi.in deleted file mode 100644 index 099fc80..0000000 --- a/chrony.texi.in +++ /dev/null @@ -1,5216 +0,0 @@ -\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 -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 -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 -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 -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 -@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 -@end example - -Typical values for 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 -@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 -@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 -@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 -@end example - -Typical values for 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 -@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 -@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 -@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 -@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 -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 -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 -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 / [/] -burst / [/] -burst / [
] -@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 -@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 -@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 -@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 -@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. - - - Copyright (C) - - 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. - - , 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 - diff --git a/chronyc.1.in b/chronyc.1.in deleted file mode 100644 index d3846c2..0000000 --- a/chronyc.1.in +++ /dev/null @@ -1,74 +0,0 @@ -.TH CHRONYC 1 "@MAN_DATE@" "chrony @VERSION@" "User's Manual" -.SH NAME -chronyc \- command-line interface for chronyd - -.SH SYNOPSIS -.B chronyc -[\fIOPTIONS\fR] - -.SH DESCRIPTION -\fIchrony\fR is a pair of programs for maintaining the accuracy of computer -clocks. - -\fBchronyc\fR is a command-line interface program which can be used to -monitor \fIchronyd\fR's performance and to change various operating -parameters whilst it is running. - -.SH USAGE -A detailed description of all commands supported by \fBchronyc\fR is available -via the documentation supplied with the distribution (\fIchrony.txt\fR and -\fIchrony.texi\fR). - -.SH OPTIONS -A summary of the options supported by \fBchronyc\fR is included below. - -.TP -\fB\-h\fR \fIhostname\fR -specify hostname or comma-separated list of addresses -(default @CHRONYSOCKDIR@/chronyd.sock,127.0.0.1,::1) -.TP -\fB\-p\fR \fIport-number\fR -specify port-number -.TP -\fB\-n\fR -display raw IP addresses (don't attempt to look up hostnames) -.TP -\fB\-d\fR -print debugging messages (if compiled with debugging support) -.TP -\fB\-4\fR -resolve hostnames only to IPv4 addresses -.TP -\fB\-6\fR -resolve hostnames only to IPv6 addresses -.TP -\fB\-m\fR -allow multiple commands to be specified on the command line. Each argument -will be interpreted as a whole command. -.TP -\fB\-f\fR \fIconf-file\fR -this option is ignored and is provided only for compatibility. -.TP -\fB\-a\fR -this option is ignored and is provided only for compatibility. -.TP -\fIcommand\fR -specify command. If no command is given, chronyc will read commands -interactively. - -.SH BUGS -To report bugs, please visit \fIhttp://chrony.tuxfamily.org\fR - -.SH "SEE ALSO" -.BR chronyd(8) - -.I http://chrony.tuxfamily.org/ - -.SH AUTHOR -Richard Curnow - -This man-page was written by Jan Schaumann as part of "The Missing -Man Pages Project". Please see \fIhttp://www.netmeister.org/misc/m2p2/index.html\fR -for details. - -The complete chrony documentation is supplied in texinfo format. diff --git a/chronyd.8.in b/chronyd.8.in deleted file mode 100644 index 0cd06a5..0000000 --- a/chronyd.8.in +++ /dev/null @@ -1,166 +0,0 @@ -.TH CHRONYD 8 "@MAN_DATE@" "chrony @VERSION@" "System Administration" -.SH NAME -chronyd \- chrony background daemon - -.SH SYNOPSIS -.B chronyd -[\fIOPTIONS\fR] [\fIconfiguration commands\fR] - -.SH DESCRIPTION -\fIchrony\fR is a pair of programs for maintaining the accuracy of computer -clocks. \fBchronyd\fR is a background daemon program that can be started at boot -time. - -\fBchronyd\fR is a daemon which runs in background on the -system. It obtains measurements (e.g. via the network) of the -system's offset relative to other systems, and adjusts the system -time accordingly. For isolated systems, the user can periodically -enter the correct time by hand (using \fIchronyc\fR). In either case, -\fBchronyd\fR determines the rate at which the computer -gains or loses time, and compensates for this. - -.SH USAGE -\fBchronyd\fR is usually started at boot-time and requires superuser -privileges. - -If \fBchronyd\fR has been installed to its default location -\fI@SBINDIR@/chronyd\fR, starting it is simply a matter of entering the -command: - -\fI@SBINDIR@/chronyd\fR - -Information messages and warnings will be logged to syslog. - -If no configuration commands are specified on the command line, -\fBchronyd\fR will read the commands from the configuration file -(default \fI@SYSCONFDIR@/chrony.conf\fR). - -.SH OPTIONS -A summary of the options supported by \fBchronyd\fR is included below. - -.TP -\fB\-P\fR \fIpriority\fR -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. -.TP -.B \-m -This option will lock chronyd into RAM so that it will never be paged out. -This mode is only supported on Linux. -.TP -.B \-n -When run in this mode, the program will not detach itself from the -terminal. -.TP -.B \-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 \fBchronyd\fR was compiled with debugging support, -this option can be used twice to print also debugging messages. -.TP -\fB\-f\fR \fIconf-file\fR -This option can be used to specify an alternate location for the -configuration file (default \fI@SYSCONFDIR@/chrony.conf\fR). -.TP -.B \-r -This option will reload sample histories for each of the servers being used. -These histories are created by using the \fIdump\fR command in \fIchronyc\fR, -or by setting the \fIdumponexit\fR directive in the configuration file. This -option is useful if you want to stop and restart \fBchronyd\fR 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 -\fBchronyd\fR's control (i.e. Linux, FreeBSD, NetBSD and Solaris). -.TP -.B \-R -When this option is used, the \fIinitstepslew\fR directive and the -\fImakestep\fR directive used with a positive limit will be ignored. This -option is useful when restarting \fBchronyd\fR and can be used in conjunction -with the \fB-r\fR option. -.TP -.B \-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 \fIdriftfile\fR -directive. Real-time clocks are supported only on Linux. - -If used in conjunction with the \fB-r\fR flag, \fBchronyd\fR will attempt -to preserve the old samples after setting the system clock from -the real time clock (RTC). This can be used to allow \fBchronyd\fR 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 \fBchronyd\fR 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 -\fBchronyd\fR was previously stopped. This is useful on computers that have no -RTC or the RTC is broken (e.g. it has no battery). -.TP -\fB\-u\fR \fIuser\fR -This option sets the name of the system user to which \fBchronyd\fR will switch -after start in order to drop root privileges. It overrides the \fBuser\fR -directive from the configuration file (default \fB@DEFAULT_USER@\fR). - -On Linux, \fBchronyd\fR needs to be compiled with support for the \fBlibcap\fR -library. On Mac OS X, FreeBSD, NetBSD and Solaris \fBchronyd\fR 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. -.TP -\fB\-F\fR \fIlevel\fR -This option configures a system call filter when \fBchronyd\fR 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 \fBchrony\fR is installed as the filter needs to -allow also system calls made from libraries that \fBchronyd\fR 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, -\fBchronyd\fR could be killed even in normal operation. -.TP -.B \-q -When run in this mode, chronyd will set the system clock once -and exit. It will not detach from the terminal. -.TP -.B \-Q -This option is similar to \fB\-q\fR, but it will only print the offset and -not correct the clock. -.TP -.B \-v -This option displays \fBchronyd\fR's version number to the terminal and exits -.TP -.B \-4 -Resolve hostnames only to IPv4 addresses and create only IPv4 sockets. -.TP -.B \-6 -Resolve hostnames only to IPv6 addresses and create only IPv6 sockets. - -.SH FILES -\fI@SYSCONFDIR@/chrony.conf\fR - -.SH BUGS -To report bugs, please visit \fIhttp://chrony.tuxfamily.org/\fR - -.SH "SEE ALSO" -\fBchronyd\fR is documented in detail in the documentation supplied with the -distribution (\fIchrony.txt\fR and \fIchrony.texi\fR). - -.BR chronyc(1), -.BR chrony.conf(5), -.BR hwclock(8), -.BR ntpd(8) - -.I http://chrony.tuxfamily.org/ - -.SH AUTHOR -Richard Curnow - -This man-page was written by Jan Schaumann as part -of "The Missing Man Pages Project". Please see -\fIhttp://www.netmeister.org/misc/m2p2/index.html\fR for details. - -The complete chrony documentation is supplied in texinfo format. - diff --git a/configure b/configure index 144e30d..cb1d139 100755 --- a/configure +++ b/configure @@ -111,7 +111,6 @@ Fine tuning of the installation directories: --bindir=DIR user executables [EPREFIX/bin] --sbindir=DIR system admin executables [EPREFIX/sbin] --datarootdir=DIR data root [PREFIX/share] - --infodir=DIR info documentation [DATAROOTDIR/info] --mandir=DIR man documentation [DATAROOTDIR/man] --docdir=DIR documentation root [DATAROOTDIR/doc/chrony] --localstatedir=DIR modifiable single-machine data [/var] @@ -261,9 +260,6 @@ do --datarootdir=* ) SETDATAROOTDIR=`echo $option | sed -e 's/^.*=//;'` ;; - --infodir=* ) - SETINFODIR=`echo $option | sed -e 's/^.*=//;'` - ;; --mandir=* ) SETMANDIR=`echo $option | sed -e 's/^.*=//;'` ;; @@ -797,11 +793,6 @@ if [ "x$SETDATAROOTDIR" != "x" ]; then DATAROOTDIR=$SETDATAROOTDIR fi -INFODIR=${DATAROOTDIR}/info -if [ "x$SETINFODIR" != "x" ]; then - INFODIR=$SETINFODIR -fi - MANDIR=${DATAROOTDIR}/man if [ "x$SETMANDIR" != "x" ]; then MANDIR=$SETMANDIR @@ -848,7 +839,7 @@ fi add_def CHRONY_VERSION "\"${CHRONY_VERSION}\"" -for f in Makefile test/unit/Makefile chrony.conf.5 chrony.texi chronyc.1 chronyd.8 +for f in Makefile doc/Makefile test/unit/Makefile do echo Creating $f sed -e "s%@EXTRA_OBJECTS@%${EXTRA_OBJECTS}%;\ @@ -867,7 +858,6 @@ do s%@SBINDIR@%${SBINDIR}%;\ s%@DOCDIR@%${DOCDIR}%;\ s%@MANDIR@%${MANDIR}%;\ - s%@INFODIR@%${INFODIR}%;\ s%@LOCALSTATEDIR@%${LOCALSTATEDIR}%;\ s%@CHRONYSOCKDIR@%${CHRONYSOCKDIR}%;\ s%@CHRONYVARDIR@%${CHRONYVARDIR}%;\ diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..d24f5a7 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,70 @@ +ADOC = asciidoctor +ADOC_FLAGS = +SED = sed +HTML_TO_TXT = w3m -dump -T text/html + +MAN_FILES = chrony.conf.man chronyc.man chronyd.man +TXT_FILES = faq.txt installation.txt +HTML_FILES = $(MAN_FILES:%.man=%.html) $(TXT_FILES:%.txt=%.html) +MAN_IN_FILES = $(MAN_FILES:%.man=%.man.in) + +SYSCONFDIR = @SYSCONFDIR@ +BINDIR = @BINDIR@ +SBINDIR = @SBINDIR@ +MANDIR = @MANDIR@ +DOCDIR = @DOCDIR@ +CHRONYSOCKDIR = @CHRONYSOCKDIR@ +CHRONYVARDIR = @CHRONYVARDIR@ +CHRONY_VERSION = @CHRONY_VERSION@ +DEFAULT_USER = @DEFAULT_USER@ +DEFAULT_HWCLOCK_FILE = @DEFAULT_HWCLOCK_FILE@ + +SED_COMMANDS = "s%\@SYSCONFDIR\@%$(SYSCONFDIR)%g;\ + s%\@BINDIR\@%$(BINDIR)%g;\ + s%\@SBINDIR\@%$(SBINDIR)%g;\ + s%\@CHRONY_VERSION\@%$(CHRONY_VERSION)%g;\ + s%\@DEFAULT_HWCLOCK_FILE\@%$(DEFAULT_HWCLOCK_FILE)%g;\ + s%\@DEFAULT_USER\@%$(DEFAULT_USER)%g;\ + s%\@CHRONYSOCKDIR\@%$(CHRONYSOCKDIR)%g;\ + s%\@CHRONYVARDIR\@%$(CHRONYVARDIR)%g;" + +man: $(MAN_FILES) $(MAN_IN_FILES) +html: $(HTML_FILES) +txt: $(TXT_FILES) +docs: man html + +%.html: %.adoc + $(ADOC) $(ADOC_FLAGS) -b html -o - $< | $(SED) -e $(SED_COMMANDS) > $@ + +%.man.in: %.adoc + $(ADOC) $(ADOC_FLAGS) -b manpage -o $@ $< + +%.man: %.man.in + $(SED) -e $(SED_COMMANDS) < $< > $@ + +%.txt: %.html + $(HTML_TO_TXT) < $< > $@ + +install: $(MAN_FILES) + [ -d $(DESTDIR)$(MANDIR)/man1 ] || mkdir -p $(DESTDIR)$(MANDIR)/man1 + [ -d $(DESTDIR)$(MANDIR)/man5 ] || mkdir -p $(DESTDIR)$(MANDIR)/man5 + [ -d $(DESTDIR)$(MANDIR)/man8 ] || mkdir -p $(DESTDIR)$(MANDIR)/man8 + cp chronyc.man $(DESTDIR)$(MANDIR)/man1/chronyc.1 + chmod 644 $(DESTDIR)$(MANDIR)/man1/chronyc.1 + cp chronyd.man $(DESTDIR)$(MANDIR)/man8/chronyd.8 + chmod 644 $(DESTDIR)$(MANDIR)/man8/chronyd.8 + cp chrony.conf.man $(DESTDIR)$(MANDIR)/man5/chrony.conf.5 + chmod 644 $(DESTDIR)$(MANDIR)/man5/chrony.conf.5 + +install-docs: $(HTML_FILES) + [ -d $(DESTDIR)$(DOCDIR) ] || mkdir -p $(DESTDIR)$(DOCDIR) + for f in $(HTML_FILES); do \ + cp $$f $(DESTDIR)$(DOCDIR); \ + chmod 644 $(DESTDIR)$(DOCDIR)/$$f; \ + done + +clean: distclean + rm -f $(MAN_IN_FILES) + +distclean: + rm -f $(MAN_FILES) $(TXT_FILES) $(HTML_FILES) diff --git a/doc/chrony.conf.adoc b/doc/chrony.conf.adoc new file mode 100644 index 0000000..8cca026 --- /dev/null +++ b/doc/chrony.conf.adoc @@ -0,0 +1,2020 @@ +// 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 <> 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 +<> 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 +<> directive. +*maxsamples* _samples_::: +Set the maximum number of samples kept for this source. This overrides the +<> 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 <> 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 <> command from *chronyc* +when disconnecting the network link. (It will still be necessary to use the +<> 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 <> +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 <> 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 <> +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 <> 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 <> 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 +<> and <> 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 <> 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 +<> directive. +*maxsamples* _samples_::: +Set the maximum number of samples kept for this source. This overrides the +<> directive. + +[[manual]]*manual*:: +The *manual* directive enables support at run-time for the +<> 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 <> 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 <> 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 +<> and <> +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 +<> 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 <> 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 <> and <> +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 <> and <> +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 <> +directive. The current remaining correction is shown in the +<> 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 +<> 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 <> 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 +<> 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 <> 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 <> 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 +<> command. ++ +Note, if the <> 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 <> 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 <> +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 <> 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 <> 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 +<> directive or the <> 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 +<> 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 <> +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 <> directive or the +<> command in *chronyc*. The process can be +reset without stepping the clock by the <> 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 <> +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 <> command, which is particularly useful when the clock is +synchronised only with manual input and the skew is always larger than the +threshold. The <> 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 <> 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 <> 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 +<> directive to not listen only on the +loopback interface to actually allow remote access. + +[[cmddeny]]*cmddeny* [*all*] [_subnet_]:: +This is similar to the <> 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 <> 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 <> +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 <> command in *chronyc* +was issued. ++ +This directive is effective only with the <> 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 <> 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 <> +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 <> directive. ++ +On Linux, the RTC copy is performed by the kernel every 11 minutes. ++ +On Mac OS X, <> 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 <> +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 <> +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 +<> 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 <> 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 +<>, <> and <> +may be particularly useful. Also, the *iburst* option of the +<> 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 <> +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 <> and +<> 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 <> directive and the +<> command in the *chronyc* program. + +The <> directive is useful when the clocks of the +clients need to stay close together when the local time is adjusted by the +<> command. The smoothing process needs to be +activated by the <> 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 <> directive is +specified in the configuration file), and the RTC tracking information is also +saved to a file (if the <> directive has been specified). +These pieces of information are also saved if the <> +and <> 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 + +<>, <> + +== 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. diff --git a/doc/chronyc.adoc b/doc/chronyc.adoc new file mode 100644 index 0000000..2b31af8 --- /dev/null +++ b/doc/chronyc.adoc @@ -0,0 +1,1121 @@ +// 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 <> directive in the *chronyd*'s +configuration file or the <> 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 +<> command in *chronyc*, or the +<> 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 +<> 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 <> +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 +<> 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 +<> 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 <> 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 +<> 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 <> +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 <> and <> +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 +<> 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 +<> 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 +<> 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 +<> 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 +<> 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 +<> 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 <> +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 <> 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 +<> 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 <> +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 <> directive in the configuration file, +or with the <> 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 +<> 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 <>, <>, +<> and <> 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 +<> and +<> directives, and how many +client log records were dropped due to the memory limit configured by the +<> 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 +<> 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 +<> 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 <> +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 +<> 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 +<> directive. + +=== Monitoring access + +[[cmdaccheck]]*cmdaccheck* _address_:: +This command is similar to the <> 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 <> 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 <> 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 <> 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 + <> 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 <> 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 +<> 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 +<> directive). This information is also +written automatically when *chronyd* is killed (by the SIGHUP, SIGINT, SIGQUIT +or SIGTERM signals) or when the <> 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 +<> 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 <> +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 +<>, <>, <> +and <> 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 +<> 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 +<> 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 <> 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 + +<>, <> + +== 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. diff --git a/doc/chronyd.adoc b/doc/chronyd.adoc new file mode 100644 index 0000000..4afbd70 --- /dev/null +++ b/doc/chronyd.adoc @@ -0,0 +1,164 @@ +// 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. + += chronyd(8) +:doctype: manpage +:man manual: System Administration +:man source: chrony @CHRONY_VERSION@ + +== NAME + +chronyd - chrony daemon + +== SYNOPSIS + +*chronyd* [_OPTION_]... [_DIRECTIVE_]... + +== DESCRIPTION + +*chronyd* is a daemon for synchronisation of the system clock. It can +synchronise the clock with NTP servers, reference clocks (e.g. a GPS receiver), +and manual input using wristwatch and keyboard via *chronyc*. It can also +operate as an NTPv4 (RFC 5905) server and peer to provide a time service to +other computers in the network. + +If no configuration directives are specified on the command line, *chronyd* +will read them from a configuration file. The compiled-in default location of +the file is _@SYSCONFDIR@/chrony.conf_. + +Information messages and warnings will be logged to syslog. + +== OPTIONS + +*-4*:: +With this option hostnames will be resolved only to IPv4 addresses and only +IPv4 sockets will be created. + +*-6*:: +With this option hostnames will be resolved only to IPv6 addresses and only +IPv6 sockets will be created. + +*-f* _file_:: +This option can be used to specify an alternate location for the configuration +file (default _@SYSCONFDIR@/chrony.conf_). + +*-n*:: +When run in this mode, the program will not detach itself from the terminal. + +*-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 +*chronyd* was compiled with debugging support, this option can be used twice to +print also debugging messages. + +*-q*:: +When run in this mode, *chronyd* will set the system clock once and exit. It +will not detach from the terminal. + +*-Q*:: +This option is similar to *-q*, but it will only print the offset without any +corrections of the clock. + +*-r*:: +This option will reload sample histories for each of the servers and refclocks +being used. These histories are created by using the +<> command in *chronyc*, or by setting the +<> directive in the configuration +file. This option is useful if you want to stop and restart *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 +*chronyd*'s control (i.e. Linux, FreeBSD, NetBSD and Solaris). + +*-R*:: +When this option is used, the <> +directive and the <> directive used with +a positive limit will be ignored. This option is useful when restarting +*chronyd* and can be used in conjunction with the *-r* option. + +*-s*:: +This option will set the system clock from the computer's real-time clock (RTC) +or to the last modification time of the file specified by the +<> directive. Real-time clocks are +supported only on Linux. ++ +If used in conjunction with the *-r* flag, *chronyd* will attempt to preserve +the old samples after setting the system clock from the RTC. This can be used +to allow *chronyd* to perform long term averaging of the gain or loss rate +across system reboots, and is useful for systems with intermittent access to +network that are shut down when not in use. For this to work well, it relies +on *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 both the current +time and the RTC time, the system time will be set to it to restore the time +when *chronyd* was previously stopped. This is useful on computers that have no +RTC or the RTC is broken (e.g. it has no battery). + +*-u* _user_:: +This option sets the name of the system user to which *chronyd* will switch +after start in order to drop root privileges. It overrides the +<> directive (default _@DEFAULT_USER@_). ++ +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. + +*-F* _level_:: +This option configures a system call filter when *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 *chrony* is installed as the filter needs to allow +also system calls made from libraries that *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, *chronyd* could be +killed even in normal operation. + +*-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. + +*-m*:: +This option will lock *chronyd* into RAM so that it will never be paged out. +This mode is only supported on Linux. + +*-v*:: +With this option *chronyd* will print version number to the terminal and exit. + +== FILES + +_@SYSCONFDIR@/chrony.conf_ + +== SEE ALSO + +<>, <> + +== 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. diff --git a/doc/installation.adoc b/doc/installation.adoc new file mode 100644 index 0000000..151674a --- /dev/null +++ b/doc/installation.adoc @@ -0,0 +1,189 @@ +// 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. + += Installation + +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 + +---- +./configure +---- + +This is a shell script that automatically determines the system type. There is +a single optional parameter, `--prefix` which indicates the directory tree +where the software should be installed. For example, + +---- +./configure --prefix=/opt/free +---- + +will install the `chronyd` daemon into `/opt/free/sbin` and the `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: + +---- +CC=cc CFLAGS=-O ./configure --prefix=/opt/free +---- + +for Bourne-family shells, or + +---- +setenv CC cc +setenv CFLAGS -O +./configure --prefix=/opt/free +---- + +for C-family shells. + +If the software cannot (yet) be built on your system, an error message will be +shown. Otherwise, `Makefile` will be generated. + +On Linux, if development files for the libcap library are available, `chronyd` +will be built with support for dropping root privileges. On other systems no +extra library is needed. The default user which `chronyd` should run as can be +specified with the `--with-user` option of the configure script. + +If development files for the editline or readline library are available, +`chronyc` will be built with line editing support. If you don't want this, +specify the `--disable-readline` flag to configure. + +If a `timepps.h` header is available (e.g. from the +http://linuxpps.org[LinuxPPS project]), `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 the `CPPFLAGS` variable to `-I/path/to/timepps`. + +Now type + +---- +make +---- + +to build the programs. + +If you want to build the manual in HTML, type + +---- +make docs +---- + +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. + +---- +make install +---- + +This will install the binaries and man pages. + +To install the HTML version of the manual, enter the command + +---- +make install-docs +---- + +Now that the software is successfully installed, the next step is to set up a +configuration file. The default location of the file is _/etc/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 + +---- +pool pool.ntp.org iburst +makestep 1.0 3 +rtcsync +---- + +Then, `chronyd` can be run. For security reasons, it's recommended to create an +unprivileged user for `chronyd` and specify it with the `-u` command-line +option or the `user` directive in the configuration file, or set the default +user with the `--with-user` configure option before building. + +== 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: + +---- +./configure --disable-readline other-options... +---- + +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: + +`--with-readline-includes=directory_name`:: + This defines the name of the directory above the one where `readline.h` is. + `readline.h` is assumed to be in `editline` or `readline` subdirectory of the + named directory. + +`--with-readline-library=directory_name`:: + This defines the directory containing the `libedit.a` or `libedit.so` file, + or `libreadline.a` or `libreadline.so` file. + +`--with-ncurses-library=directory_name`:: + This defines the directory containing the `libncurses.a` or `libncurses.so` + file. + +== 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 `--mandir=DIR` option to configure specifies an install directory for the +man pages. This overrides the `man` subdirectory of the argument to the +--prefix option. + +---- +./configure --prefix=/usr --mandir=/usr/share/man +---- + +to set both options together. + +The final option is the `DESTDIR` option to the make command. For example, you +could use the commands + +---- +./configure --prefix=/usr --mandir=/usr/share/man +make all docs +make install DESTDIR=./tmp +cd tmp +tar cvf - . | gzip -9 > chrony.tar.gz +---- + +to build a package. When untarred within the root directory, this will install +the files to the intended final locations.