doc: update NEWS

If a special reference mode is enabled, always pass the test for
synchronization loop. This allows chronyd using the initstepslew
directive (or the -q/-Q option) to accept time from its own clients
after restart as is documented in the chrony.conf man page.

This was broken since update to NTPv4.

.gitignore

@@ -7,17 +7,15 @@
 tags
 /RELEASES
 /Makefile
-/chrony.conf.5
-/chrony.info
-/chrony.html
-/chrony.texi
-/chrony.txt
 /chronyc
-/chronyc.1
 /chronyd
-/chronyd.8
 /config.h
 /config.log
+/doc/Makefile
+/doc/*.html
+/doc/*.man
+/doc/*.man.in
+/doc/*.txt
 /getdate.c
 /version.h
 /test/simulation/clknetsim

Makefile.in

@@ -24,9 +24,6 @@
 SYSCONFDIR=@SYSCONFDIR@
 BINDIR=@BINDIR@
 SBINDIR=@SBINDIR@
-MANDIR=@MANDIR@
-INFODIR=@INFODIR@
-DOCDIR=@DOCDIR@
 LOCALSTATEDIR=@LOCALSTATEDIR@
 CHRONYVARDIR=@CHRONYVARDIR@
 
@@ -74,11 +71,12 @@ $(HASH_OBJ) : $(patsubst %.o,%.c,$(HASH_OBJ))
 
 distclean : clean
 	-rm -f .DS_Store
-	-rm -f Makefile
+	-rm -f Makefile config.h config.log
-	-rm -f chrony.conf.5 chrony.texi chronyc.1 chronyd.8
+	$(MAKE) -C doc distclean
+	$(MAKE) -C test/unit 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 +94,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 +101,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
+	$(MAKE) -C doc install
-	chmod 644 $(DESTDIR)$(MANDIR)/man1/chronyc.1
+
-	cp chronyd.8 $(DESTDIR)$(MANDIR)/man8
+docs :
-	chmod 644 $(DESTDIR)$(MANDIR)/man8/chronyd.8
+	$(MAKE) -C doc docs
-	cp chrony.conf.5 $(DESTDIR)$(MANDIR)/man5
+
-	chmod 644 $(DESTDIR)$(MANDIR)/man5/chrony.conf.5
+install-docs :
+	$(MAKE) -C doc install-docs
 
 %.o : %.c
 	$(CC) $(CFLAGS) $(CPPFLAGS) -c $<
@@ -123,28 +119,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

NEWS

@@ -1,3 +1,31 @@
+New in version 2.4
+==================
+
+Enhancements
+------------
+* Add orphan option to local directive for orphan mode compatible with ntpd
+* Add distance option to local directive to set activation threshold
+  (1 second by default)
+* Add maxdrift directive to set maximum allowed drift of system clock
+* Try to replace NTP sources exceeding maximum distance
+* Randomise source replacement to avoid getting stuck with bad sources
+* Randomise selection of sources from pools on start
+* Ignore reference timestamp as ntpd doesn't always set it correctly
+* Modify tracking report to use same values as seen by NTP clients
+* Add -c option to chronyc to write reports in CSV format
+* Provide detailed manual pages
+
+Bug fixes
+---------
+* Fix SOCK refclock to work correctly when not specified as last refclock
+* Fix initstepslew and -q/-Q options to accept time from own NTP clients
+* Fix crash on exit when multiple signals are received
+* Fix conversion of very small floating-point numbers in command packets
+
+Removed features
+----------------
+* Drop documentation in Texinfo format
+
 New in version 2.3
 ==================
 

README

@@ -53,7 +53,7 @@ ready-formatted plain text (chrony.txt) in the distribution.
 There is also information available on the chrony web pages, accessible
 through the URL 
 
-    http://chrony.tuxfamily.org/
+    https://chrony.tuxfamily.org/
 
 Where are new versions announced?
 =================================
@@ -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 <mlichvar@redhat.com>
 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 :
 

candm.h

@@ -93,11 +93,8 @@
 #define REQ_REFRESH 53
 #define REQ_SERVER_STATS 54
 #define REQ_CLIENT_ACCESSES_BY_INDEX2 55
-#define N_REQUEST_TYPES 56
+#define REQ_LOCAL2 56
-
+#define N_REQUEST_TYPES 57
-/* Special utoken value used to log on with first exchange being the
-   password.  (This time value has long since gone by) */
-#define SPECIAL_UTOKEN 0x10101010
 
 /* Structure used to exchange timevals independent on size of time_t */
 typedef struct {
@@ -215,6 +212,8 @@ typedef struct {
 typedef struct {
   int32_t on_off;
   int32_t stratum;
+  Float distance;
+  int32_t orphan;
   int32_t EOR;
 } REQ_Local;
 

chrony.conf.5.in

@@ -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 <rc@rc0.org.uk>
-
-This man-page was written by Jan Schaumann <jschauma@netmeister.org> 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.
-

chronyc.1.in

@@ -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 <rc@rc0.org.uk>
-
-This man-page was written by Jan Schaumann <jschauma@netmeister.org> 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.

chronyd.8.in

@@ -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 <rc@rc0.org.uk>
-
-This man-page was written by Jan Schaumann <jschauma@netmeister.org> 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.
-

cmdmon.c

@@ -132,6 +132,7 @@ static const char permissions[] = {
   PERMIT_AUTH, /* REFRESH */
   PERMIT_AUTH, /* SERVER_STATS */
   PERMIT_AUTH, /* CLIENT_ACCESSES_BY_INDEX2 */
+  PERMIT_AUTH, /* LOCAL2 */
 };
 
 /* ================================================== */
@@ -248,43 +249,51 @@ prepare_socket(int family, int port_number)
 
 /* ================================================== */
 
-void
+static void
-CAM_Initialise(int family)
+do_size_checks(void)
 {
-  int i, port_number;
+  int i, request_length, padding_length, reply_length;
+  CMD_Request request;
+  CMD_Reply reply;
 
-  assert(!initialised);
+  assert(offsetof(CMD_Request, data) == 20);
-  initialised = 1;
+  assert(offsetof(CMD_Reply, data) == 28);
-
-  assert(sizeof (permissions) / sizeof (permissions[0]) == N_REQUEST_TYPES);
 
   for (i = 0; i < N_REQUEST_TYPES; i++) {
-    CMD_Request r;
+    request.version = PROTO_VERSION_NUMBER;
-    int command_length, padding_length;
+    request.command = htons(i);
-
+    request_length = PKL_CommandLength(&request);
-    r.version = PROTO_VERSION_NUMBER;
+    padding_length = PKL_CommandPaddingLength(&request);
-    r.command = htons(i);
+    if (padding_length > MAX_PADDING_LENGTH || padding_length > request_length ||
-    command_length = PKL_CommandLength(&r);
+        request_length > sizeof (CMD_Request) ||
-    padding_length = PKL_CommandPaddingLength(&r);
+        (request_length && request_length < offsetof(CMD_Request, data)))
-    assert(padding_length <= MAX_PADDING_LENGTH && padding_length <= command_length);
+      assert(0);
-    assert((command_length >= offsetof(CMD_Request, data) &&
-            command_length <= sizeof (CMD_Request)) || command_length == 0);
   }
 
   for (i = 1; i < N_REPLY_TYPES; i++) {
-    CMD_Reply r;
+    reply.reply = htons(i);
-    int reply_length;
+    reply.status = STT_SUCCESS;
-
+    reply.data.manual_list.n_samples = htonl(MAX_MANUAL_LIST_SAMPLES);
-    r.reply = htons(i);
+    reply_length = PKL_ReplyLength(&reply);
-    r.status = STT_SUCCESS;
+    if ((reply_length && reply_length < offsetof(CMD_Reply, data)) ||
-    r.data.manual_list.n_samples = htonl(MAX_MANUAL_LIST_SAMPLES);
+        reply_length > sizeof (CMD_Reply))
-    reply_length = PKL_ReplyLength(&r);
+      assert(0);
-    assert((reply_length >= offsetof(CMD_Reply, data) &&
-            reply_length <= sizeof (CMD_Reply)) || reply_length == 0);
   }
+}
 
+/* ================================================== */
+
+void
+CAM_Initialise(int family)
+{
+  int port_number;
+
+  assert(!initialised);
+  assert(sizeof (permissions) / sizeof (permissions[0]) == N_REQUEST_TYPES);
+  do_size_checks();
+
+  initialised = 1;
   sock_fdu = -1;
-
   port_number = CNF_GetCommandPort();
 
   if (port_number && (family == IPADDR_UNSPEC || family == IPADDR_INET4))
@@ -576,11 +585,10 @@ handle_settime(CMD_Request *rx_message, CMD_Reply *tx_message)
 static void
 handle_local(CMD_Request *rx_message, CMD_Reply *tx_message)
 {
-  int on_off, stratum;
+  if (ntohl(rx_message->data.local.on_off)) {
-  on_off = ntohl(rx_message->data.local.on_off);
+    REF_EnableLocal(ntohl(rx_message->data.local.stratum),
-  if (on_off) {
+                    UTI_FloatNetworkToHost(rx_message->data.local.distance),
-    stratum = ntohl(rx_message->data.local.stratum);
+                    ntohl(rx_message->data.local.orphan));
-    REF_EnableLocal(stratum);
   } else {
     REF_DisableLocal();
   }
@@ -1409,7 +1417,7 @@ read_from_cmd_socket(void *anything)
           handle_settime(&rx_message, &tx_message);
           break;
         
-        case REQ_LOCAL:
+        case REQ_LOCAL2:
           handle_local(&rx_message, &tx_message);
           break;
 

cmdparse.c

@@ -3,7 +3,7 @@
 
  **********************************************************************
  * Copyright (C) Richard P. Curnow  1997-2003
- * Copyright (C) Miroslav Lichvar  2013-2014
+ * Copyright (C) Miroslav Lichvar  2013-2014, 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
@@ -223,6 +223,41 @@ CPS_ParseNTPSourceAdd(char *line, CPS_NTP_Source *src)
 
 /* ================================================== */
 
+int
+CPS_ParseLocal(char *line, int *stratum, int *orphan, double *distance)
+{
+  int n;
+  char *cmd;
+
+  *stratum = 10;
+  *distance = 1.0;
+  *orphan = 0;
+
+  while (*line) {
+    cmd = line;
+    line = CPS_SplitWord(line);
+
+    if (!strcasecmp(cmd, "stratum")) {
+      if (sscanf(line, "%d%n", stratum, &n) != 1 ||
+          *stratum >= NTP_MAX_STRATUM || *stratum <= 0)
+        return 0;
+    } else if (!strcasecmp(cmd, "orphan")) {
+      *orphan = 1;
+      n = 0;
+    } else if (!strcasecmp(cmd, "distance")) {
+      if (sscanf(line, "%lf%n", distance, &n) != 1)
+        return 0;
+    } else {
+      return 0;
+    }
+
+    line += n;
+  }
+
+  return 1;
+}
+/* ================================================== */
+
 void
 CPS_StatusToString(CPS_Status status, char *dest, int len)
 {

cmdparse.h

@@ -59,6 +59,9 @@ typedef struct {
 /* Parse a command to add an NTP server or peer */
 extern CPS_Status CPS_ParseNTPSourceAdd(char *line, CPS_NTP_Source *src);
   
+/* Parse a command to enable local reference */
+extern int CPS_ParseLocal(char *line, int *stratum, int *orphan, double *distance);
+
 /* Get a string describing error status */
 extern void CPS_StatusToString(CPS_Status status, char *dest, int len);
 

conf.c

@@ -85,6 +85,7 @@ static char *rtc_file = NULL;
 static double max_update_skew = 1000.0;
 static double correction_time_ratio = 3.0;
 static double max_clock_error = 1.0; /* in ppm */
+static double max_drift = 500000.0; /* in ppm */
 static double max_slew_rate = 1e6 / 12.0; /* in ppm */
 
 static double max_distance = 3.0;
@@ -107,6 +108,8 @@ static char *dumpdir;
 
 static int enable_local=0;
 static int local_stratum;
+static int local_orphan;
+static double local_distance;
 
 /* Threshold (in seconds) - if absolute value of initial error is less
    than this, slew instead of stepping */
@@ -489,6 +492,8 @@ CNF_ParseLine(const char *filename, int number, char *line)
     parse_double(p, &max_clock_error);
   } else if (!strcasecmp(command, "maxdistance")) {
     parse_double(p, &max_distance);
+  } else if (!strcasecmp(command, "maxdrift")) {
+    parse_double(p, &max_drift);
   } else if (!strcasecmp(command, "maxsamples")) {
     parse_int(p, &max_samples);
   } else if (!strcasecmp(command, "maxslewrate")) {
@@ -814,13 +819,9 @@ parse_log(char *line)
 static void
 parse_local(char *line)
 {
-  int stratum;
+  if (!CPS_ParseLocal(line, &local_stratum, &local_orphan, &local_distance))
-  if (sscanf(line, "stratum%d", &stratum) == 1) {
-    local_stratum = stratum;
-    enable_local = 1;
-  } else {
     command_parse_error();
-  }
+  enable_local = 1;
 }
 
 /* ================================================== */
@@ -1486,6 +1487,14 @@ CNF_GetMaxUpdateSkew(void)
 
 /* ================================================== */
 
+double
+CNF_GetMaxDrift(void)
+{
+  return max_drift;
+}
+
+/* ================================================== */
+
 double
 CNF_GetMaxClockError(void)
 {
@@ -1558,10 +1567,12 @@ CNF_GetCommandPort(void) {
 /* ================================================== */
 
 int
-CNF_AllowLocalReference(int *stratum)
+CNF_AllowLocalReference(int *stratum, int *orphan, double *distance)
 {
   if (enable_local) {
     *stratum = local_stratum;
+    *orphan = local_orphan;
+    *distance = local_distance;
     return 1;
   } else {
     return 0;

conf.h

@@ -83,6 +83,7 @@ extern char *CNF_GetLeapSecTimezone(void);
 /* Value returned in ppm, as read from file */
 extern double CNF_GetMaxUpdateSkew(void);
 extern double CNF_GetMaxClockError(void);
+extern double CNF_GetMaxDrift(void);
 extern double CNF_GetCorrectionTimeRatio(void);
 extern double CNF_GetMaxSlewRate(void);
 
@@ -91,7 +92,7 @@ extern double CNF_GetReselectDistance(void);
 extern double CNF_GetStratumWeight(void);
 extern double CNF_GetCombineLimit(void);
 
-extern int CNF_AllowLocalReference(int *stratum);
+extern int CNF_AllowLocalReference(int *stratum, int *orphan, double *distance);
 
 extern void CNF_SetupAccessRestrictions(void);
 

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}%;\

doc/Makefile.in

@@ -0,0 +1,72 @@
+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:
+	rm -f $(MAN_FILES) $(TXT_FILES) $(HTML_FILES)
+	rm -f $(MAN_IN_FILES)
+
+distclean:
+	rm -f $(MAN_FILES) $(TXT_FILES) $(HTML_FILES)
+	rm -f Makefile

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
+<<chronyc.adoc#dump,*dump*>> command in *chronyc*, or by setting the
+<<chrony.conf.adoc#dumponexit,*dumponexit*>> 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 <<chrony.conf.adoc#initstepslew,*initstepslew*>>
+directive and the <<chrony.conf.adoc#makestep,*makestep*>> 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
+<<chrony.conf.adoc#driftfile,*driftfile*>> 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
+<<chrony.conf.adoc#user,*user*>> 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
+
+<<chronyc.adoc#,*chronyc(1)*>>, <<chrony.conf.adoc#,*chrony.conf(5)*>>
+
+== BUGS
+
+For instructions on how to report bugs, please visit
+https://chrony.tuxfamily.org/.
+
+== AUTHORS
+
+chrony was written by Richard Curnow, Miroslav Lichvar and others.

doc/faq.adoc

@@ -1,77 +1,71 @@
+// This file is part of chrony
+//
+// Copyright (C) Richard P. Curnow  1997-2003
+// Copyright (C) Miroslav Lichvar  2014-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.
+
+= Frequently Asked Questions
 :toc:
 :numbered:
 
-Frequently Asked Questions
+== `chrony` compared to other programs
-==========================
 
-== +chrony+ compared to other programs
+=== How does `chrony` compare to `ntpd`?
 
-=== How does +chrony+ compare to +ntpd+?
+`chronyd` was designed to work well in a wide range of conditions and it can
-
+usually synchronise the system clock faster and with better time accuracy. It
-+chronyd+ was designed to work well in a wide range of conditions and it can
-usually synchronise the system clock faster and with better time accuracy.  It
 doesn't implement some of the less useful NTP modes like broadcast client or
 multicast server/client.
 
-For a more detailed comparison of features and performance, see the
+If your computer is connected to the Internet only for few minutes at a time,
-http://chrony.tuxfamily.org/comparison.html[comparison page] on the +chrony+
-website and the
-http://chrony.tuxfamily.org/manual.html#Comparison-with-ntpd[Comparison with
-ntpd] section in the manual.
-
-If your computer is connected to the internet only for few minutes at a time,
 the network connection is often congested, you turn your computer off or
 suspend it frequently, the clock is not very stable (e.g. there are rapid
 changes in the temperature or it's a virtual machine), or you want to use NTP
-on an isolated network with no hardware reference clocks in sight, +chrony+
+on an isolated network with no hardware reference clocks in sight, `chrony`
 will probably work much better for you.
 
-The original reason +chrony+ was written was that +ntpd+ (called +xntpd+ at the
+For a more detailed comparison of features and performance, see the
-time) could not to do anything sensible on a PC which was connected to the 'net
+https://chrony.tuxfamily.org/comparison.html[comparison page] on the `chrony`
-only for about 5 minutes once or twice a day, mainly to upload/download email
+website.
-and news.  The requirements were
-
-* slew the time to correct it when going online and NTP servers
-  become visible
-* determine the rate at which the computer gains or loses time and
-  use this information to keep it reasonably correct between connects
-  to the 'net.  This has to be done using a method that does not care
-  about the intermittent availability of the references or the fact
-  the computer is turned off between groups of measurements.
-* maintain the time across reboots, by working out the error and
-  drift rate of the computer's real-time clock and using this
-  information to set the system clock correctly at boot up.
-
-Also, when working with isolated networks with no true time references at all
-+ntpd+ was found to give no help with managing the local clock's gain/loss rate
-on the NTP master node (which was set from watch).  Some automated support was
-added to +chrony+ to deal with this.
 
 == Configuration issues
 
 === What is the minimum recommended configuration for an NTP client?
 
 First, the client needs to know which NTP servers it should ask for the current
-time.  They are specified by the +server+ or +pool+ directive.  The +pool+
+time. They are specified by the `server` or `pool` directive. The `pool`
-directive can be used for names that resolve to multiple addresses.  For good
+directive can be used for names that resolve to multiple addresses. For good
-reliability the client should have at least three servers.  The +iburst+ option
+reliability the client should have at least three servers. The `iburst` option
 speeds up the initial synchronisation.
 
 To stabilize the initial synchronisation on the next start, the estimated drift
-of the system clock is saved by adding the +driftfile+ directive.
+of the system clock is saved to a file specified by the `driftfile` directive.
 
 If the system clock can be far from the true time after boot for any reason,
-+chronyd+ should be allowed to correct it quickly by stepping instead of
+`chronyd` should be allowed to correct it quickly by stepping instead of
-slewing, which would take a very long time.  The +makestep+ directive does
+slewing, which would take a very long time. The `makestep` directive does
 that.
 
-In order to keep the real-time clock (RTC) close to the true time on Linux, so
+In order to keep the real-time clock (RTC) close to the true time, so the
-the system time is reasonably close to the true time when it's initialized on
+system time is reasonably close to the true time when it's initialized on the
-the next boot from the RTC, the +rtcsync+ directive enables a kernel mode in
+next boot from the RTC, the `rtcsync` directive enables a mode in which the
-which the system time is copied to the RTC every 11 minutes.
+system time is periodically copied to the RTC. It is supported on Linux and Mac
+OS X.
 
 If you want to use public NTP servers from the
-http://www.pool.ntp.org/[pool.ntp.org] project, the minimal 'chrony.conf' file
+http://www.pool.ntp.org/[pool.ntp.org] project, the minimal _chrony.conf_ file
 could be:
 
 ----
@@ -83,15 +77,15 @@ rtcsync
 
 === How do I make an NTP server from an NTP client?
 
-You need to add an +allow+ directive to the 'chrony.conf' file in order to open
+You need to add an `allow` directive to the _chrony.conf_ file in order to open
-the NTP port and allow +chronyd+ to reply to client requests.  +allow+ with no
+the NTP port and allow `chronyd` to reply to client requests. `allow` with no
 specified subnet allows all IPv4 and IPv6 addresses.
 
 === I have several computers on a LAN. Should be all clients of an external server?
 
-The best configuration is usually to make one computer the master, with
+The best configuration is usually to make one computer the server, with
-the others as clients of it.  Add a +local+ directive to the master's
+the others as clients of it. Add a `local` directive to the server's
-'chrony.conf' file.  This configuration will be better because
+_chrony.conf_ file. This configuration will be better because
 
 * the load on the external connection is less
 * the load on the external NTP server(s) is less
@@ -100,79 +94,79 @@ the others as clients of it.  Add a +local+ directive to the master's
 
 === Must I specify servers by IP address if DNS is not available on chronyd start?
 
-No.  Starting from version 1.25, +chronyd+ will keep trying to resolve
+No. Starting from version 1.25, `chronyd` will keep trying to resolve
-the hostnames specified in the +server+ and +peer+ directives in
+the names specified by the `server`, `pool`, and `peer` directives in an
-increasing intervals until it succeeds.  The +online+ command can be
+increasing interval until it succeeds. The `online` command can be issued from
-issued from +chronyc+ to try to resolve them immediately.
+`chronyc` to try to resolve them immediately.
 
-=== How can I make +chronyd+ more secure?
+=== How can I make `chronyd` more secure?
 
-If you don't need to serve time to NTP clients or peers, you can add +port 0+
+If you don't need to serve time to NTP clients or peers, you can add `port 0`
-to the 'chrony.conf' file to completely disable the NTP server functionality
+to the _chrony.conf_ file to completely disable the NTP server functionality
-and prevent NTP requests from reaching +chronyd+. Starting from version 2.0,
+and prevent NTP requests from reaching `chronyd`. Starting from version 2.0,
-the NTP server port is open only when client access is allowed by the +allow+
+the NTP server port is open only when client access is allowed by the `allow`
-directive or command, an NTP peer is configured, or the +broadcast+ directive
+directive or command, an NTP peer is configured, or the `broadcast` directive
 is used.
 
-If you don't need to use +chronyc+ remotely, you can add the following
+If you don't need to use `chronyc` remotely, you can add the following
 directives to the configuration file to bind the command sockets to the
-loopback interface.  This is done by default since version 2.0.
+loopback interface. This is done by default since version 2.0.
 
 ----
 bindcmdaddress 127.0.0.1
 bindcmdaddress ::1
 ----
 
-If you don't need to use +chronyc+ at all or you need to run +chronyc+ only
+If you don't need to use `chronyc` at all or you need to run `chronyc` only
-under the root or chrony user (which can access +chronyd+ through a Unix domain
+under the root or _chrony_ user (which can access `chronyd` through a Unix
-socket since version 2.2), you can disable the internet command sockets
+domain socket since version 2.2), you can disable the internet command sockets
-completely by adding +cmdport 0+ to the configuration file.
+completely by adding `cmdport 0` to the configuration file.
 
-You can specify an unprivileged user with the +-u+ option, or the +user+
+You can specify an unprivileged user with the `-u` option, or the `user`
-directive in the 'chrony.conf' file, to which +chronyd+ will switch after start
+directive in the _chrony.conf_ file, to which `chronyd` will switch after start
-in order to drop root privileges.  The configure script has a +--with-user+
+in order to drop root privileges. The configure script has a `--with-user`
-option, which sets the default user.  On Linux, +chronyd+ needs to be compiled
+option, which sets the default user. On Linux, `chronyd` needs to be compiled
-with support for the +libcap+ library.  On other systems, +chronyd+ forks into
+with support for the `libcap` library. On other systems, `chronyd` forks into
-two processes.  The child process retains root privileges, but can only perform
+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.
 
-Also, if +chronyd+ is compiled with support for the Linux secure computing
+Also, if `chronyd` is compiled with support for the Linux secure computing
-(seccomp) facility, you can enable a system call filter with the +-F+ option.
+(seccomp) facility, you can enable a system call filter with the `-F` option.
 It will significantly reduce the kernel attack surface and possibly prevent
-kernel exploits from the +chronyd+ process if it's compromised.  It's
+kernel exploits from the `chronyd` process if it's compromised. 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
+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
+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
+If the filter is missing some system call, `chronyd` could be killed even in
 normal operation.
 
 === How can I improve the accuracy of the system clock with NTP sources?
 
 Select NTP servers that are well synchronised, stable and close to your
-network.  It's better to use more than one server, three or four is usually
+network. It's better to use more than one server, three or four is usually
-recommended as the minimum, so +chronyd+ can detect falsetickers and combine
+recommended as the minimum, so `chronyd` can detect servers that serve false
-measurements from multiple sources.
+time and combine measurements from multiple sources.
 
-There are also useful options which can be set in the +server+ directive, they
+There are also useful options which can be set in the `server` directive, they
-are +minpoll+, +maxpoll+, +polltarget+, +maxdelay+, +maxdelayratio+ and
+are `minpoll`, `maxpoll`, `polltarget`, `maxdelay`, `maxdelayratio` and
-+maxdelaydevratio+.
+`maxdelaydevratio`.
 
 The first three options set the minimum and maximum allowed polling interval,
-and how should be the actual interval adjusted in the specified range.  Their
+and how should be the actual interval adjusted in the specified range. Their
-default values are 6 (64 seconds) for +minpoll+, 10 (1024 seconds) for
+default values are 6 (64 seconds) for `minpoll`, 10 (1024 seconds) for
-+maxpoll+ and 6 (samples) for +polltarget+.  The default values should be used
+`maxpoll` and 6 (samples) for `polltarget`. The default values should be used
-for general servers on the internet.  With your own NTP servers or if have
+for general servers on the Internet. With your own NTP servers or if have
 permission to poll some servers more frequently, setting these options for
 shorter polling intervals may significantly improve the accuracy of the system
 clock.
 
-The optimal polling interval depends on many factors, including the ratio
+The optimal polling interval depends mainly on two factors, stability of the
-between the wander of the clock and the network jitter (sometimes expressed in
+network latency and stability of the system clock (which mainly depends on the
-NTP documents as the Allan intercept), the temperature sensitivity of the
+temperature sensitivity of the crystal oscillator and the maximum rate of the
-crystal oscillator and the maximum rate of change of the temperature.
+temperature change).
 
-An example of the directive for an NTP server on the internet that you are
+An example of the directive for an NTP server on the Internet that you are
 allowed to poll frequently could be
 
 ----
@@ -188,96 +182,102 @@ server ntp.local minpoll 2 maxpoll 4 polltarget 30
 
 The maxdelay options are useful to ignore measurements with larger delay (e.g.
 due to congestion in the network) and improve the stability of the
-synchronisation.  The +maxdelaydevratio+ option could be added to the example
+synchronisation. The `maxdelaydevratio` option could be added to the example
 with local NTP server
 
 ----
 server ntp.local minpoll 2 maxpoll 4 polltarget 30 maxdelaydevratio 2
 ----
 
-=== What happened to the +commandkey+ and +generatecommandkey+ directives?
+=== What happened to the `commandkey` and `generatecommandkey` directives?
 
-They were removed in version 2.2.  Authentication is no longer supported in the
+They were removed in version 2.2. Authentication is no longer supported in the
-command protocol.  Commands that required authentication are now allowed only
+command protocol. Commands that required authentication are now allowed only
-through a Unix domain socket, which is accessible only by the root and chrony
+through a Unix domain socket, which is accessible only by the root and _chrony_
-users.  If you need to configure +chronyd+ remotely or locally without the root
+users. If you need to configure `chronyd` remotely or locally without the root
-password, please consider using ssh and/or sudo to run +chronyc+ under the root
+password, please consider using ssh and/or sudo to run `chronyc` under the root
-or chrony user on the same host as +chronyd+ is running.
+or _chrony_ user on the host where `chronyd` is running.
 
 == Computer is not synchronising
 
-This is the most common problem.  There are a number of reasons, see the
+This is the most common problem. There are a number of reasons, see the
 following questions.
 
 === Behind a firewall?
 
 If there is a firewall between you and the NTP server you're trying to use, the
-packets may be blocked.  Try using a tool like +wireshark+ or +tcpdump+ to see if
+packets may be blocked. Try using a tool like `wireshark` or `tcpdump` to see if
-you're getting responses from the server.  If you have an external modem, see
+you're getting responses from the server. If you have an external modem, see
 if the receive light blinks straight after the transmit light (when the link is
-quiet apart from the NTP traffic.)  Try adding +log measurements+ to the
+quiet apart from the NTP traffic). Try adding `log measurements` to the
-'chrony.conf' file and look in the 'measurements.log' file after +chronyd+ has
+_chrony.conf_ file and look in the _measurements.log_ file after `chronyd` has
 been running for a short period. See if any measurements appear.
 
-=== Are NTP servers specified with the +offline+ option?
+=== Are NTP servers specified with the `offline` option?
 
-Check that you're using +chronyc+\'s +online+ and +offline+ commands
+Check that you're using ``chronyc``'s `online` and `offline` commands
-appropriately.  Again, check in 'measurements.log' to see if you're getting any
+appropriately. Again, check in _measurements.log_ to see if you're getting any
 data back from the server.
 
-=== Is +chronyd+ allowed to step the system clock?
+=== Is `chronyd` allowed to step the system clock?
 
-By default, +chronyd+ adjusts the clock gradually by slowing it down or
+By default, `chronyd` adjusts the clock gradually by slowing it down or
-speeding it up.  If the clock is too far from the correct time, it will take
+speeding it up. If the clock is too far from the true time, it will take
-a long time to correct the error.  The +System time+ value printed by the
+a long time to correct the error. The `System time` value printed by the
-+chronyc+'s +tracking+ command is the remaining correction that needs to be
+``chronyc``'s `tracking` command is the remaining correction that needs to be
 applied to the system clock.
 
-The +makestep+ directive can be used to allow +chronyd+ to step the clock. For
+The `makestep` directive can be used to allow `chronyd` to step the clock. For
-example, if 'chrony.conf' had
+example, if _chrony.conf_ had
 
 ----
 makestep 1 3
 ----
 
 the clock would be stepped in the first three updates if its offset was larger
-than one second.  Normally, it's recommended to allow the step only in the
+than one second. Normally, it's recommended to allow the step only in the first
-first few updates, but in some cases (e.g. a computer without RTC or virtual
+few updates, but in some cases (e.g. a computer without an RTC or virtual
-machine which can be suspended and resumed with incorrect time) it may be
+machine which can be suspended and resumed with an incorrect time) it may be
-necessary to allow the step at any clock update.  The example above would
+necessary to allow the step on any clock update. The example above would change
-change to
+to
 
 ----
 makestep 1 -1
 ----
 
-== Issues with +chronyc+
+== Issues with `chronyc`
 
-=== I keep getting the error +506 Cannot talk to daemon+
+=== I keep getting the error `506 Cannot talk to daemon`
 
-When accessing +chronyd+ remotely, make sure that the 'chrony.conf' file (on
+When accessing `chronyd` remotely, make sure that the _chrony.conf_ file (on
-the computer where +chronyd+ is running) has a 'cmdallow' entry for the
+the computer where `chronyd` is running) has a `cmdallow` entry for the
-computer you are running +chronyc+ on and an appropriate 'bindcmdaddress'
+computer you are running `chronyc` on and an appropriate `bindcmdaddress`
-directive.  This isn't necessary for localhost.
+directive. This isn't necessary for localhost.
 
-Perhaps +chronyd+ is not running.  Try using the +ps+ command (e.g.  on Linux,
+Perhaps `chronyd` is not running. Try using the `ps` command (e.g. on Linux,
-+ps -auxw+) to see if it's running.  Or try +netstat -a+ and see if the ports
+`ps -auxw`) to see if it's running. Or try `netstat -a` and see if the ports
-123/udp and 323/udp are listening.  If +chronyd+ is not running, you may have a
+123/udp and 323/udp are listening. If `chronyd` is not running, you may have a
-problem with the way you are trying to start it (e.g.  at boot time).
+problem with the way you are trying to start it (e.g. at boot time).
 
 Perhaps you have a firewall set up in a way that blocks packets on port
-323/udp.  You need to amend the firewall configuration in this case.
+323/udp. You need to amend the firewall configuration in this case.
 
-=== I keep getting the error +501 Not authorised+
+=== I keep getting the error `501 Not authorised`
 
-Since version 2.2, the +password+ command doesn't do anything and +chronyc+
+Since version 2.2, the `password` command doesn't do anything and `chronyc`
-needs to run under the root or chrony user, which are allowed to access the
+needs to run locally under the root or _chrony_ user, which are allowed to
-Unix domain command socket.
+access the ``chronyd``'s Unix domain command socket.
 
-=== Is the +chronyc+ / +chronyd+ protocol documented anywhere?
+With older versions, you need to authenticate with the `password` command first
+or use the `-a` option to authenticate automatically on start. The
+configuration file needs to specify a file which contains keys (`keyfile`
+directive) and which key in the key file should be used for `chronyc`
+authentication (`commandkey` directive).
 
-Only by the source code :-) See 'cmdmon.c' (+chronyd+ side) and 'client.c'
+=== Is the `chronyc` / `chronyd` protocol documented anywhere?
-(+chronyc+ side).
+
+Only by the source code. See _cmdmon.c_ (`chronyd` side) and _client.c_
+(`chronyc` side).
 
 == Real-time clock issues
 
@@ -287,96 +287,94 @@ This is the clock which keeps the time even when your computer is turned off.
 It is used to initialize the system clock on boot. It normally doesn't drift
 more than few seconds per day.
 
-There are two approaches how +chronyd+ can work with it.  One is to use the
+There are two approaches how `chronyd` can work with it. One is to use the
-+rtcsync+ directive, which tells +chronyd+ to enable a kernel mode which sets
+`rtcsync` directive, which tells `chronyd` to enable a kernel mode which sets
-the RTC from the system clock every 11 minutes.  +chronyd+ itself won't touch
+the RTC from the system clock every 11 minutes. `chronyd` itself won't touch
-the RTC.  If the computer is not turned off for a long time, the RTC should
+the RTC. If the computer is not turned off for a long time, the RTC should
 still be close to the true time when the system clock will be initialized from
 it on the next boot.
 
-The other option is to use the +rtcfile+ directive, which will tell +chronyd+
+The other option is to use the `rtcfile` directive, which tells `chronyd` to
-to monitor the rate at which the RTC gains or loses time.  When +chronyd+ is
+monitor the rate at which the RTC gains or loses time. When `chronyd` is
-started with the +-s+ option on the next boot, it will set the system time from
+started with the `-s` option on the next boot, it will set the system time from
-the RTC and also compensate for the drift it has measured previously.  The
+the RTC and also compensate for the drift it has measured previously. The
-+rtcautotrim+ directive can be used to keep the RTC close to the true time, but
+`rtcautotrim` directive can be used to keep the RTC close to the true time, but
 it's not strictly necessary if its only purpose is to set the system clock when
-+chronyd+ is started on boot.  See the documentation for details.
+`chronyd` is started on boot. See the documentation for details.
 
-=== I want to use +chronyd+'s RTC support. Must I disable +hwclock+?
+=== I want to use ``chronyd``'s RTC support. Must I disable `hwclock`?
 
-The +hwclock+ program is often set-up by default in the boot and shutdown
+The `hwclock` program is often set-up by default in the boot and shutdown
-scripts with many Linux installations.  With the kernel RTC synchronisation
+scripts with many Linux installations. With the kernel RTC synchronisation
-(+rtcsync+ directive), the RTC will be set also every 11 minutes as long as the
+(`rtcsync` directive), the RTC will be set also every 11 minutes as long as the
-system clock is synchronised.  If you want to use +chronyd+'s RTC monitoring
+system clock is synchronised. If you want to use ``chronyd``'s RTC monitoring
-(+rtcfile+ directive), it's important to disable +hwclock+ in the shutdown
+(`rtcfile` directive), it's important to disable `hwclock` in the shutdown
-procedure.  If you don't, it will over-write the RTC with a new value, unknown
+procedure. If you don't, it will over-write the RTC with a new value, unknown
-to +chronyd+.  At the next reboot, +chronyd+ started with the +-s+ option will
+to `chronyd`. At the next reboot, `chronyd` started with the `-s` option will
 compensate this (wrong) time with its estimate of how far the RTC has drifted
 whilst the power was off, giving a meaningless initial system time.
 
-There is no need to remove +hwclock+ from the boot process, as long as +chronyd+
+There is no need to remove `hwclock` from the boot process, as long as `chronyd`
 is started after it has run.
 
-=== I just keep getting the +513 RTC driver not running+ message
+=== I just keep getting the `513 RTC driver not running` message
 
-For the real time clock support to work, you need the following three
+For the real-time clock support to work, you need the following three
 things
 
-* a kernel that is supported (e.g. 2.2 onwards)
+* an RTC in your computer
-* enhanced RTC support compiled into the kernel
+* a Linux kernel with enabled RTC support
-* an +rtcfile+ directive in your 'chrony.conf' file
+* an `rtcfile` directive in your _chrony.conf_ file
 
-== NTP-specific issues
+=== I get `Could not open /dev/rtc, Device or resource busy` in my syslog file
-
-=== Can +chronyd+ be driven from broadcast NTP servers?
-
-No, the broadcast client mode is not supported and there is currently no plan
-to implement it.  The broadcast and multicast modes are inherently less
-accurate and less secure (even with authentication) than the ordinary
-server/client mode and they are not as useful as they used to be.  Even with
-very modest hardware a single NTP server can serve time to hundreds of
-thousands of clients using the ordinary mode.
-
-=== Can +chronyd+ transmit broadcast NTP packets?
-
-Yes, the +broadcast+ directive can be used to enable the broadcast server mode
-to serve time to clients in the network which support the broadcast client mode
-(it's not supported in +chronyd+, see the previous question).
-
-=== Can +chronyd+ keep the system clock a fixed offset away from real time?
-
-This is not possible as the program currently stands.
-
-=== What happens if the network connection is dropped without using +chronyc+'s +offline+ command first?
-
-+chronyd+ will keep trying to access the server(s) that it thinks are online.
-When the network is connected again, it will take some time (on average half of
-the current polling interval) before new measurements are made and the clock is
-corrected. If the servers were set to offline and the +online+ command was
-issued when the network was connected, +chronyd+ would make new measurements
-immediately.
-
-The +auto_offline+ option to the +server+ entry in the 'chrony.conf' file may
-be useful to switch the servers to the offline state automatically.
-
-== Linux-specific issues
-
-=== I get +Could not open /dev/rtc, Device or resource busy+ in my syslog file
 
 Some other program running on the system may be using the device.
 
-== Microsoft Windows
+== NTP-specific issues
 
-=== Does +chrony+ support Windows?
+=== Can `chronyd` be driven from broadcast NTP servers?
 
-No.  The +chronyc+ program (the command-line client used for configuring
+No, the broadcast client mode is not supported and there is currently no plan
-+chronyd+ while it is running) has been successfully built and run under
+to implement it. The broadcast and multicast modes are inherently less
-Cygwin in the past.  +chronyd+ is not portable, because part of it is
+accurate and less secure (even with authentication) than the ordinary
-very system-dependent.  It needs adapting to work with Windows'
+server/client mode and they are not as useful as they used to be. Even with
+very modest hardware a single NTP server can serve time to hundreds of
+thousands of clients using the ordinary mode.
+
+=== Can `chronyd` transmit broadcast NTP packets?
+
+Yes, the `broadcast` directive can be used to enable the broadcast server mode
+to serve time to clients in the network which support the broadcast client mode
+(it's not supported in `chronyd`, see the previous question).
+
+=== Can `chronyd` keep the system clock a fixed offset away from real time?
+
+This is not possible as the program currently stands.
+
+=== What happens if the network connection is dropped without using ``chronyc``'s `offline` command first?
+
+`chronyd` will keep trying to access the server(s) that it thinks are online.
+When the network is connected again, it will take some time (on average half of
+the maximum polling interval) before new measurements are made and the clock is
+corrected. If the servers were set to offline and the `online` command was
+issued when the network was connected, `chronyd` would make new measurements
+immediately.
+
+The `auto_offline` option to the `server` entry in the _chrony.conf_ file may
+be useful to switch the servers to the offline state automatically.
+
+== Operating systems
+
+=== Does `chrony` support Windows?
+
+No. The `chronyc` program (the command-line client used for configuring
+`chronyd` while it is running) has been successfully built and run under
+Cygwin in the past. `chronyd` is not portable, because part of it is
+very system-dependent. It needs adapting to work with Windows'
 equivalent of the adjtimex() call, and it needs to be made to work as a
 service.
 
 === Are there any plans to support Windows?
 
-We have no plans to do this.  Anyone is welcome to pick this work up and
+We have no plans to do this. Anyone is welcome to pick this work up and
 contribute it back to the project.

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.

local.c

@@ -42,13 +42,12 @@
 
 /* ================================================== */
 
-/* Maximum allowed frequency offset in ppm, the time must not stop
-   or run backwards */
-#define MAX_FREQ 500000.0
-
 /* Variable to store the current frequency, in ppm */
 static double current_freq_ppm;
 
+/* Maximum allowed frequency, in ppm */
+static double max_freq_ppm;
+
 /* Temperature compensation, in ppm */
 static double temp_comp_ppm;
 
@@ -166,6 +165,11 @@ LCL_Initialise(void)
 
   calculate_sys_precision();
 
+  /* This is the maximum allowed frequency offset in ppm, the time must
+     never stop or run backwards */
+  max_freq_ppm = CNF_GetMaxDrift();
+  max_freq_ppm = CLAMP(0.0, max_freq_ppm, 500000.0);
+
   max_clock_error = CNF_GetMaxClockError() * 1e-6;
 }
 
@@ -406,12 +410,12 @@ LCL_ReadAbsoluteFrequency(void)
 static double
 clamp_freq(double freq)
 {
-  if (freq <= MAX_FREQ && freq >= -MAX_FREQ)
+  if (freq <= max_freq_ppm && freq >= -max_freq_ppm)
     return freq;
 
   LOG(LOGS_WARN, LOGF_Local, "Frequency %.1f ppm exceeds allowed maximum", freq);
 
-  return freq >= MAX_FREQ ? MAX_FREQ : -MAX_FREQ;
+  return CLAMP(-max_freq_ppm, freq, max_freq_ppm);
 }
 
 /* ================================================== */

make_release

@@ -1,6 +1,6 @@
 #!/bin/sh
 
-LANG=C
+LANG=C.UTF-8
 export LANG
 
 if [ $# -ne 1 ]; then
@@ -11,7 +11,6 @@ fi
 version=$1
 tag=$version
 subdir=chrony-${version}
-mandate=$(date +'%B %Y')
 
 umask 022
 
@@ -39,29 +38,13 @@ echo $version > version.txt
 
 sed -i -e "s%@@VERSION@@%${version}%" examples/chrony.spec
 
-for m in chronyc.1.in chrony.conf.5.in chronyd.8.in; do
+./configure && make -C doc man txt || exit 1
-  sed -e "s%@VERSION@%${version}%;s%@MAN_DATE@%${mandate}%" \
-    < $m > ${m}_
-  mv -f ${m}_ $m
-done
 
-./configure && make chrony.txt getdate.c || exit 1
+iconv -f utf-8 -t ascii//TRANSLIT < doc/installation.txt > INSTALL
-
+iconv -f utf-8 -t ascii//TRANSLIT < doc/faq.txt > FAQ
-awk '/^[1-9] Installation$/{p=1}
-     /^[1-9]\.. Support for line editing/{exit}; p' chrony.txt | \
-  tail -n +4 > INSTALL
-
-if [ $(wc -l < INSTALL) -gt 120 -o $(wc -l < INSTALL) -lt 85 ]; then
-  echo "INSTALL generated incorrectly?"
-  exit 3
-fi
-
-a2x --lynx -f text doc/faq.adoc || exit 1
-mv doc/faq.text FAQ
-rm -rf doc
 
 make distclean
-rm -f config.h config.log make_release .gitignore
+rm -f make_release .gitignore
 
 cd ..
 tar cv --owner root --group root $subdir | gzip -9 > ${subdir}.tar.gz

ntp_core.c

@@ -602,6 +602,7 @@ NCR_ChangeRemoteAddress(NCR_Instance inst, NTP_Remote_Address *remote_addr)
     close_client_socket(inst);
   else {
     NIO_CloseServerSocket(inst->local_addr.sock_fd);
+    inst->local_addr.ip_addr.family = IPADDR_UNSPEC;
     inst->local_addr.sock_fd = NIO_OpenServerSocket(remote_addr);
   }
 
@@ -800,7 +801,7 @@ transmit_packet(NTP_Mode my_mode, /* The mode this machine wants to be */
                 )
 {
   NTP_Packet message;
-  int leap, auth_len, length, ret, precision;
+  int auth_len, length, ret, precision;
   struct timeval local_receive, local_transmit;
   NTP_int64 ts_fuzz;
 
@@ -822,7 +823,7 @@ transmit_packet(NTP_Mode my_mode, /* The mode this machine wants to be */
   if (my_mode == MODE_CLIENT) {
     /* Don't reveal local time or state of the clock in client packets */
     precision = 32;
-    are_we_synchronised = leap_status = our_stratum = our_ref_id = 0;
+    leap_status = our_stratum = our_ref_id = 0;
     our_ref_time.tv_sec = our_ref_time.tv_usec = 0;
     our_root_delay = our_root_dispersion = 0.0;
   } else {
@@ -858,14 +859,8 @@ transmit_packet(NTP_Mode my_mode, /* The mode this machine wants to be */
     local_receive = *local_rx;
   }
 
-  if (are_we_synchronised) {
-    leap = (int) leap_status;
-  } else {
-    leap = LEAP_Unsynchronised;
-  }
-
   /* Generate transmit packet */
-  message.lvm = NTP_LVM(leap, version, my_mode);
+  message.lvm = NTP_LVM(leap_status, version, my_mode);
   /* Stratum 16 and larger are invalid */
   if (our_stratum < NTP_MAX_STRATUM) {
     message.stratum = our_stratum;
@@ -961,6 +956,7 @@ static void
 transmit_timeout(void *arg)
 {
   NCR_Instance inst = (NCR_Instance) arg;
+  NTP_Local_Address local_addr;
   int sent;
 
   inst->tx_timeout_id = 0;
@@ -996,6 +992,10 @@ transmit_timeout(void *arg)
     inst->local_addr.sock_fd = NIO_OpenClientSocket(&inst->remote_addr);
   }
 
+  /* Don't require the packet to be sent from the same address as before */
+  local_addr.ip_addr.family = IPADDR_UNSPEC;
+  local_addr.sock_fd = inst->local_addr.sock_fd;
+
   /* Check whether we need to 'warm up' the link to the other end by
      sending an NTP exchange to ensure both ends' ARP caches are
      primed.  On loaded systems this might also help ensure that bits
@@ -1009,7 +1009,7 @@ transmit_timeout(void *arg)
        as the reply will be ignored */
     transmit_packet(MODE_CLIENT, inst->local_poll, inst->version, 0, 0,
                     &inst->remote_orig, &inst->local_rx, NULL, NULL,
-                    &inst->remote_addr, &inst->local_addr);
+                    &inst->remote_addr, &local_addr);
 
     inst->presend_done = 1;
 
@@ -1027,7 +1027,7 @@ transmit_timeout(void *arg)
                          &inst->remote_orig,
                          &inst->local_rx, &inst->local_tx, &inst->local_ntp_tx,
                          &inst->remote_addr,
-                         &inst->local_addr);
+                         &local_addr);
 
   ++inst->tx_count;
 
@@ -1184,7 +1184,6 @@ receive_packet(NTP_Packet *message, struct timeval *now, double now_err, NCR_Ins
 
   /* These are the timeval equivalents of the remote epochs */  
   struct timeval remote_receive_tv, remote_transmit_tv;
-  struct timeval remote_reference_tv;
   struct timeval local_average, remote_average;
   double local_interval, remote_interval;
 
@@ -1223,7 +1222,6 @@ receive_packet(NTP_Packet *message, struct timeval *now, double now_err, NCR_Ins
 
   UTI_Int64ToTimeval(&message->receive_ts, &remote_receive_tv);
   UTI_Int64ToTimeval(&message->transmit_ts, &remote_transmit_tv);
-  UTI_Int64ToTimeval(&message->reference_ts, &remote_reference_tv);
 
   /* Check if the packet is valid per RFC 5905, section 8.
      The test values are 1 when passed and 0 when failed. */
@@ -1241,7 +1239,6 @@ receive_packet(NTP_Packet *message, struct timeval *now, double now_err, NCR_Ins
      association if not properly 'up'. */
   test3 = (message->originate_ts.hi || message->originate_ts.lo) &&
           (message->receive_ts.hi || message->receive_ts.lo) &&
-          (message->reference_ts.hi || message->reference_ts.lo) &&
           (message->transmit_ts.hi || message->transmit_ts.lo);
 
   /* Test 4 would check for denied access.  It would always pass as this
@@ -1262,10 +1259,8 @@ receive_packet(NTP_Packet *message, struct timeval *now, double now_err, NCR_Ins
           message->stratum != NTP_INVALID_STRATUM; 
 
   /* Test 7 checks for bad data.  The root distance must be smaller than a
-     defined maximum and the transmit time must not be before the time of
+     defined maximum. */
-     the last synchronisation update. */
+  test7 = pkt_root_delay / 2.0 + pkt_root_dispersion < NTP_MAX_DISPERSION;
-  test7 = pkt_root_delay / 2.0 + pkt_root_dispersion < NTP_MAX_DISPERSION &&
-          UTI_CompareTimevals(&remote_reference_tv, &remote_transmit_tv) < 1;
 
   /* The packet is considered valid if the tests above passed */
   valid_packet = test1 && test2 && test3 && test5 && test6 && test7;
@@ -1353,7 +1348,8 @@ receive_packet(NTP_Packet *message, struct timeval *now, double now_err, NCR_Ins
 
     /* Test D requires that the remote peer is not synchronised to us to
        prevent a synchronisation loop */
-    testD = message->stratum <= 1 || pkt_refid != UTI_IPToRefid(&local_addr->ip_addr);
+    testD = message->stratum <= 1 || REF_GetMode() != REF_ModeNormal ||
+            pkt_refid != UTI_IPToRefid(&local_addr->ip_addr);
   } else {
     offset = delay = dispersion = 0.0;
     sample_time = *now;
@@ -1450,6 +1446,9 @@ receive_packet(NTP_Packet *message, struct timeval *now, double now_err, NCR_Ins
        server and the socket can be closed */
     close_client_socket(inst);
 
+    /* Update the local address */
+    inst->local_addr.ip_addr = local_addr->ip_addr;
+
     requeue_transmit = 1;
   }
 
@@ -2008,6 +2007,14 @@ NCR_GetRemoteAddress(NCR_Instance inst)
 
 /* ================================================== */
 
+uint32_t
+NCR_GetLocalRefid(NCR_Instance inst)
+{
+  return UTI_IPToRefid(&inst->local_addr.ip_addr);
+}
+
+/* ================================================== */
+
 int NCR_IsSyncPeer(NCR_Instance inst)
 {
   return SRC_IsSyncPeer(inst->source);

ntp_core.h

@@ -105,6 +105,8 @@ extern void NCR_IncrementActivityCounters(NCR_Instance inst, int *online, int *o
 
 extern NTP_Remote_Address *NCR_GetRemoteAddress(NCR_Instance instance);
 
+extern uint32_t NCR_GetLocalRefid(NCR_Instance inst);
+
 extern int NCR_IsSyncPeer(NCR_Instance instance);
 
 extern void NCR_AddBroadcastDestination(IPAddr *addr, unsigned short port, int interval);

ntp_io.c

@@ -162,21 +162,21 @@ prepare_socket(int family, int port_number, int client_only)
   /* Make the socket capable of re-using an old address if binding to a specific port */
   if (port_number &&
       setsockopt(sock_fd, SOL_SOCKET, SO_REUSEADDR, (char *)&on_off, sizeof(on_off)) < 0) {
-    LOG(LOGS_ERR, LOGF_NtpIO, "Could not set reuseaddr socket options");
+    LOG(LOGS_ERR, LOGF_NtpIO, "Could not set %s socket option", "SO_REUSEADDR");
     /* Don't quit - we might survive anyway */
   }
   
   /* Make the socket capable of sending broadcast pkts - needed for NTP broadcast mode */
   if (!client_only &&
       setsockopt(sock_fd, SOL_SOCKET, SO_BROADCAST, (char *)&on_off, sizeof(on_off)) < 0) {
-    LOG(LOGS_ERR, LOGF_NtpIO, "Could not set broadcast socket options");
+    LOG(LOGS_ERR, LOGF_NtpIO, "Could not set %s socket option", "SO_BROADCAST");
     /* Don't quit - we might survive anyway */
   }
 
 #ifdef SO_TIMESTAMP
   /* Enable receiving of timestamp control messages */
   if (setsockopt(sock_fd, SOL_SOCKET, SO_TIMESTAMP, (char *)&on_off, sizeof(on_off)) < 0) {
-    LOG(LOGS_ERR, LOGF_NtpIO, "Could not set timestamp socket options");
+    LOG(LOGS_ERR, LOGF_NtpIO, "Could not set %s socket option", "SO_TIMESTAMP");
     /* Don't quit - we might survive anyway */
   }
 #endif
@@ -185,7 +185,7 @@ prepare_socket(int family, int port_number, int client_only)
   /* Allow binding to address that doesn't exist yet */
   if (my_addr_len > 0 &&
       setsockopt(sock_fd, IPPROTO_IP, IP_FREEBIND, (char *)&on_off, sizeof(on_off)) < 0) {
-    LOG(LOGS_ERR, LOGF_NtpIO, "Could not set free bind socket option");
+    LOG(LOGS_ERR, LOGF_NtpIO, "Could not set %s socket option", "IP_FREEBIND");
   }
 #endif
 
@@ -193,7 +193,7 @@ prepare_socket(int family, int port_number, int client_only)
 #ifdef HAVE_IN_PKTINFO
     /* We want the local IP info on server sockets */
     if (setsockopt(sock_fd, IPPROTO_IP, IP_PKTINFO, (char *)&on_off, sizeof(on_off)) < 0) {
-      LOG(LOGS_ERR, LOGF_NtpIO, "Could not set packet info socket option");
+      LOG(LOGS_ERR, LOGF_NtpIO, "Could not set %s socket option", "IP_PKTINFO");
       /* Don't quit - we might survive anyway */
     }
 #endif
@@ -203,18 +203,18 @@ prepare_socket(int family, int port_number, int client_only)
 #ifdef IPV6_V6ONLY
     /* Receive IPv6 packets only */
     if (setsockopt(sock_fd, IPPROTO_IPV6, IPV6_V6ONLY, (char *)&on_off, sizeof(on_off)) < 0) {
-      LOG(LOGS_ERR, LOGF_NtpIO, "Could not set IPV6_V6ONLY socket option");
+      LOG(LOGS_ERR, LOGF_NtpIO, "Could not set %s socket option", "IPV6_V6ONLY");
     }
 #endif
 
 #ifdef HAVE_IN6_PKTINFO
 #ifdef IPV6_RECVPKTINFO
     if (setsockopt(sock_fd, IPPROTO_IPV6, IPV6_RECVPKTINFO, (char *)&on_off, sizeof(on_off)) < 0) {
-      LOG(LOGS_ERR, LOGF_NtpIO, "Could not set IPv6 packet info socket option");
+      LOG(LOGS_ERR, LOGF_NtpIO, "Could not set %s socket option", "IPV6_RECVPKTINFO");
     }
 #else
     if (setsockopt(sock_fd, IPPROTO_IPV6, IPV6_PKTINFO, (char *)&on_off, sizeof(on_off)) < 0) {
-      LOG(LOGS_ERR, LOGF_NtpIO, "Could not set IPv6 packet info socket option");
+      LOG(LOGS_ERR, LOGF_NtpIO, "Could not set %s socket option", "IPV6_PKTINFO");
     }
 #endif
 #endif

ntp_sources.c

@@ -3,7 +3,7 @@
 
  **********************************************************************
  * Copyright (C) Richard P. Curnow  1997-2003
- * Copyright (C) Miroslav Lichvar  2011-2012, 2014
+ * Copyright (C) Miroslav Lichvar  2011-2012, 2014, 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
@@ -53,8 +53,7 @@ typedef struct {
   int pool;                     /* Number of the pool from which was this source
                                    added or INVALID_POOL */
   int tentative;                /* Flag indicating there was no valid response
-                                   yet and the source may be removed if other
+                                   received from the source yet */
-                                   sources from the pool respond first */
 } SourceRecord;
 
 /* Hash table of SourceRecord, its size is a power of two and it's never
@@ -71,6 +70,7 @@ static int auto_start_sources = 0;
 struct UnresolvedSource {
   char *name;
   int port;
+  int random_order;
   int replacement;
   union {
     struct {
@@ -311,7 +311,7 @@ add_source(NTP_Remote_Address *remote_addr, char *name, NTP_Source_Type type, So
       record->remote_addr = NCR_GetRemoteAddress(record->data);
       record->name = name ? Strdup(name) : NULL;
       record->pool = pool;
-      record->tentative = pool != INVALID_POOL ? 1 : 0;
+      record->tentative = 1;
 
       if (auto_start_sources)
         NCR_StartInstance(record->data);
@@ -328,6 +328,7 @@ replace_source(NTP_Remote_Address *old_addr, NTP_Remote_Address *new_addr)
 {
   int slot1, slot2, found;
   SourceRecord *record;
+  struct SourcePool *pool;
 
   find_slot(old_addr, &slot1, &found);
   if (!found)
@@ -341,6 +342,15 @@ replace_source(NTP_Remote_Address *old_addr, NTP_Remote_Address *new_addr)
   NCR_ChangeRemoteAddress(record->data, new_addr);
   record->remote_addr = NCR_GetRemoteAddress(record->data);
 
+  if (!record->tentative) {
+    record->tentative = 1;
+
+    if (record->pool != INVALID_POOL) {
+      pool = ARR_GetElement(pools, record->pool);
+      pool->sources--;
+    }
+  }
+
   /* The hash table must be rebuilt for the new address */
   rehash_records();
 
@@ -358,13 +368,17 @@ process_resolved_name(struct UnresolvedSource *us, IPAddr *ip_addrs, int n_addrs
 {
   NTP_Remote_Address address;
   int i, added;
+  unsigned short first = 0;
+
+  if (us->random_order)
+    UTI_GetRandomBytes(&first, sizeof (first));
 
   for (i = added = 0; i < n_addrs; i++) {
-    DEBUG_LOG(LOGF_NtpSources, "(%d) %s", i + 1, UTI_IPToString(&ip_addrs[i]));
+    address.ip_addr = ip_addrs[((unsigned int)i + first) % n_addrs];
-
-    address.ip_addr = ip_addrs[i];
     address.port = us->port;
 
+    DEBUG_LOG(LOGF_NtpSources, "(%d) %s", i + 1, UTI_IPToString(&address.ip_addr));
+
     if (us->replacement) {
       if (replace_source(&us->replace_source, &address) != NSR_AlreadyInUse)
         break;
@@ -507,6 +521,7 @@ NSR_AddSourceByName(char *name, int port, int pool, NTP_Source_Type type, Source
   us = MallocNew(struct UnresolvedSource);
   us->name = Strdup(name);
   us->port = port;
+  us->random_order = 0;
   us->replacement = 0;
   us->new_source.type = type;
   us->new_source.params = *params;
@@ -648,6 +663,11 @@ resolve_source_replacement(SourceRecord *record)
   us = MallocNew(struct UnresolvedSource);
   us->name = Strdup(record->name);
   us->port = record->remote_addr->port;
+  /* If there never was a valid reply from this source (e.g. it was a bad
+     replacement), ignore the order of addresses from the resolver to not get
+     stuck to a pair of addresses if the order doesn't change, or a group of
+     IPv4/IPv6 addresses if the resolver prefers inaccessible IP family */
+  us->random_order = record->tentative;
   us->replacement = 1;
   us->replace_source = *record->remote_addr;
 
@@ -733,6 +753,26 @@ static void remove_tentative_pool_sources(int pool)
     rehash_records();
 }
 
+/* ================================================== */
+
+uint32_t
+NSR_GetLocalRefid(IPAddr *address)
+{
+  NTP_Remote_Address remote_addr;
+  int slot, found;
+
+  remote_addr.ip_addr = *address;
+  remote_addr.port = 0;
+
+  find_slot(&remote_addr, &slot, &found);
+  if (!found)
+    return 0;
+
+  return NCR_GetLocalRefid(get_record(slot)->data);
+}
+
+/* ================================================== */
+
 /* This routine is called by ntp_io when a new packet arrives off the network,
    possibly with an authentication tail */
 void
@@ -752,20 +792,21 @@ NSR_ProcessReceive(NTP_Packet *message, struct timeval *now, double now_err, NTP
       return;
 
     if (record->tentative) {
-      /* First reply from a pool source */
+      /* This was the first valid reply from the source */
       record->tentative = 0;
 
-      assert(record->pool != INVALID_POOL);
+      if (record->pool != INVALID_POOL) {
-      pool = (struct SourcePool *)ARR_GetElement(pools, record->pool);
+        pool = ARR_GetElement(pools, record->pool);
-      pool->sources++;
+        pool->sources++;
 
-      DEBUG_LOG(LOGF_NtpSources, "pool %s has %d confirmed sources",
+        DEBUG_LOG(LOGF_NtpSources, "pool %s has %d confirmed sources",
-                record->name, pool->sources);
+                  record->name, pool->sources);
 
-      /* If the number of sources reached the configured maximum, remove
+        /* If the number of sources from the pool reached the configured
-         the tentative sources added from this pool */
+           maximum, remove the remaining tentative sources */
-      if (pool->sources >= pool->max_sources)
+        if (pool->sources >= pool->max_sources)
-        remove_tentative_pool_sources(record->pool);
+          remove_tentative_pool_sources(record->pool);
+      }
     }
   } else {
     NCR_ProcessUnknown(message, now, now_err, remote_addr, local_addr, length);

ntp_sources.h

@@ -83,6 +83,9 @@ extern void NSR_HandleBadSource(IPAddr *address);
 /* Procedure to resolve all names again */
 extern void NSR_RefreshAddresses(void);
 
+/* Procedure to get local reference ID corresponding to a source */
+extern uint32_t NSR_GetLocalRefid(IPAddr *address);
+
 /* This routine is called by ntp_io when a new packet arrives off the network */
 extern void NSR_ProcessReceive(NTP_Packet *message, struct timeval *now, double now_err, NTP_Remote_Address *remote_addr, NTP_Local_Address *local_addr, int length);
 

pktlength.c

@@ -67,7 +67,7 @@ static const struct request_length request_lengths[] = {
   REQ_LENGTH_ENTRY(modify_maxupdateskew, null), /* MODIFY_MAXUPDATESKEW */
   REQ_LENGTH_ENTRY(logon, null),                /* LOGON */
   REQ_LENGTH_ENTRY(settime, manual_timestamp),  /* SETTIME */
-  REQ_LENGTH_ENTRY(local, null),                /* LOCAL */
+  { 0, 0 },                                     /* LOCAL */
   REQ_LENGTH_ENTRY(manual, null),               /* MANUAL */
   REQ_LENGTH_ENTRY(null, n_sources),            /* N_SOURCES */
   REQ_LENGTH_ENTRY(source_data, source_data),   /* SOURCE_DATA */
@@ -112,6 +112,7 @@ static const struct request_length request_lengths[] = {
   REQ_LENGTH_ENTRY(null, server_stats),         /* SERVER_STATS */
   REQ_LENGTH_ENTRY(client_accesses_by_index,
                    client_accesses_by_index),   /* CLIENT_ACCESSES_BY_INDEX2 */
+  REQ_LENGTH_ENTRY(local, null),                /* LOCAL2 */
 };
 
 static const uint16_t reply_lengths[] = {

refclock.c

@@ -87,7 +87,7 @@ struct RCL_Instance_Record {
   SRC_Instance source;
 };
 
-/* Array of RCL_Instance_Record */
+/* Array of pointers to RCL_Instance_Record */
 static ARR_Instance refclocks;
 
 static LOG_FileID logfileid;
@@ -114,13 +114,13 @@ static void filter_add_dispersion(struct MedianFilter *filter, double dispersion
 static RCL_Instance
 get_refclock(unsigned int index)
 {
-  return (RCL_Instance)ARR_GetElement(refclocks, index);
+  return *(RCL_Instance *)ARR_GetElement(refclocks, index);
 }
 
 void
 RCL_Initialise(void)
 {
-  refclocks = ARR_CreateInstance(sizeof (struct RCL_Instance_Record));
+  refclocks = ARR_CreateInstance(sizeof (RCL_Instance));
 
   CNF_AddRefclocks();
 
@@ -148,6 +148,7 @@ RCL_Finalise(void)
     filter_fini(&inst->filter);
     Free(inst->driver_parameter);
     SRC_DestroyInstance(inst->source);
+    Free(inst);
   }
 
   if (ARR_GetSize(refclocks) > 0) {
@@ -162,8 +163,10 @@ int
 RCL_AddRefclock(RefclockParameters *params)
 {
   int pps_source = 0;
+  RCL_Instance inst;
 
-  RCL_Instance inst = ARR_GetNewElement(refclocks);
+  inst = MallocNew(struct RCL_Instance_Record);
+  *(RCL_Instance *)ARR_GetNewElement(refclocks) = inst;
 
   if (strcmp(params->driver_name, "SHM") == 0) {
     inst->driver = &RCL_SHM_driver;
@@ -470,15 +473,16 @@ RCL_AddPulse(RCL_Instance instance, struct timeval *pulse_time, double second)
     double root_delay, root_dispersion, distance;
     uint32_t ref_id;
 
-    /* Ignore the pulse if we are not well synchronized */
+    /* Ignore the pulse if we are not well synchronized and the local
+       reference is not active */
 
     REF_GetReferenceParams(&cooked_time, &is_synchronised, &leap, &stratum,
         &ref_id, &ref_time, &root_delay, &root_dispersion);
     distance = fabs(root_delay) / 2 + root_dispersion;
 
-    if (!is_synchronised || distance >= 0.5 / rate) {
+    if (leap == LEAP_Unsynchronised || distance >= 0.5 / rate) {
       DEBUG_LOG(LOGF_Refclock, "refclock pulse ignored second=%.9f sync=%d dist=%.9f",
-          second, is_synchronised, distance);
+          second, leap != LEAP_Unsynchronised, distance);
       /* Drop also all stored samples */
       filter_reset(&instance->filter);
       return 0;
@@ -528,9 +532,10 @@ pps_stratum(RCL_Instance instance, struct timeval *tv)
   REF_GetReferenceParams(tv, &is_synchronised, &leap, &stratum,
       &ref_id, &ref_time, &root_delay, &root_dispersion);
 
-  /* Don't change our stratum if local stratum is active
+  /* Don't change our stratum if the local reference is active
      or this is the current source */
-  if (ref_id == instance->ref_id || REF_IsLocalActive())
+  if (ref_id == instance->ref_id ||
+      (!is_synchronised && leap != LEAP_Unsynchronised))
     return stratum - 1;
 
   /* Or the current source is another PPS refclock */ 

reference.c

@@ -3,7 +3,7 @@
 
  **********************************************************************
  * Copyright (C) Richard P. Curnow  1997-2003
- * Copyright (C) Miroslav Lichvar  2009-2015
+ * 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
@@ -45,6 +45,8 @@
 static int are_we_synchronised;
 static int enable_local_stratum;
 static int local_stratum;
+static int local_orphan;
+static double local_distance;
 static NTP_Leap our_leap_status;
 static int our_leap_sec;
 static int our_stratum;
@@ -230,7 +232,7 @@ REF_Initialise(void)
 
   correction_time_ratio = CNF_GetCorrectionTimeRatio();
 
-  enable_local_stratum = CNF_AllowLocalReference(&local_stratum);
+  enable_local_stratum = CNF_AllowLocalReference(&local_stratum, &local_orphan, &local_distance);
 
   leap_timeout_id = 0;
   leap_in_progress = 0;
@@ -1157,29 +1159,37 @@ REF_GetReferenceParams
  double *root_dispersion
 )
 {
-  double elapsed;
+  double elapsed, dispersion;
-  double extra_dispersion;
 
   assert(initialised);
 
   if (are_we_synchronised) {
+    UTI_DiffTimevalsToDouble(&elapsed, local_time, &our_ref_time);
+    dispersion = our_root_dispersion +
+      (our_skew + fabs(our_residual_freq) + LCL_GetMaxClockError()) * elapsed;
+  } else {
+    dispersion = 0.0;
+  }
+
+  /* Local reference is active when enabled and the clock is not synchronised
+     or the root distance exceeds the threshold */
+
+  if (are_we_synchronised &&
+      !(enable_local_stratum && our_root_delay / 2 + dispersion > local_distance)) {
 
     *is_synchronised = 1;
 
     *stratum = our_stratum;
 
-    UTI_DiffTimevalsToDouble(&elapsed, local_time, &our_ref_time);
-    extra_dispersion = (our_skew + fabs(our_residual_freq) + LCL_GetMaxClockError()) * elapsed;
-
     *leap_status = !leap_in_progress ? our_leap_status : LEAP_Unsynchronised;
     *ref_id = our_ref_id;
     *ref_time = our_ref_time;
     *root_delay = our_root_delay;
-    *root_dispersion = our_root_dispersion + extra_dispersion;
+    *root_dispersion = dispersion;
 
   } else if (enable_local_stratum) {
 
-    *is_synchronised = 1;
+    *is_synchronised = 0;
 
     *stratum = local_stratum;
     *ref_id = NTP_REFID_LOCAL;
@@ -1220,13 +1230,27 @@ REF_GetReferenceParams
 int
 REF_GetOurStratum(void)
 {
-  if (are_we_synchronised) {
+  struct timeval now_cooked, ref_time;
-    return our_stratum;
+  int synchronised, stratum;
-  } else if (enable_local_stratum) {
+  NTP_Leap leap_status;
-    return local_stratum;
+  uint32_t ref_id;
-  } else {
+  double root_delay, root_dispersion;
+
+  SCH_GetLastEventTime(&now_cooked, NULL, NULL);
+  REF_GetReferenceParams(&now_cooked, &synchronised, &leap_status, &stratum,
+                         &ref_id, &ref_time, &root_delay, &root_dispersion);
+
+  return stratum;
+}
+
+/* ================================================== */
+
+int
+REF_GetOrphanStratum(void)
+{
+  if (!enable_local_stratum || !local_orphan)
     return NTP_MAX_STRATUM;
-  }
+  return local_stratum;
 }
 
 /* ================================================== */
@@ -1257,10 +1281,12 @@ REF_ModifyMakestep(int limit, double threshold)
 /* ================================================== */
 
 void
-REF_EnableLocal(int stratum)
+REF_EnableLocal(int stratum, double distance, int orphan)
 {
   enable_local_stratum = 1;
-  local_stratum = stratum;
+  local_stratum = CLAMP(1, stratum, NTP_MAX_STRATUM - 1);
+  local_distance = distance;
+  local_orphan = !!orphan;
 }
 
 /* ================================================== */
@@ -1273,14 +1299,6 @@ REF_DisableLocal(void)
 
 /* ================================================== */
 
-int
-REF_IsLocalActive(void)
-{
-  return !are_we_synchronised && enable_local_stratum;
-}
-
-/* ================================================== */
-
 #define LEAP_SECOND_CLOSE 5
 
 int REF_IsLeapSecondClose(void)
@@ -1309,52 +1327,34 @@ int REF_IsLeapSecondClose(void)
 void
 REF_GetTrackingReport(RPT_TrackingReport *rep)
 {
-  double elapsed;
-  double extra_dispersion;
   struct timeval now_raw, now_cooked;
   double correction;
+  int synchronised;
 
   LCL_ReadRawTime(&now_raw);
   LCL_GetOffsetCorrection(&now_raw, &correction, NULL);
   UTI_AddDoubleToTimeval(&now_raw, correction, &now_cooked);
 
-  rep->ref_id = NTP_REFID_UNSYNC;
+  REF_GetReferenceParams(&now_cooked, &synchronised,
+                         &rep->leap_status, &rep->stratum,
+                         &rep->ref_id, &rep->ref_time,
+                         &rep->root_delay, &rep->root_dispersion);
+
+  if (rep->stratum == NTP_MAX_STRATUM)
+    rep->stratum = 0;
+
   rep->ip_addr.family = IPADDR_UNSPEC;
-  rep->stratum = 0;
-  rep->leap_status = our_leap_status;
-  rep->ref_time.tv_sec = 0;
-  rep->ref_time.tv_usec = 0;
   rep->current_correction = correction;
   rep->freq_ppm = LCL_ReadAbsoluteFrequency();
   rep->resid_freq_ppm = 0.0;
   rep->skew_ppm = 0.0;
-  rep->root_delay = 0.0;
-  rep->root_dispersion = 0.0;
   rep->last_update_interval = last_ref_update_interval;
   rep->last_offset = last_offset;
   rep->rms_offset = sqrt(avg2_offset);
 
-  if (are_we_synchronised) {
+  if (synchronised) {
-    
-    UTI_DiffTimevalsToDouble(&elapsed, &now_cooked, &our_ref_time);
-    extra_dispersion = (our_skew + fabs(our_residual_freq) + LCL_GetMaxClockError()) * elapsed;
-    
-    rep->ref_id = our_ref_id;
     rep->ip_addr = our_ref_ip;
-    rep->stratum = our_stratum;
-    rep->ref_time = our_ref_time;
     rep->resid_freq_ppm = 1.0e6 * our_residual_freq;
     rep->skew_ppm = 1.0e6 * our_skew;
-    rep->root_delay = our_root_delay;
-    rep->root_dispersion = our_root_dispersion + extra_dispersion;
-
-  } else if (enable_local_stratum) {
-
-    rep->ref_id = NTP_REFID_LOCAL;
-    rep->ip_addr.family = IPADDR_UNSPEC;
-    rep->stratum = local_stratum;
-    rep->ref_time = now_cooked;
-    rep->root_dispersion = LCL_GetSysPrecisionAsQuantum();
   }
-
 }

reference.h

@@ -165,6 +165,9 @@ REF_SetUnsynchronised(void);
    synchronised */
 extern int REF_GetOurStratum(void);
 
+/* Return stratum of the local reference if orphan mode is enabled */
+extern int REF_GetOrphanStratum(void);
+
 /* Return the current skew */
 extern double REF_GetSkew(void);
 
@@ -174,9 +177,8 @@ extern void REF_ModifyMaxupdateskew(double new_max_update_skew);
 /* Modify makestep settings */
 extern void REF_ModifyMakestep(int limit, double threshold);
 
-extern void REF_EnableLocal(int stratum);
+extern void REF_EnableLocal(int stratum, double distance, int orphan);
 extern void REF_DisableLocal(void);
-extern int REF_IsLocalActive(void);
 
 /* Check if current raw or cooked time is close to a leap second
    and is better to discard any measurements */

reports.h

@@ -29,6 +29,7 @@
 
 #include "sysincl.h"
 #include "addressing.h"
+#include "ntp.h"
 
 #define REPORT_INVALID_OFFSET 0x80000000
 
@@ -50,8 +51,8 @@ typedef struct {
 typedef struct {
   uint32_t ref_id;
   IPAddr ip_addr;
-  unsigned long stratum;
+  int stratum;
-  unsigned long leap_status;
+  NTP_Leap leap_status;
   struct timeval ref_time;
   double current_correction;
   double last_offset;

sched.c

@@ -179,7 +179,8 @@ SCH_AddInputFileHandler
   /* Don't want to allow the same fd to register a handler more than
      once without deleting a previous association - this suggests
      a bug somewhere else in the program. */
-  assert(!FD_ISSET(fd, &read_fds));
+  if (FD_ISSET(fd, &read_fds))
+    assert(0);
 
   ++n_read_fds;
   
@@ -208,7 +209,8 @@ SCH_RemoveInputFileHandler(int fd)
   assert(initialised);
 
   /* Check that a handler was registered for the fd in question */
-  assert(FD_ISSET(fd, &read_fds));
+  if (!FD_ISSET(fd, &read_fds))
+    assert(0);
 
   --n_read_fds;
 
@@ -717,7 +719,6 @@ SCH_MainLoop(void)
 void
 SCH_QuitProgram(void)
 {
-  assert(initialised);
   need_to_exit = 1;
 }
 

sources.c

@@ -73,6 +73,7 @@ typedef enum {
   SRC_BAD_DISTANCE,     /* Has root distance longer than allowed maximum */
   SRC_WAITS_STATS,      /* Others have bad stats, selection postponed */
   SRC_STALE,            /* Has older samples than others */
+  SRC_ORPHAN,           /* Has stratum equal or larger than orphan stratum */
   SRC_FALSETICKER,      /* Doesn't agree with others */
   SRC_JITTERY,          /* Scatter worse than other's dispersion (not used) */
   SRC_WAITS_SOURCES,    /* Not enough sources, selection postponed */
@@ -429,9 +430,11 @@ SRC_UpdateReachability(SRC_Instance inst, int reachable)
     REF_SetUnsynchronised();
   }
 
-  /* Try to replace NTP sources that are unreachable or falsetickers */
+  /* Try to replace NTP sources that are unreachable, falsetickers, or
-  if (inst->type == SRC_NTP && (inst->status == SRC_FALSETICKER ||
+     have root distance larger than the allowed maximum */
-      (!inst->reachability && inst->reachability_size == SOURCE_REACH_BITS))) {
+  if (inst->type == SRC_NTP &&
+      ((!inst->reachability && inst->reachability_size == SOURCE_REACH_BITS) ||
+       inst->status == SRC_FALSETICKER || inst->status == SRC_BAD_DISTANCE)) {
     NSR_HandleBadSource(inst->ip_addr);
   }
 }
@@ -605,6 +608,7 @@ SRC_SelectSource(SRC_Instance updated_inst)
   int n_badstats_sources, max_sel_reach, max_badstat_reach, sel_req_source;
   int depth, best_depth, trust_depth, best_trust_depth;
   int combined, stratum, min_stratum, max_score_index;
+  int orphan_stratum, orphan_source;
   double src_offset, src_offset_sd, src_frequency, src_skew;
   double src_root_delay, src_root_dispersion;
   double best_lo, best_hi, distance, sel_src_distance, max_score;
@@ -678,6 +682,9 @@ SRC_SelectSource(SRC_Instance updated_inst)
       max_sel_reach = sources[i]->reachability;
   }
 
+  orphan_stratum = REF_GetOrphanStratum();
+  orphan_source = INVALID_SOURCE;
+
   for (i = 0; i < n_sources; i++) {
     if (sources[i]->status != SRC_OK)
       continue;
@@ -692,7 +699,56 @@ SRC_SelectSource(SRC_Instance updated_inst)
       continue;
     }
 
+    /* When the local reference is configured with the orphan option, NTP
+       sources that have stratum equal to the configured local stratum are
+       considered to be orphans (i.e. serving local time while not being
+       synchronised with real time) and are excluded from the normal source
+       selection.  Sources with stratum larger than the local stratum are
+       considered to be directly on indirectly synchronised to an orphan and
+       are always ignored.
+
+       If no selectable source is available and all orphan sources have
+       reference IDs larger than the local ID, no source will be selected and
+       the local reference mode will be activated at some point, i.e. this host
+       will become an orphan.  Otherwise, the orphan source with the smallest
+       reference ID will be selected.  This ensures a group of servers polling
+       each other (with the same orphan configuration) which have no external
+       source can settle down to a state where only one server is serving its
+       local unsychronised time and others are synchronised to it. */
+
+    if (si->stratum >= orphan_stratum && sources[i]->type == SRC_NTP) {
+      sources[i]->status = SRC_ORPHAN;
+
+      if (si->stratum == orphan_stratum && sources[i]->reachability &&
+          (orphan_source == INVALID_SOURCE ||
+           sources[i]->ref_id < sources[orphan_source]->ref_id))
+        orphan_source = i;
+
+      continue;
+    }
+
     ++n_sel_sources;
+  }
+
+  /* If no selectable source is available, consider the orphan source */
+  if (!n_sel_sources && orphan_source != INVALID_SOURCE) {
+    uint32_t local_ref_id = NSR_GetLocalRefid(sources[orphan_source]->ip_addr);
+
+    if (!local_ref_id) {
+      LOG(LOGS_ERR, LOGF_Sources, "Unknown local refid in orphan mode");
+    } else if (sources[orphan_source]->ref_id < local_ref_id) {
+      sources[orphan_source]->status = SRC_OK;
+      n_sel_sources = 1;
+      DEBUG_LOG(LOGF_Sources, "selecting orphan refid=%"PRIx32,
+                sources[orphan_source]->ref_id);
+    }
+  }
+
+  for (i = 0; i < n_sources; i++) {
+    if (sources[i]->status != SRC_OK)
+      continue;
+
+    si = &sources[i]->sel_info;
 
     j1 = n_endpoints;
     j2 = j1 + 1;
@@ -1252,6 +1308,7 @@ SRC_ReportSource(int index, RPT_SourceReport *report, struct timeval *now)
       case SRC_BAD_STATS:
       case SRC_BAD_DISTANCE:
       case SRC_STALE:
+      case SRC_ORPHAN:
       case SRC_WAITS_STATS:
         report->state = RPT_UNREACH;
         break;

stubs.c

@@ -230,6 +230,12 @@ NSR_InitiateSampleBurst(int n_good_samples, int n_total_samples,
   return 0;
 }
 
+uint32_t
+NSR_GetLocalRefid(IPAddr *address)
+{
+  return 0;
+}
+
 int
 NSR_TakeSourcesOnline(IPAddr *mask, IPAddr *address)
 {

sys_linux.c

@@ -50,6 +50,7 @@
 #ifdef FEAT_SCFILTER
 #include <sys/prctl.h>
 #include <seccomp.h>
+#include <termios.h>
 #ifdef FEAT_PHC
 #include <linux/ptp_clock.h>
 #endif

test/simulation/105-ntpauth

@@ -43,7 +43,7 @@ check_packet_interval || test_fail
 client_conf="keyfile tmp/keys"
 clients=2
 peers=2
-max_sync_time=300
+max_sync_time=500
 base_delay="$default_base_delay (* -1 (equal 0.1 from 3) (equal 0.1 to 1))"
 client_lpeer_options="key 1"
 client_rpeer_options="key 1"

test/simulation/110-chronyc

@@ -13,7 +13,7 @@ check_chronyd_exit || test_fail
 
 check_chronyc_output "^Reference ID    : 192\.168\.123\.1 \(192\.168\.123\.1\)
 Stratum         : 2
-Ref time \(UTC\)  : Fri Jan  1 00:1.:.. 2010
+Ref time \(UTC\)  : Fri Jan 01 00:1.:.. 2010
 System time     : 0\.0000..... seconds (slow|fast) of NTP time
 Last offset     : [+-]0\.000...... seconds
 RMS offset      : 0\.000...... seconds

test/simulation/115-cmdmontime

@@ -10,11 +10,11 @@ grep -q 'HAVE_LONG_TIME_T 1' ../../config.h || test_skip
 limit=2
 client_server_options="noselect"
 client_conf="local stratum 1"
-chronyc_start="0.5"
+chronyc_start="1.5"
 chronyc_conf="tracking"
 
 for year in `seq 1850 100 2300`; do
-	date="Jan  1 00:00:00 $year"
+	date="Jan 01 00:00:00 $year"
 	export CLKNETSIM_START_DATE=$(date -d "$date UTC" +'%s')
 	run_test || test_fail
 	check_chronyd_exit || test_fail

test/simulation/121-orphan

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+. ./test.common
+
+test_start "orphan option"
+
+server_strata=3
+server_conf="local stratum 5 orphan
+server 192.168.123.1
+server 192.168.123.2
+server 192.168.123.3"
+max_sync_time=500
+chronyc_start=300
+chronyc_conf="tracking"
+time_rms_limit=5e-4
+
+run_test || test_fail
+check_chronyd_exit || test_fail
+check_source_selection || test_fail
+check_sync || test_fail
+check_chronyc_output "^.*Stratum *: 7.*$" || test_fail
+
+test_pass

test/unit/Makefile.in

@@ -33,6 +33,9 @@ clean:
 	rm -f *.o $(TESTS)
 	rm -rf .deps
 
+distclean: clean
+	rm -f Makefile
+
 .deps:
 	@mkdir .deps
 

util.c

@@ -362,6 +362,7 @@ UTI_IPToRefid(IPAddr *ip)
 uint32_t
 UTI_IPToHash(IPAddr *ip)
 {
+  static uint32_t seed = 0;
   unsigned char *addr;
   unsigned int i, len;
   uint32_t hash;
@@ -379,10 +380,15 @@ UTI_IPToHash(IPAddr *ip)
       return 0;
   }
 
-  for (i = 0, hash = 0; i < len; i++)
+  /* Include a random seed in the hash to randomize collisions
+     and order of addresses in hash tables */
+  while (!seed)
+    UTI_GetRandomBytes(&seed, sizeof (seed));
+
+  for (i = 0, hash = seed; i < len; i++)
     hash = 71 * hash + addr[i];
 
-  return hash;
+  return hash + seed;
 }
 
 /* ================================================== */
@@ -801,9 +807,10 @@ UTI_FloatNetworkToHost(Float f)
 
   x = ntohl(f.f);
 
-  exp = (x >> FLOAT_COEF_BITS) - FLOAT_COEF_BITS;
+  exp = x >> FLOAT_COEF_BITS;
   if (exp >= 1 << (FLOAT_EXP_BITS - 1))
       exp -= 1 << FLOAT_EXP_BITS;
+  exp -= FLOAT_COEF_BITS;
 
   coef = x % (1U << FLOAT_COEF_BITS);
   if (coef >= 1 << (FLOAT_COEF_BITS - 1))