xntpd 3.3b from UDel

11 files changed, 5840 insertions, 0 deletions

diff --git a/usr.sbin/xntpd/doc/README.irig b/usr.sbin/xntpd/doc/README.irig
new file mode 100644
index 0000000..f293f4c
--- /dev/null
+++ b/usr.sbin/xntpd/doc/README.irig
@@ -0,0 +1,306 @@
+             Audio IRIG Receiver for Precision Timekeeping
+
+                         Revised 20 September 1993
+
+Note: This information file is included in both the BSD audio driver
+distribution (bsd_audio.tar.Z) and NTP Version 3 distribution
+(xntp3.tar.Z) as the file README.irig. Both distributions can be
+obtained via anonymous ftp from louie.udel.edu in the directory pub/ntp.
+
+1. Introduction
+
+This software distribution includes modifications to the BSD audio
+driver for the Sun SPARCstation written by Van Jacobson and
+collaborators at Lawrence Berkeley National Laboratory. The
+modifications provide for the connection of a standard Inter-Range
+Instrumentation Group (IRIG) timecode signal generator and the decoding
+of the signal to produce data sufficient to synchronize a host clock to
+the IRIG signal. There are several timing receivers now on the market
+that can produce IRIG signals, including those made by Austron,
+TrueTime, Odetics and Spectracom, among others. These data can be used
+to precisely synchronize the host computer clock to within a few
+microseconds without requiring level converters or pulse generators
+necessary with the one-pulse-per-second signals also produced by these
+receivers. The current implementation of the Network Time Protocol
+Version 3 supports the modified BSD driver when installed in the SunOS
+4.1.x kernel.
+
+The specific IRIG signal format supported by the driver is designated
+IRIG-B. It consists of an amplitude-modulated 1000-Hz sinewave, where
+each symbol is encoded as ten full carrier cycles, or 10 ms in duration.
+The symbols are distinguished using a pulse-width code, where 2 ms
+corresponds to logic zero, 5 ms to logic one and 8 ms to a position
+identifier used for symbol synchronization. The complete IRIG-B message
+consists of a frame of ten fields, each field consisting of a nine
+information symbols followed by a position identifier for a total frame
+duration of one second. The first symbol in the frame is also a position
+identifier to facilitate frame synchronization.
+
+The IRIG-B signal encodes the day of year and time of day in binary-
+coded decimal (BCD) format, together with a set of control functions,
+which are not used by the driver, but included in the raw binary
+timecode. Either the BCD timecode or the combined raw timecode and BCD
+timecode can be returned in response to a read() system call. The BCD
+timecode is in handy ASCII format: "ddd hh:mm:ss*" for convenience in
+client programs. In this format the "*" status character is " " when the
+driver is operating normally and "?" when errors may be present (see
+below). In order to reduce residual errors to the greatest extent
+possible, the driver computes a timestamp based on the value of the
+kernel clock at the on-time epoch of the IRIG-B signal. In addition, the
+driver automatically adjusts for slowly varying amplitude levels of the
+IRIG-B signal and suppresses noise transients.
+
+In operation the IRIG driver interprets the IRIG-B signal in real time,
+synchronizes to the signal, demodulates the data bits and prepares the
+data to be read later. At the on-time epoch a timestamp is captured from
+the kernel clock and adjusted for the phase of the IRIG carrier signal
+relative to the 8-kHz codec sample clock. When a client program issues a
+read() request, the most recent timecode data, including a status byte
+and the corrected timestamp, are stored in a structure and returned to
+the caller. Depending on the frequency with which the driver is called,
+this may result in old data or duplicate data or even invalid data,
+should the driver be called before it has computed its first timestamp.
+
+In practice, the resulting ambiguity causes few problems. The caller
+converts the ASCII timecode returned by a read() system call to Unix
+timeval format and subtracts it from the kernel timestamp provided by
+the driver. The result is an adjustment that can be subtracted from the
+kernel time, as returned in a gettimeofday() call, for example, to
+correct for the deviation between IRIG time and kernel time. The result
+can always be relied on to within plus/minus 128 microseconds, the audio
+codec sampling interval, and ordinarily to within a few microseconds, as
+determined by the interpolation algorithm.
+
+2. Programming Interface
+
+The IRIG driver modifications are integrated in the BSD audio driver
+bsd_audio.c without affecting its usual functions in transmitting and
+receiving ordinary speech, except when enabled by specific ioctl()
+system calls. However, the driver cannot be used for both speech and
+IRIG signals at the same time. Once activated by a designated ioctl()
+call, the driver remains active until it is explicitly deactivated by
+another ioctl() call. This allows applications to configure the audio
+device and pass the pre-configured driver to other applications. Since
+the driver is currently only a receiver, it does not affect the
+operation of the BSD audio output driver.
+
+Data are read using the standard read() system call. Since the output
+formats have constant lengths, the application receives the data into a
+fixed-length buffer or structure. The read() call never blocks; it
+simply returns the most recent IRIG data received during the last
+second. It may happen that, due to unavoidable race conditions in the
+kernel, data for other than the most recent second are returned. The
+driver's internal data structure is updated as an atomic unit; thus, the
+entire structure is valid, even if it contains old data. This should
+cause no problems, since in the intended application the driver is
+called at regular intervals by a time-synchronization daemon such as
+NTP. The daemon can determine the validity of the time indication by
+checking the timecode or status byte returned with the data.
+
+The header file bsd_audioirig.h  defines the irig_time structure and
+ioctl() codes used by the driver. Following are those codes specific to
+the IRIG function of the driver. Unless indicated otherwise, the (third)
+argument of the ioctl() system call points to an integer or string.
+
+AUDIO_IRIG_OPEN
+
+     This command activates the IRIG receiver. The audio driver must be
+     opened with this command before other commands can be issued. The
+     argument is ignored. When the IRIG receiver is initialized, all
+     internal data are purged and any buffered data are lost.
+
+AUDIO_IRIG_CLOSE
+
+     This command deactivates the IRIG receiver. The argument is
+     ignored. The buffers are purged and any buffered time data are
+     lost. The original BSD audio driver functions are enabled and it
+     resumes operating normally.
+
+AUDIO_IRIG_SETFORMAT
+
+     The argument is a pointer to an integer designating the output
+     format for the IRIG data. There are currently two formats defined,
+     0 (default) and 1. If an invalid format is selected, the default
+     format is used.
+
+The data returned by a read() system call in format 0 is a character
+string in the format "ddd hh:mm:ss*\n", which consists of 13 ASCII
+characters followed by a newline terminator for a total of 14
+characters. The "*" status character is an ASCII space " " if the status
+byte determined by the driver is zero and "?" if not. This format is
+intended to be used with simple user programs that care only about the
+time to the nearest second.
+The data returned by a read() system call in format 1 is a structure
+defined in the bsd_audioirig.h header file:
+
+     struct irig_time {
+          struct timeval stamp;    /* timestamp */
+          u_char bits[13];         /* 100 irig data bits */
+          u_char status;           /* status byte */
+          char time[14];           /* time string */
+     };
+
+The irig-time.stamp is a pair of 32-bit longwords in Unix timeval
+format, as defined in the sys/time.h header file. The first word is the
+number of seconds since 1 January 1970, while the second is the number
+of microseconds in the current second. The timestamp is captured at the
+most recent on-time instant of the IRIG timecode and applies to all
+other values returned in the irig_time structure.
+
+The irig_time.bits[13] is a vector of 13 bytes to hold the 100-bit,
+zero-padded raw binary timecode, packed 8 symbols per byte. The symbol
+encoding maps IRIG one to 1 and both IRIG zero and IRIG position
+identifier to 0. The order of encoding is illustrated by the following
+diagram (the padding bits are represented by xxxx, which are set to
+zero):
+
+IRIG symbol number  00000000001111111111 . . . 8888889999999999xxxx
+                    01234567890123456789 . . . 4567890123456789xxxx
+                    -----------------------------------------------
+bits byte number    <--00--><--01--><----     ----><--11--><--12-->
+bits bit in byte    01234567012345670123 . . . 45670123456701234567
+
+The irig_time.status is a single byte with bits defined in the
+bsd_audioirig.h header file. In ordinary operation all bits of the
+status byte are zero and the " " status character is set in the ASCII
+timecode. If any of these bits are nonzero, the "?" status character is
+set in the ASCII timecode.
+
+AUDIO_IRIG_BADSIGNAL
+
+     The signal amplitude is outside tolerance limits, either in
+     amplitude or modulation depth. The indicated time may or may not be
+     in error. If the signal is too high, it may be clipped by the
+     codec, so that the pulse width cannot be reliably determined. If
+     too low, it may be obscured by noise. The nominal expectation is
+     that the peak amplitude of the signal be maintained by the codec
+     AGC at about 10 dB below the clipping level and that the modulation
+     index be at least 0.5 (6 dB).
+
+AUDIO_IRIG_BADDATA
+
+     An invalid hex code (A through F) has been found where BCD data is
+     expected. The ASCII representation of the invalid code is set to
+     "?". Errors of this type are most likely due to noise on the IRIG
+     signal due to ground loops, coupling to other noise sources, etc.
+
+AUDIO_IRIG_BADSYNC
+
+     A code element has been found where a position identifier should be
+     or a position identifier has been found where a code element should
+     be. The time is meaningless and should be disregarded. Errors of
+     this type can be due to severe noise on the IRIG signal due to
+     ground loops, coupling to other noise sources, etc., or during
+     initial acquisition of the signal.
+
+AUDIO_IRIG_BADCLOCK
+
+     Some IRIG timecode generators can indicate whether or not the
+     generator is operating correctly or synchronized to its source of
+     standard time using a designated field in the raw binary timecode.
+     Where such information is available and the IRIG decoder can detect
+     it, this bit is set when the generator reports anything except
+     normal operating conditions.
+
+AUDIO_IRIG_OLDDATA
+
+     The IRIG time has not changed since the last time it was returned
+     in a read() call. This is not normally considered an error, unless
+     it persists for longer than a few seconds, in which case it
+     probably indicates a hardware problem.
+
+The irig_time.time[14] vector is a character string in the format "ddd
+hh:mm:ss*\0", which consists of 13 ASCII characters followed by a zero
+terminator. The "*" status character is an ASCII space " " if the status
+byte is zero and "?" if not. This format is identical to format 0,
+except that in format 1 the time string is null-terminated.
+
+2.1. Programming Example
+
+The following pseudo-code demonstrates how the IRIG receiver may be used
+by a simple user program. Of course, real code should include error
+checking after each call to ensure the driver is communicating properly.
+It should also verify that the correct fields in the structure are being
+filled by the read() call.
+
+     include "bsd_audioirig.h"
+
+     int format = 1;
+     struct irig_time it;
+
+     Audio_fd = open("/dev/audio", O_RDONLY);
+     ioctl(Audio_fd, AUDIO_IRIG_OPEN, NULL);
+     ioctl(Audio_fd, AUDIO_IRIG_SETFORMAT,&format);
+     while (condition)
+          read(Audio_fd, &it, sizeof(it);
+          printf("%s\n", it.time);
+     ioctl(Audio_fd, AUDIO_IRIG_CLOSE, NULL);
+     close(Audio_fd);
+
+3. Implementation and Configuration Notes
+
+The signal level produced by most IRIG-equipped radios is on the order
+of a few volts peak-peak, which is far larger than the audio codec can
+accept; therefore, an attenuator in the form of a voltage divider is
+needed. The codec can handle IRIG signals at the microphone input from
+4.2mV to 230mV peak-peak. A suitable attenuator conists of a series-
+connected 100K-Ohm resistor at the input and a parallel-connected 1K-Ohm
+resistor at the output, both contained along with suitable connectors in
+a small aluminum box. The exact values of these resistors are not
+critical, since the IRIG driver includes an automatic level-adjustment
+capability.
+
+For the most accurate time using the IRIG signal and a particular radio,
+it may be necessary to adjust the time1 parameter of the fudge command
+to compensate for the codec delay and any additional delay due to IRIG
+processing in the radio itself. Since the codec samples at an 8-kHz
+rate, the average delay is about 62 usec; however, the delays due to the
+radios and IRIG signals themselves can vary. For instance, in the
+Austron recievers the IRIG delay is essentially zero, while in the
+Spectracom receivers the delay is about 240 usec relative to the 1-pps
+signal. In addition, the poll interval can be reduced from the usual 64
+seconds to 16 seconds to reduce wander of the local hardware clock.
+Finally, the prefer parameter can be used to bias the clock-selection
+algorithm to favor the IRIG time, which is ordinarily the best time
+available. For example, the following two lines in the NTP configuration
+file ntp.conf are appropriate for the Spectracom Netclock/1 WWVB
+Synchronized Clock with IRIG Option:
+
+server 127.127.6.0 prefer minpoll 4 maxpoll 4 # irig audio decoder
+fudge 127.127.6.0 time1 0.0005
+
+The time1 value of .0005 s (500 usec) was determined by actual
+measurement. Since the IRIG delay in Austron receivers is essentially
+zero, the fudge command is not necessary with these receivers. The
+correct value in case of other radios may have to be determined by
+actual measurement. A convenient way of doing this is to configure the
+PPSPPS feature in the NTP Version 3 distribution and adjust time1 until
+the 1-pps signal and IRIG signal both show the same offset.
+
+The modified BSD driver includes both the modified driver itself
+bsd_audio.c and the IRIG header file bsd_audioirig.h, as well as
+modified header files bsd_audiovar.h and bsd_audioio.h. The driver is
+installed in the same way as described in the BSD driver documentation,
+with the addition of the following define in the kernel configuration
+file:
+
+options   AUDIO_IRIG          # IRIG driver
+
+This causes the IRIG code to be included in the BSD driver, as well as a
+C-coded codec interrupt routine which replaces the assembly-coded
+routine and provides the IRIG functionality. While the C-coded routine
+is somewhat slower than the assembly-coded routine, the extra overhead
+is not expected to be significant. Note that the IRIG driver calls the
+kernel routine microtime() as included in the ppsclock directory of the
+NTP Version 3 distribution xntp3. It is highly recommended that this
+routine be installed in the kernel configuration as well. The
+instructions for doing this are contained in the ppsclock directory of
+the xntp3 distribution.
+
+Roy LeCates <lecates@udel.edu> and David Mills <mills@udel.edu>
+Electrical Engineering Department
+University of Delaware
+Newark, DE 19716
+302 831 8247 fax 302 831 4316
+
+24 August 1993
diff --git a/usr.sbin/xntpd/doc/README.kern b/usr.sbin/xntpd/doc/README.kern
new file mode 100644
index 0000000..1b791c3
--- /dev/null
+++ b/usr.sbin/xntpd/doc/README.kern
@@ -0,0 +1,775 @@
+          Unix Kernel Modifications for Precision Timekeeping
+
+                       Revised 3 December 1993
+
+Note: This information file is included in the distributions for the
+SunOS, Ultrix and OSF/1 kernels and in the NTP Version 3 distribution
+(xntp3.tar.Z) as the file README.kern. Availability of the kernel
+distributions, which involve licensed code, will be announced
+separately. The NTP Version 3 distribution can be obtained via anonymous
+ftp from louie.udel.edu in the directory pub/ntp. In order to utilize
+all features of this distribution, the NTP version number should be 3.3
+or later.
+
+1. Introduction
+
+This memo describes modifications to certain SunOS, Ultrix and OSF/1
+kernel software that manage the system clock and timer functions. They
+provide improved accuracy and stability through the use of a disciplined
+clock interface for use with the Network Time Protocol (NTP) or similar
+time-synchronization protocol. In addition, for the DEC 3000 AXP (Alpha)
+and DECstation 5000/240 machines, the modifications provide improved
+precision within one microsecond (us) (SunOS 4.1.x already does provide
+precision to this order). The NTP Version 3 daemon xntpd operates with
+these kernel modifications to provide synchronization in principle to
+within this order, but in practice this is limited by the short-term
+stability of the timer oscillator to within the order of 100 usec.
+
+This memo describes the principles behind the design and operation of
+the new software. There are three versions: one that operates with the
+SunOS 4.1.x kernels, a second that operates with the Ultrix 4.x kernels
+and a third that operates with the OSF/1 V1.x kernels. A detailed
+description of the variables and algorithms is given in the hope that
+similar functionality can be incorporated in Unix kernels for other
+machines. The algorithms involve only minor changes to the system clock
+and interval timer routines and include interfaces for application
+programs to learn the system clock status and certain statistics of the
+time-synchronization process. Detailed installation instructions are
+given in a companion README.install file included in the kernel
+distributions. The kernel software itself is not provided for public
+distribution, since it involves licensed code. Detailed instructions on
+how to obtain it for either SunOS, Ultrix or OSF/1 will be given
+separately.
+
+The principal feature added to the Unix kernels is to change the way the
+system clock is controlled, in order to provide precision time and
+frequency adjustments. Another feature utilizes an undocumented bus-
+cycle counter in the DEC 3000 AXP and DECstation 5000/240 to provide
+precise time to the microsecond. This feature can in principle be used
+with any DEC machine that has this counter, although this has not been
+verified. The addition of these features does not affect the operation
+of existing Unix system calls such as gettimeofday(), settimeofday() and
+adjtime(); however, if the new features are in use, the operations of
+adjtime() are controlled instead by a new system call ntp_adjtime().
+
+Most Unix programs read the system clock using the gettimeofday() system
+call, which returns only the system time and timezone data. For some
+applications it is useful to know the maximum error of the reported time
+due to all causes, including clock reading errors, oscillator frequency
+errors and accumulated latencies on the path to a primary reference
+source. However, the new software can adjust the system clock to
+compensate for its intrinsic frequency error, so that the timing errors
+expected in normal operation will usually be much less than the maximum
+error. The user application interface includes a new system call
+ntp_gettime(), which returns the system time, as well as the maximum
+error and estimated error. This interface is intended to support
+applications that need such things, including distributed file systems,
+multimedia teleconferencing and other real-time applications. The
+protocol daemon application interface includes a new system call
+ntp_adjtime(), which can be used to read and write kernel variables used
+for precision timekeeping, including time and frequency adjustments,
+controlling time constant, leap-second warning and related data.
+
+In this memo, NTP Version 3 and the Unix implementation xntpd are used
+as an example application of the new system calls for use by a protocol
+daemon. In principle, the new system calls can be used by other
+protocols and daemon implementations as well. Even in cases where the
+local time is maintained by periodic exchanges of messages at relatively
+long intervals, such as using the NIST Automated Computer Time Service,
+the ability to precisely adjust the local clock frequency simplifies the
+synchronization procedures and allows the call frequency to be
+considerably reduced.
+
+2. Design Principles
+
+In order to understand how the new software works, it is useful to
+consider how most Unix systems maintain the system time. In the original
+design a hardware timer interrupts the kernel at a fixed rate: 100 Hz in
+the SunOS kernel, 256 Hz in the Ultrix kernel and 1024 Hz in the OSF/1
+kernel. Since the Ultrix kernel rate does not evenly divide one second
+in microseconds, the kernel adds 64 microseconds once each second, so
+the timescale consists of 255 advances of 3906 usec plus one of 3970
+usec. Similarly, the OSF/1 kernel adds 576 usec once each second, so its
+timescale consists of 1023 advances of 976 usec plus one of 1552 usec.
+
+In all Unix kernels considered in this memo, it is possible to slew the
+system clock to a new offset using the standard Unix adjtime() system
+call. To do this the clock frequency is changed by adding or subtracting
+a fixed amount (tickadj) at each timer interrupt (tick) for a calculated
+number of ticks. Since this calculation involves dividing the requested
+offset by tickadj, it is possible to slew to a new offset with a
+precision only of tickadj, which is usually in the neighborhood of 5 us,
+but sometimes much higher. This results in an amortization error which
+can accumulate to unacceptable levels, so that special provisions must
+be made in the clock adjustment procedures of the protocol daemon.
+
+In order to maintain the system clock within specified bounds with this
+scheme, it is necessary to call adjtime() on a regular basis. For
+instance, let the bound be set at 100 usec, which is a reasonable value
+for NTP-synchronized hosts on a local network, and let the onboard
+oscillator tolerance be 100 parts-per-million (ppm), which is a
+reasonably conservative assumption. This requires that adjtime() be
+called at intervals not exceeding 1 second (s), which is in fact what
+the unmodified NTP software daemon does.
+
+In the new software this scheme is replaced by another that extends the
+low-order bits of the system clock to provide very precise clock
+adjustments. At each timer interrupt a precisely calibrated quantity is
+added to the composite time value and overflows handled as required. The
+quantity is computed from the measured clock offset and in addition a
+frequency adjustment, which is automatically calculated from previous
+time adjustments. This implementation operates as an adaptive-parameter
+first-order, type-II, phase-lock loop (PLL), which in principle provides
+precision control of the system clock phase to within +-1 us and
+frequency to within +-5 nanoseconds (ns) per day.
+
+This PLL model is identical to the one implemented in NTP, except that
+in NTP the software daemon has to simulate the PLL using only the
+original adjtime() system call. The daemon is considerably complicated
+by the need to parcel time adjustments at frequent intervals in order to
+maintain the accuracy to specified bounds. The modified kernel routines
+do this directly, allowing vast gobs of ugly daemon code to be avoided
+at the expense of only a small amount of new code in the kernel. In
+fact, the amount of code added to the kernel for the new scheme is about
+the amount needed to implement the old scheme. A new system call
+ntp_adjtime(), which operates in a way similar to the original
+adjtime(), is called only as each new time update is determined, which
+in NTP occurs at intervals of from 16 s to 1024 s. In addition, doing
+the frequency correction in the kernel means that the system time runs
+true even if the daemon were to cease operation or the network paths to
+the primary reference source fail. The addition of the new ntp_adjtime()
+system call does not affect the original adjtime() system call, which
+continues to operate in its traditional fashion. However, the two system
+calls canot be used at the same time; only one of the two should be used
+on any given system.
+
+It is the intent in the design that settimeofday() be used for changes
+in system time greater than +-128 ms. It has been the Internet
+experience that the need to change the system time in increments greater
+than +-128 milliseconds is extremely rare and is usually associated with
+a hardware or software malfunction or system reboot. Once the system
+clock has been set in this way, the ntp_adjtime() system call is used to
+provide periodic updates including the time offset, maximum error,
+estimated error and PLL time constant. With NTP the update interval
+depends on the measured error and time constant; however, the scheme is
+quite forgiving and neither moderate loss of updates nor variations in
+the length of the polling interval are serious.
+
+In addition, the kernel adjusts the maximum error to grow by an amount
+equal to the oscillator frequency tolerance times the elapsed time since
+the last update. The default engineering parameters have been optimized
+for intervals not greater than about 16 s. For longer intervals the PLL
+time constant can be adjusted to optimize the dynamic response up to
+intervals of 1024 s. Normally, this is automatically done by NTP. In any
+case, if updates are suspended, the PLL coasts at the frequency last
+determined, which usually results in errors increasing only to a few
+tens of milliseconds over a day.
+
+The new code needs to know the initial frequency offset and time
+constant for the PLL, and the daemon needs to know the current frequency
+offset computed by the kernel for monitoring purposes. These data are
+exchanged between the kernel and protocol daemon using ntp_adjtime() as
+documented later in this memo. Provisions are made to exchange related
+timing information, such as the maximum error and estimated error,
+between the kernel and daemon and between the kernel and application
+programs.
+
+In the DEC 3000 AXP, DECstation 5000/240 and possibly other DEC
+machines there is an undocumented hardware register that counts system
+bus cycles at a rate of 25 MHz. The new kernel microtime() routine tests
+for the CPU type and, in the case of these machines, use this register
+to interpolate system time between hardware timer interrupts. This
+results in a precision of +-1 us for all time values obtained via the
+gettimeofday() and ntp_gettime() system calls. These routines call the
+microtime() routine, which returns the actual interpolated value but
+does not change the kernel time variable. Therefore, other kernel
+routines that access the kernel time variable directly and do not call
+either gettimeofday(), ntp_gettime() or microtime() will continue their
+present behavior. The microtime() feature is independent of other
+features described here and is operative even if the kernel PLL or new
+system calls have not been implemented.
+
+While any protocol daemon can in principle be modified to use the new
+system calls, the most likely will be users of the NTP Version 3 daemon
+xntpd. The xntpd code determines whether the new system calls are
+implemented and automatically reconfigures as required. When
+implemented, the daemon reads the frequency offset from a file and
+provides it and the initial time constant via ntp_adjtime(). In
+subsequent calls to ntp_adjtime(), only the time adjustment and time
+constant are affected. The daemon reads the frequency from the kernel
+using ntp_adjtime() at intervals of about one hour and writes it to the
+system log file. This information is recovered when the daemon is
+restarted after reboot, for example, so the sometimes extensive training
+period to learn the frequency separately for each system can be avoided.
+
+3. Kernel Interfaces
+
+This section describes the kernel interfaces to the protocol daemon and
+user applications. The ideas are based on suggestions from Jeff Mogul
+and Philip Gladstone and a similar interface designed by the latter. It
+is important to point out that the functionality of the original Unix
+adjtime() system call is preserved, so that the modified kernel will
+work as the unmodified one should the kernel PLL not be in use. In this
+case the ntp_adjtime() system call can still be used to read and write
+kernel variables that might be used by a protocol daemon other than NTP,
+for example.
+
+3.1. The ntp_gettime() System Call
+
+The syntax and semantics of the ntp_gettime() call are given in the
+following fragment of the timex.h header file. This file is identical in
+the SunOS, Ultrix and OSF/1 kernel distributions. Note that the timex.h
+file calls the syscall.h system header file, which must be modified to
+define the SYS_ntp_gettime system call specific to each system type. The
+kernel distributions include directions on how to do this.
+
+/*
+ * This header file defines the Network Time Protocol (NTP) interfaces
+ * for user and daemon application programs. These are implemented using
+ * private system calls and data structures and require specific kernel
+ * support.
+ *
+ * NAME
+ *   ntp_gettime - NTP user application interface
+ *
+ * SYNOPSIS
+ *   #include <sys/timex.h>
+ *
+ *   int system call(SYS_ntp_gettime, tptr)
+ *
+ *   int SYS_ntp_gettime      defined in syscall.h header file
+ *   struct ntptimeval *tptr  pointer to ntptimeval structure
+ *
+ * NTP user interface - used to read kernel clock values
+ * Note: maximum error = NTP synch distance = dispersion + delay / 2;
+ * estimated error = NTP dispersion.
+ */
+struct ntptimeval {
+     struct timeval time;     /* current time */
+     long maxerror;           /* maximum error (usec) */
+     long esterror;           /* estimated error (usec) */
+};
+
+The ntp_gettime() system call returns three values in the ntptimeval
+structure: the current time in unix timeval format plus the maximum and
+estimated errors in microseconds. While the 32-bit long data type limits
+the error quantities to something more than an hour, in practice this is
+not significant, since the protocol itself will declare an
+unsynchronized condition well below that limit. If the protocol computes
+either of these values in excess of 16 seconds, they are clamped to that
+value and the local clock declared unsynchronized.
+
+Following is a detailed description of the ntptimeval structure members.
+
+struct timeval time;
+
+     This member is set to the current system time, expressed as a Unix
+     timeval structure. The timeval structure consists of two 32-bit
+     words, one for the number of seconds past 1 January 1970 and the
+     other the number of microseconds past the most recent second's
+     epoch.
+
+long maxerror;
+
+     This member is set to the value of the time_maxerror kernel
+     variable, which establishes the maximum error of the indicated time
+     relative to the primary reference source, in microseconds. This
+     variable can also be set and read by the ntp_adjtime() system call.
+     For NTP, the value is determined as the synchronization distance,
+     which is equal to the root dispersion plus one-half the root delay.
+     It is increased by a small amount (time_tolerance) each second to
+     reflect the clock frequency tolerance. This variable is computed by
+     the time-synchronization daemon and the kernel and returned in a
+     ntp_gettime() system call, but is otherwise not used by the kernel.
+
+long esterror;
+
+     This member is set to the value of the time_esterror kernel
+     variable, which establishes the expected error of the indicated
+     time relative to the primary reference source, in microseconds.
+     This variable can also be set and read by the ntp_adjtime() system
+     call. For NTP, the value is determined as the root dispersion,
+     which represents the best estimate of the actual error of the
+     system clock based on its past behavior, together with observations
+     of multiple clocks within the peer group. This variable is computed
+     by the time-synchronization daemon and returned in a ntp_gettime()
+     system call, but is otherwise not used by the kernel.
+
+3.2. The ntp_adjtime() System Call
+
+The syntax and semantics of the ntp_adjtime() call is given in the
+following fragment of the timex.h header file. Note that, as in the
+ntp_gettime() system call, the the syscall.h system header file must be
+modified to define the SYS_ntp_adjtime system call specific to each
+system type.
+
+/*
+ * NAME
+ *   ntp_adjtime - NTP daemon application interface
+ *
+ * SYNOPSIS
+ *   #include <sys/timex.h>
+ *
+ *   int system call(SYS_ntp_adjtime, mode, tptr)
+ *
+ *   int SYS_ntp_adjtime      defined in syscall.h header file
+ *   struct timex *tptr       pointer to timex structure
+ *
+ * NTP daemon interface - used to discipline kernel clock oscillator
+ */
+struct timex {
+     int mode;                /* mode selector */
+     long offset;             /* time offset (usec) */
+     long frequency;          /* frequency offset (scaled ppm) */
+     long maxerror;           /* maximum error (usec) */
+     long esterror;           /* estimated error (usec) */
+     int status;              /* clock command/status */
+     long time_constant;      /* pll time constant */
+     long precision;          /* clock precision (usec) (read only) */
+     long tolerance;          /* clock frequency tolerance (ppm)
+                               * (read only)
+                               */
+};
+
+The ntp_adjtime() system call is used to read and write certain time-
+related kernel variables summarized in this and subsequent sections.
+Writing these variables can only be done in superuser mode. To write a
+variable, the mode structure member is set with one or more bits, one of
+which is assigned each of the following variables in turn. The current
+values for all variables are returned in any case; therefore, a mode
+argument of zero means to return these values without changing anything.
+
+Following is a description of the timex structure members.
+
+int mode;
+
+     This is a bit-coded variable selecting one or more structure
+     members, with one bit assigned each member. If a bit is set, the
+     value of the associated member variable is copied to the
+     corresponding kernel variable; if not, the member is ignored. The
+     bits are assigned as given in the following fragment of the timex.h
+     header file. Note that the precision and tolerance are intrinsic
+     properties of the kernel configuration and cannot be changed.
+
+     /*
+      * Mode codes (timex.mode)
+      */
+     #define ADJ_OFFSET       0x0001    /* time offset */
+     #define ADJ_FREQUENCY    0x0002    /* frequency offset */
+     #define ADJ_MAXERROR     0x0004    /* maximum time error */
+     #define ADJ_ESTERROR     0x0008    /* estimated time error */
+     #define ADJ_STATUS       0x0010    /* clock status */
+     #define ADJ_TIMECONST    0x0020    /* pll time constant */
+
+long offset;
+
+     If selected, this member (scaled) replaces the value of the
+     time_offset kernel variable, which defines the current time offset
+     of the phase-lock loop. The value must be in the range +-512 ms in
+     the present implementation. If so, the clock status is
+     automatically set to TIME_OK.
+
+long time_constant;
+
+     If selected, this member replaces the value of the time_constant
+     kernel variable, which establishes the bandwidth of "stiffness" of
+     the kernel PLL. The value is used as a shift, with the effective
+     PLL time constant equal to a multiple of (1 << time_constant), in
+     seconds. The optimum value for the time_constant variable is
+     log2(update_interval) - 4, where update_interval is the nominal
+     interval between clock updates, in seconds. With an ordinary crystal
+     oscillator the optimum value for time_constant is about 2, giving
+     an update_interval of 4 (64 s). Values of time_constant between zero
+     and 2 can be used if quick convergence is necessary; values between
+     2 and 6 can be used to reduce network load, but at a modest cost in
+     accuracy. Values above 6 are appropriate only if a precision
+     oscillator is available.
+
+long frequency;
+
+     If selected, this member (scaled) replaces the value of the
+     time_frequency kernel variable, which establishes the intrinsic
+     frequency of the local clock oscillator. This variable is scaled by
+     (1 << SHIFT_USEC) in parts-per-million (ppm), giving it a maximum
+     value of about +-31 ms/s and a minimum value (frequency resolution)
+     of about 2e-11, which is appropriate for even the best quartz
+     oscillator.
+
+long maxerror;
+
+     If selected, this member replaces the value of the time_maxerror
+     kernel variable, which establishes the maximum error of the
+     indicated time relative to the primary reference source, in
+     microseconds. This variable can also be read by the ntp_gettime()
+     system call. For NTP, the value is determined as the
+     synchronization distance, which is equal to the root dispersion
+     plus one-half the root delay. It is increased by a small amount
+     (time_tolerance) each second to reflect the clock frequency
+     tolerance. This variable is computed by the time-synchronization
+     daemon and the kernel and returned in a ntp_gettime() system call,
+     but is otherwise not used by the kernel.
+
+long esterror;
+
+     If selected, this member replaces the value of the time_esterror
+     kernel variable, which establishes the expected error of the
+     indicated time relative to the primary reference source, in
+     microseconds. This variable can also be read by the ntp_gettime()
+     system call. For NTP, the value is determined as the root
+     dispersion, which represents the best estimate of the actual error
+     of the system clock based on its past behavior, together with
+     observations of multiple clocks within the peer group. This
+     variable is computed by the time-synchronization daemon and
+     returned in a ntp_gettime() system call, but is otherwise not used
+     by the kernel.
+
+int status;
+
+     If selected, this member replaces the value of the time_status
+     kernel variable, which records whether the clock is synchronized,
+     waiting for a leap second, etc. In order to set this variable
+     explicitly, either (a) the current clock status is TIME_OK or (b)
+     the member value is TIME_BAD; that is, the ntp_adjtime() call can
+     always set the clock to the unsynchronized state or, if the clock
+     is running correctly, can set it to any state. In any case, the
+     ntp_adjtime() call always returns the current state in this member,
+     so the caller can determine whether or not the request succeeded.
+
+long precision;
+
+     This member is set equal to the time_precision kernel in
+     microseconds variable upon return from the system call. The
+     time_precision variable cannot be written. This variable represents
+     the maximum error in reading the system clock, which is ordinarily
+     equal to the kernel variable tick, 10000 usec in the SunOS kernel,
+     3906 usec in Ultrix kernel and 976 usec in the OSF/1 kernel.
+     However, in cases where the time can be interpolated with
+     microsecond resolution, such as in the SunOS kernel and modified
+     Ultrix and OSF/1 kernels, the precision is specified as 1 usec.
+     This variable is computed by the kernel for use by the time-
+     synchronization daemon, but is otherwise not used by the kernel.
+
+long tolerance;
+
+     This member is set equal to the time_tolerance kernel variable in
+     parts-per-million (ppm) upon return from the system call. The
+     time_tolerance variable cannot be written. This variable represents
+     the maximum frequency error or tolerance of the particular platform
+     and is a property of the architecture and manufacturing process.
+
+3.3. Command/Status Codes
+
+The kernel routines use the system clock status variable time_status,
+which records whether the clock is synchronized, waiting for a leap
+second, etc. The value of this variable is returned as the result code
+by both the ntp_gettime() and ntp_adjtime() system calls. In addition,
+it can be explicitly read and written using the ntp_adjtime() system
+call, but can be written only in superuser mode. Values presently
+defined in the timex.h header file are as follows:
+
+/*
+ * Clock command/status codes (timex.status)
+ */
+#define TIME_OK     0         /* clock synchronized */
+#define TIME_INS    1         /* insert leap second */
+#define TIME_DEL    2         /* delete leap second */
+#define TIME_OOP    3         /* leap second in progress */
+#define TIME_BAD    4         /* clock not synchronized */
+
+A detailed description of these codes as used by the leap-second state
+machine is given later in this memo. In case of a negative result code,
+the kernel has intercepted an invalid address or (in case of the
+ntp_adjtime() system call), a superuser violation.
+
+4. Technical Summary
+
+In order to more fully understand the workings of the PLL, a stand-alone
+simulator kern.c is included in the kernel distributions. This is an
+implementation of an adaptive-parameter, first-order, type-II phase-lock
+loop. The system clock is implemented using a set of variables and
+algorithms defined in the simulator and driven by explicit offsets
+generated by the simulator. The algorithms include code fragments
+identical to those in the modified kernel routines and operate in the
+same way, but the operations can be understood separately from any
+licensed source code into which these fragments may be integrated. The
+code segments themselves are not derived from any licensed code.
+
+4.1. PLL Simulation
+
+In the simulator the hardupdate() fragment is called by ntp_adjtime() as
+each update is computed to adjust the system clock phase and frequency.
+Note that the time constant is in units of powers of two, so that
+multiplies can be done by simple shifts. The phase variable is computed
+as the offset multiplied by the time constant. Then, the time since the
+last update is computed and clamped to a maximum (for robustness) and to
+zero if initializing. The offset is multiplied (sorry about the ugly
+multiply) by the result and by the square of the time constant and then
+added to the frequency variable. Finally, the frequency variable is
+clamped not to exceed the tolerance. Note that all shifts are assumed to
+be positive and that a shift of a signed quantity to the right requires
+a little dance.
+
+With the defines given, the maximum time offset is determined by the
+size in bits of the long type (32) less the SHIFT_UPDATE scale factor or
+18 bits (signed). The scale factor is chosen so that there is no loss of
+significance in later steps, which may involve a right shift up to 14
+bits. This results in a maximum offset of about +-130 ms. Since
+time_constant must be greater than or equal to zero, the maximum
+frequency offset is determined by the SHIFT_KF (20) scale factor, or
+about +-130 ppm. In the addition step, the value of offset * mtemp is
+represented in 18 + 10 = 28 bits, which will not overflow a long add.
+There could be a loss of precision due to the right shift of up to eight
+bits, since time_constant is bounded at 6. This results in a net worst-
+case frequency error of about 2^-16 us or well down into the oscillator
+phase noise. While the time_offset value is assumed checked before
+entry, the time_phase variable is an accumulator, so is clamped to the
+tolerance on every call. This helps to damp transients before the
+oscillator frequency has been determined, as well as to satisfy the
+correctness assertions if the time-synchronization protocol comes
+unstuck.
+
+The hardclock() fragment is inserted in the hardware timer interrupt
+routine at the point the system clock is to be incremented. Previous to
+this fragment the time_update variable has been initialized to the value
+computed by the adjtime() system call in the stock Unix kernel, normally
+the value of tick plus/minus the tickadj value, which is usually in the
+order of 5 microseconds. When the kernel PLL is in use, adjtime() is
+not, so the time_update value at this point is the value of tick. This
+value, the phase adjustment (time_adj) and the clock phase (time_phase)
+are summed and the total tested for overflow of the microsecond. If an
+overflow occurs, the microsecond (tick) is incremented or decremented,
+depending on the sign of the overflow.
+
+The second_overflow() fragment is inserted at the point where the
+microseconds field of the system time variable is being checked for
+overflow. On rollover of the second the maximum error is increased by
+the tolerance and the time offset is divided by the phase weight
+(SHIFT_KG) and time constant. The time offset is then reduced by the
+result and the result is scaled and becomes the value of the phase
+adjustment. The phase adjustment is then corrected for the calculated
+frequency offset and a fixed offset determined from the fixtick variable
+in some kernel implementations. On rollover of the day, the leap-warning
+indicator is checked and the apparent time adjusted +-1 s accordingly.
+The microtime() routine insures that the reported time is always
+monotonically increasing.
+
+The simulator has been used to check the PLL operation over the design
+envelope of +-128 ms in time error and +-100 ppm in frequency error.
+This confirms that no overflows occur and that the loop initially
+converges in about 15 minutes for timer interrupt rates from 50 Hz to
+1024 Hz. The loop has a normal overshoot of about seven percent and a
+final convergence time of several hours, depending on the initial time
+and frequency error.
+
+4.2. Leap Seconds
+
+It does not seem generally useful in the user application interface to
+provide additional details private to the kernel and synchronization
+protocol, such as stratum, reference identifier, reference timestamp and
+so forth. It would in principle be possible for the application to
+independently evaluate the quality of time and project into the future
+how long this time might be "valid." However, to do that properly would
+duplicate the functionality of the synchronization protocol and require
+knowledge of many mundane details of the platform architecture, such as
+the subnet configuration, reachability status and related variables.
+However, for the curious, the ntp_adjtime() system call can be used to
+reveal some of these mysteries.
+
+However, the user application may need to know whether a leap second is
+scheduled, since this might affect interval calculations spanning the
+event. A leap-warning condition is determined by the synchronization
+protocol (if remotely synchronized), by the timecode receiver (if
+available), or by the operator (if awake). This condition is set by the
+protocol daemon on the day the leap second is to occur (30 June or 31
+December, as announced) by specifying in a ntp_adjtime() system call a
+clock status of either TIME_DEL, if a second is to be deleted, or
+TIME_INS, if a second is to be inserted. Note that, on all occasions
+since the inception of the leap-second scheme, there has never been a
+deletion occasion. If the value is TIME_DEL, the kernel adds one second
+to the system time immediately following second 23:59:58 and resets the
+clock status to TIME_OK. If the value is TIME_INS, the kernel subtracts
+one second from the system time immediately following second 23:59:59
+and resets the clock status to TIME_OOP, in effect causing system time
+to repeat second 59. Immediately following the repeated second, the
+kernel resets the clock status to TIME_OK.
+
+Depending upon the system call implementation, the reported time during
+a leap second may repeat (with the TIME_OOP return code set to advertise
+that fact) or be monotonically adjusted until system time "catches up"
+to reported time. With the latter scheme the reported time will be
+correct before and shortly after the leap second (depending on the
+number of microtime() calls during the leap second itself), but freeze
+or slowly advance during the leap second itself. However, Most programs
+will probably use the ctime() library routine to convert from timeval
+(seconds, microseconds) format to tm format (seconds, minutes,...). If
+this routine is modified to use the ntp_gettime() system call and
+inspect the return code, it could simply report the leap second as
+second 60.
+
+To determine local midnight without fuss, the kernel simply finds the
+residue of the time.tv_sec value mod 86,400, but this requires a messy
+divide. Probably a better way to do this is to initialize an auxiliary
+counter in the settimeofday() routine using an ugly divide and increment
+the counter at the same time the time.tv_sec is incremented in the timer
+interrupt routine. For future embellishment.
+
+4.2. Kernel Variables
+
+The following kernel variables are defined by the new code:
+
+long time_offset = 0;         /* time adjustment (us) */
+
+     This variable is used by the PLL to adjust the system time in small
+     increments. It is scaled by (1 << SHIFT_UPDATE) in binary
+     microseconds. The maximum value that can be represented is about +-
+     512 ms and the minimum value or precision is one microsecond.
+
+long time_constant = 0;       /* pll time constant */
+
+     This variable determines the bandwidth or "stiffness" of the PLL.
+     It is used as a shift, with the effective value in positive powers
+     of two. The default value (0) corresponds to a PLL time constant of
+     about 4 minutes.
+
+long time_tolerance = MAXFREQ; /* frequency tolerance (ppm) */
+
+     This variable represents the maximum frequency error or tolerance
+     of the particular platform and is a property of the architecture.
+     It is expressed as a positive number greater than zero in parts-
+     per-million (ppm). The default MAXFREQ (100) is appropriate for
+     conventional workstations.
+
+long time_precision = 1000000 / HZ; /* clock precision (us) */
+
+     This variable represents the maximum error in reading the system
+     clock. It is expressed as a positive number greater than zero in
+     microseconds and is usually based on the number of microseconds
+     between timer interrupts, 3906 usec for the Ultrix kernel, 976 usec
+     for the OSF/1 kernel. However, in cases where the time can be
+     interpolated between timer interrupts with microsecond resolution,
+     such as in the unmodified SunOS kernel and modified Ultrix and
+     OSF/1 kernels, the precision is specified as 1 usec. This variable
+     is computed by the kernel for use by the time-synchronization
+     daemon, but is otherwise not used by the kernel.
+
+long time_maxerror;           /* maximum error */
+
+     This variable establishes the maximum error of the indicated time
+     relative to the primary reference source, in microseconds. For NTP,
+     the value is determined as the synchronization distance, which is
+     equal to the root dispersion plus one-half the root delay. It is
+     increased by a small amount (time_tolerance) each second to reflect
+     the clock frequency tolerance. This variable is computed by the
+     time-synchronization daemon and the kernel, but is otherwise not
+     used by the kernel.
+
+long time_esterror;           /* estimated error */
+
+     This variable establishes the expected error of the indicated time
+     relative to the primary reference source, in microseconds. For NTP,
+     the value is determined as the root dispersion, which represents
+     the best estimate of the actual error of the system clock based on
+     its past behavior, together with observations of multiple clocks
+     within the peer group. This variable is computed by the time-
+     synchronization daemon and returned in system calls, but is
+     otherwise not used by the kernel.
+
+long time_phase = 0;          /* phase offset (scaled us) */
+long time_freq = 0;           /* frequency offset (scaled ppm) */
+time_adj = 0;                 /* tick adjust (scaled 1 / HZ) */
+
+     These variables control the phase increment and the frequency
+     increment of the system clock at each tick. The time_phase variable
+     is scaled by (1 << SHIFT_SCALE) (24) in microseconds, giving a
+     maximum adjustment of about +-128 us/tick and a resolution of about
+     60 femtoseconds/tick. The time_freq variable is scaled by (1 <<
+     SHIFT_KF) in parts-per-million (ppm), giving it a maximum value of
+     over +-2000 ppm and a minimum value (frequency resolution) of about
+     1e-5 ppm. The time_adj variable is the actual phase increment in
+     scaled microseconds to add to time_phase once each tick. It is
+     computed from time_phase and time_freq once per second.
+
+long time_reftime = 0;        /* time at last adjustment (s) */
+
+     This variable is the second's portion of the system time on the
+     last call to adjtime(). It is used to adjust the time_freq variable
+     as the time since the last update increases.
+
+int fixtick = 1000000 % HZ;   /* amortization factor */
+
+     In some systems such as the Ultrix and OSF/1 kernels, the local
+     clock runs at some frequency that does not divide the number of
+     microseconds in the second. In order that the clock runs at a
+     precise rate, it is necessary to introduce an amortization factor
+     into the local timescale, in effect a leap-multimicrosecond. This
+     is not a new kernel variable, but a new use of an existing kernel
+     variable.
+
+4.3. Architecture Constants
+
+Following is a list of the important architecture constants that
+establish the response and stability of the PLL and provide maximum
+bounds on behavior in order to satisfy correctness assertions made in
+the protocol specification.
+
+#define HZ 256                /* timer interrupt frequency (Hz) */
+#define SHIFT_HZ 8            /* log2(HZ) */
+
+     The HZ define (a variable in some kernels) establishes the timer
+     interrupt frequency, 100 Hz for the SunOS kernel, 256 Hz for the
+     Ultrix kernel and 1024 Hz for the OSF/1 kernel. The SHIFT_HZ define
+     expresses the same value as the nearest power of two in order to
+     avoid hardware multiply operations. These are the only parameters
+     that need to be changed for different kernel timer interrupt
+     frequencies.
+
+#define SHIFT_KG 6       /* shift for phase increment */
+#define SHIFT_KF 16      /* shift for frequency increment */
+#define MAXTC 6          /* maximum time constant (shift) */
+
+     These defines establish the response and stability characteristics
+     of the PLL model. The SHIFT_KG and SHIFT_KF defines establish the
+     damping of the PLL and are chosen by analysis for a slightly
+     underdamped convergence characteristic. The MAXTC define
+     establishes the maximum time constant of the PLL.
+
+#define SHIFT_SCALE (SHIFT_KF + SHIFT_HZ) /* shift for scale factor */
+#define SHIFT_UPDATE (SHIFT_KG + MAXTC) /* shift for offset scale
+                          * factor */
+#define SHIFT_USEC 16    /* shift for 1 us in external units */
+#define FINEUSEC (1 << SHIFT_SCALE) /* 1 us in scaled units */
+
+     The SHIFT_SCALE define establishes the decimal point on the
+     time_phase variable which serves as a an extension to the low-order
+     bits of the system clock variable. The SHIFT_UPDATE define
+     establishes the decimal point of the phase portion of the
+     ntp_adjtime() update. The SHIFT_USEC define represents 1 us in
+     external units (shift), while the FINEUSEC define represents 1 us
+     in internal units.
+
+#define MAXPHASE 128000  /* max phase error (usec) */
+#define MAXFREQ 100      /* max frequency error (ppm) */
+#define MINSEC 16        /* min interval between updates (s) */
+#define MAXSEC 1200      /* max interval between updates (s) */
+
+     These defines establish the performance envelope of the PLL, one to
+     bound the maximum phase error, another to bound the maximum
+     frequency error and two others to bound the minimum and maximum
+     time between updates. The intent of these bounds is to force the
+     PLL to operate within predefined limits in order to conform to the
+     correctness models assumed by time-synchronization protocols like
+     NTP and DTSS. An excursion which exceeds these bounds is clamped to
+     the bound and operation proceeds accordingly. In practice, this can
+     occur only if something has failed or is operating out of
+     tolerance, but otherwise the PLL continues to operate in a stable
+     mode. Note that the MAXPHASE define conforms to the maximum offset
+     allowed in NTP before the system time is reset (by settimeofday(),
+     rather than incrementally adjusted (by ntp_adjtime().
+
+David L. Mills <mills@udel.edu>
+Electrical Engineering Department
+University of Delaware
+Newark, DE 19716
+302 831 8247 fax 302 831 4316
+
+1 April 1992
diff --git a/usr.sbin/xntpd/doc/README.magic b/usr.sbin/xntpd/doc/README.magic
new file mode 100644
index 0000000..f473a92
--- /dev/null
+++ b/usr.sbin/xntpd/doc/README.magic
@@ -0,0 +1,346 @@
+                 Magic Tricks for Precision Timekeeping
+
+                       Revised 19 September 1993
+
+Note: This information file is included in the NTP Version 3
+distribution (xntp3.tar.Z) as the file README.magic. This distribution
+can be obtained via anonymous ftp from louie.udel.edu in the directory
+pub/ntp.
+
+1. Introduction
+
+It most cases it is possible using NTP to synchronize a number of hosts
+on an Ethernet or moderately loaded T1 network to a radio clock within a
+few tens of milliseconds with no particular care in selecting the radio
+clock or configuring the servers on the network. This may be adequate
+for the majority of applications; however, modern workstations and high
+speed networks can do much better than that, generally to within some
+fraction of a millisecond, by using special care in the design of the
+hardware and software interfaces.
+
+The timekeeping accuracy of a NTP-synchronized host depends on two
+quantities: the delay due to hardware and software processing and the
+accumulated jitter due to such things as clock reading precision and
+varying latencies in hardware and software queuing. Processing delays
+directly affect the timekeeping accuracy, unless minimized by systematic
+analysis and adjustment. Jitter, on the other hand, can be essentially
+removed, as long as the statistical properties are unbiased, by the low-
+pass filtering of the phase-lock loop incorporated in the NTP local
+clock model.
+
+This note discusses issues in the connection of external time sources
+such as radio clocks and related timing signals to a primary (stratum-1)
+NTP time server. Of principal concern are various techniques that can be
+utilized to improve the accuracy and precision of the time accuracy and
+frequency stability. Radio clocks are most often connected to a time
+server using a serial asynchronous port. Much of the discussion in this
+memorandum has to do with ways in which the delay incurred in this type
+of connection can be controlled and ways in which the jitter due to
+various causes can be minimized.
+
+However, there are ways other than serial ports to connect a radio
+clock, including special purpose hardware devices for some
+architectures, and even unusual applications of existing interface
+devices, such as the audio codec provided in some systems. Many of these
+methods can yield accuracies as good as any attainable with a serial
+port. For those radio clocks equipped with an IRIG-B signal output, for
+example, a hardware device is available for the Sun SPARCstation; see
+the xntpd.8 manual page in the doc directory of the NTP Version 3
+distribution for further information. In addition, it is possible to
+decode the IRIG-B signal using the audio codec included in the Sun
+SPARCstation and a special kernel driver described in the irig.txt file
+in the doc directory of the NTP Version 3 distribution. These devices
+will not be discussed further in this memorandum.
+
+2. Connection via Serial Port
+
+Most radio clocks produce an ASCII timecode with a precision only to the
+millisecond. This results in a maximum peak-to-peak (p-p) jitter in the
+clock readings of one millisecond. However, assuming the read requests
+are statistically independent of the clock update times, the reading
+error is uniformly distributed over the millisecond, so that the average
+over a large number of readings will make the clock appear 0.5 ms late.
+To compensate for this, it is only necessary to add 0.5 ms to its
+reading before further processing by the NTP algorithms.
+
+Radio clocks are usually connected to the host computer using a serial
+port operating at a typical speed of 9600 baud. The on-time reference
+epoch for the timecode is usually the start bit of a designated
+character, usually <CR>, which is part of the timecode. The UART chip
+implementing the serial port most often has a sample clock of eight to
+16 times the basic baud rate. Assuming the sample clock starts midway in
+the start bit and continues to midway in the first stop bit, this
+creates a processing delay of 10.5 baud times, or about 1.1 ms, relative
+to the start bit of the character. The jitter contribution is usually no
+more than a couple of sample-clock periods, or about 26 usec p-p. This
+is small compared to the clock reading jitter and can be ignored. Thus,
+the UART delay can be considered constant, so the hardware contribution
+to the total mean delay budget is 0.5 + 1.1 = 1.6 ms.
+
+In some kernel serial port drivers, in particular, the Sun zs driver,
+an intentional delay is introduce in input character processing when the
+first character is received after an idle period. A batch of characters
+is passed to the calling program when either (a) a timeout in the
+neighborhood of 10 ms expires or (b) an input buffer fills up. The
+intent in this design is to reduce the interrupt load on the processor
+by batching the characters where possible. Obviously, this can cause
+severe problems for precision timekeeping. It is possible to patch the
+zs driver to eliminate the jitter due to this cause; contact the author
+for further details. However, there is a better solution which will be
+described later in this note. The problem does not appear to be present
+in the Serial/Parallel Controller (SPC) for the SBus, which contains
+eight serial asynchronous ports along with a parallel port. The
+measurements referred to below were made using this controller.
+
+Good timekeeping depends strongly on the means available to capture an
+accurate sample of the local clock or timestamp at the instant the stop
+bit of the on-time character is found; therefore, the code path delay
+between the character interrupt routine and the first place a timestamp
+can be captured is very important, since on some systems such as Sun
+SPARCstations, this path can be astonishingly long. The Sun scheduling
+mechanisms involve both a hardware interrupt queue and a software
+interrupt queue. Entries are made on the hardware queue as the interrupt
+is signalled and generally with the lowest latency, estimated at 20-30
+microseconds (usec) for a SPARC 4/65 IPC. Then, after minimal
+processing, an entry is made on the software queue for later processing
+in order of software interrupt priority. Finally, the software interrupt
+unblocks the NTP daemon which calculates the current local clock offset
+and introduces corrections as required.
+
+Opportunities exist to capture timestamps at the hardware interrupt
+time, software interrupt time and at the time the NTP daemon is
+activated, but these involve various degrees of kernel trespass and
+hardware gimmicks. To gain some idea of the severity of the errors
+introduced at each of these stages, measurements were made using a Sun
+4/65 IPC and a test setup that results in an error between the host
+clock and a precision time source (calibrated cesium clock) no greater
+than 0.1 ms. The total delay from the on-time epoch to when the NTP
+daemon is activated was measured at 8.3 ms in an otherwise idle system,
+but increased on rare occasion to over 25 ms under load, even when the
+NTP daemon was operated at the highest available software priority
+level. Since 1.6 ms of the total delay is due to the hardware, the
+remaining 6.7 ms represents the total code path delay accounting for all
+software processing from the hardware interrupt to the NTP daemon.
+
+It is commonly observed that the latency variations (jitter) in typical
+real-time applications scale as the processing delay. In the case above,
+the ratio of the maximum observed delay (25 ms) to the baseline code
+path delay (8.3 ms) is about three. It is natural to expect that this
+ratio remain the same or less as the code path between the hardware
+interrupt and where the timestamp is captured is reduced. However, in
+general this requires trespass on kernel facilities and/or making use of
+features not common to all or even most Unix implementations. In order
+to assess the cost and benefits of increasingly more aggressive insult
+to the hardware and software of the system, it is useful to construct a
+budget of the code path delay at each of the timestamp opportunity
+times. For instance, on Unix systems which include support for the SIGIO
+facility, it is possible to intervene at the time the software interrupt
+is serviced. The NTP daemon code uses this facility, when available, to
+capture a timestamp and save it along with the data in a buffer for
+later processing. This reduces the total code path delay from 6.7 ms to
+3.5 ms on an otherwise idle system. This reduction applies to all input
+processing, including network interfaces and serial ports.
+
+3. The CLK Mode
+
+By far the best place to capture the timestamp is right in the kernel
+interrupt routine, but this gerally requires intruding in the code
+itself, which can be intricate and architecture dependent. The next best
+place is in some routine close to the interrupt routine on the code
+path. There are two ways to do this, depending on the ancestry of the
+Unix operating system variant. Older systems based primarily on the
+original Unix 4.3bsd support what is called a line discipline module,
+which is a hunk of code with more-or-less well defined interface
+specifications that can get in the way, so to speak, of the code path
+between the interrupt routine and the remainder of the serial port
+processing. Newer systems based on System V STREAMS can do the same
+thing using what is called a streams module. Both approaches are
+supported in the NTP Version 3 distribution, as described in the README
+files in the kernel directory of the distribution. In either case,
+header and source files have to be copied to the kernel build tree and
+certain tables in the kernel have to be modified. In neither case,
+however, are kernel sources required. In order to take advantage of
+this, the clock driver must include code to activate the feature and
+extract the timestamp. At present, this support is included in the clock
+drivers for the Spectracom WWVB clock (WWVB define), the PSTI/Traconex
+WWV/WWVH clock (PST define) and a special one-pulse-per-second (pps)
+signal (PPSCLK define) described later. If justified, support can be
+easily added to most other clock drivers as well. For future reference,
+these modules operating with supported drivers will be called the CLK
+support.
+
+The CLK line discipline and STREAMS modules operate in the same way.
+They look for a designated character, usually <CR>, and stuff a Unix
+timestamp in the data stream following that character whenever it is
+found. Eventually, the data arrive at the particular clock driver
+configured in the NTP Version 3 distribution. The driver then uses the
+timestamp as a precise reference epoch, subject to the earlier
+processing delays and jitter budget, for future reference. In order to
+gain some insight as to the effectiveness of this approach, measurements
+were made using the same test setup described above. The total delay
+from the on-time epoch to the instant when the timestamp is captured was
+measured at 3.5 ms. Thus, the code path delay is this value less the
+hardware delay 3.5 - 1.6 = 1.9 ms.
+
+While the improvement in accuracy in the baseline case is significant,
+there is another factor, at least in Sun systems, that makes it even
+more worthwhile. When processing the code path up to the CLK module, the
+priority is apparently higher than for processing beyond it. In case of
+heavy CPU activity, this can lead to relatively long tails in the
+processing delays for the driver, which of course are avoided by
+capturing the timestamp early in the code path.
+
+4. The PPSCLK Mode
+
+Many timing receivers can produce a 1-pps signal of considerably better
+precision than the ASCII timecode. Using this signal, it is possible to
+avoid the 1-ms p-p jitter and 1.6 ms hardware timecode adjustment
+entirely. However, a device is required to interface this signal to the
+hardware and operating system. In general, this requires some sort of
+level converter and pulse generator that can turn the 1-pps signal on-
+time transition into a valid character. An example of such a device is
+described in the gadget directory of the NTP Version 3 distribution.
+Although many different circuit designs could be used as well, this
+particular device generates a single 26-usec start bit for each 1-pps
+signal on-time transition. This appears to the UART operating at 38.4K
+baud as an ASCII DEL (hex FF).
+
+Now, assuming a serial port can be dedicated to this purpose, a source
+of 1-pps character interrupts is available and can be used to provide a
+precision reference. The NTP Version 3 daemon can be configured to
+utilize this feature by specifying the PPSCLK define, which requires the
+CLK module and gadget box described above. The character resulting from
+each 1-pps signal on-time transition is intercepted by the CLK module
+and a timestamp is inserted in the data stream. An interrupt is created
+for the device driver, which reads the timestamp and discards the DEL
+character. Since the timestamp is captured at the on-time transition,
+the seconds-fraction portion is the offset between the local clock and
+the on-time epoch less the UART delay of 273 usec at 38.4K baud. If the
+local clock is within +-0.5 second of this epoch, as determined by other
+means, the local clock correction is taken as the offset itself, if
+between zero and 0.5 s, and the offset minus one second, if between 0.5
+and 1.0 s. In the NTP daemon the resulting correction is first processed
+by a multi-stage median/trimmed mean filter to remove residual jitter
+and then processed by the usual NTP algorithms.
+
+The baseline delay between the on-time transition and the timestamp
+capture was measured at 400+-10 usec on an otherwise idle test system.
+As the UART delay at 38.4K baud is about 270 usec, the difference, 130
+usec, must be due to the hardware interrupt latency plus the time to
+call the microtime() routine which actually reads the system clock and
+microsecond counter. For these measurements the assembly-coded version
+of this routine described in the ppsclock directory of the NTP Version 3
+distribution was used. This routine reduces the time to read the system
+clock from 42-85 usec with the native Sun C-coded routine to about 3
+usec using the microtime() assembly-coded routine and can be ignored.
+Thus, the 130 usec must be accounted for in interrupt service, register
+window, context switching, streams operations and measurement
+uncertainty, which is probably not unreasonable. The reason for the
+difference between the this figure and the previously calculated value
+of 1.9 ms for the CLK module and serial ASCII timecode is probably due
+to the fact that all STREAMS modules other than the CLK module were
+removed, since the serial port is not used for ordinary ASCII data.
+
+An interesting feature of this approach is that the 1-pps signal is not
+necessarily associated with any particular radio clock and, indeed,
+there may be no such clock at all. Some precision timekeeping equipment,
+such as cesium clocks, VLF receivers and LORAN-C timing receivers
+produce only a precision 1-pps signal and rely on other mechanisms to
+resolve the second of the day and day of the year. It is possible for an
+NTP-synchronized host to derive the latter information using other NTP
+peers, presumably properly synchronized within +-0.5 second, and to
+remove residual jitter using the 1-pps signal. This makes it quite
+practical to deliver precision time to local clients when the subnet
+paths to remote primary servers are heavily congested. In extreme cases
+like this, it has been found useful to increase the tracking aperture
+from +-128 ms to as high as +-512 ms.
+
+In the current implementation the radio timecode and 1-pps signal are
+separately processed. The timecode capture and CLK support, if provided
+by the radio driver, operate the same way whether or not the PPSCLK
+support is enabled. If the local clock is reliably synchronized within
++-0.5 s and the 1-pps signal has been valid for some number of seconds,
+its offset rather than whatever synchronization source has been selected
+is used instead. However, while a this procedure delivers a new offset
+estimate every second, the local clock is updated only as each valid
+update is computed for the peer selected as the source of
+synchronization.
+
+However, there is a hazard to the use of the 1-pps signal in this way if
+the radio generating the 1-pps signal misbehaves or loses
+synchronization with its transmitter. In such a case the radio might
+indicate the error, but the system has no way to associate the error
+with the 1-pps signal. To deal with this problem the prefer parameter
+described in the xntpd.8 man page in the doc directory of the NTP
+Version 3 distribution can be used both to cause the clock selection
+algorithm to choose a preferred peer, all other things being equal, as
+well as associate the error indications in such a way that the 1-pps
+signal will be disregarded if the peer stops providing valid updates,
+such as would occur in an error condition. The prefer parameter can be
+used in other situations as well when preference is to be given a
+particular source of synchronization.
+
+5. The PPS Mode
+
+For the ultimate accuracy and lowest jitter, it would be best to
+eliminate the UART and capture the 1-pps on-time transition directly
+using an appropriate interface. This is in fact possible using a
+modified serial port driver and data lead in the serial port interface
+cable. In this scheme, described in detail in the ppsclock directory of
+the NTP Version 3 distribution, the 1-pps source is connected via the
+previously described gadget box to the carrier-detect lead of a serial
+port. Happily, this can be the same port used for a radio clock, for
+example, or another unrelated serial device. The scheme, referred to
+subsequently as the PPS mode, is specific to the SunOS 4.1.x kernel and
+requires a special STREAMS module. Instructions on how to build the
+kernel are also included in that directory.
+
+Except for special-purpose interface modules, such as the KSI/Odetics
+TPRO IRIG-B decoder and the modified audio driver for the IRIG-B signal
+mentioned previously, the PPS mode provides the most accurate and
+precise timestamp available. There is essentially no latency and the
+timestamp is captured within 20-30 usec of the on-time epoch.
+
+The PPS mode requires the PPSPPS define and one of the radio clock
+serial ports to be selected as the PPS interface. This is the port which
+handles the 1-pps signal; however, the signal path has nothing to do
+with the ordinary serial data path; the two signals are not related,
+other than by the need to activate the PPS mode and pass the file
+descriptor to a common processing routine. Thus, for the port to be
+selected for the PPS function, the define for the associated radio clock
+needs to have a PPS suffix. In case of multiple radio clocks on a single
+time server, the PPS suffix is necessary on only one of them; more than
+one PPS suffix would be an error.
+
+The PPS mode works just like the CLK mode in the treatment of the prefer
+parameter and indicated peer errors. As in the CLK mode, only the offset
+within the second is used and only when the offset is less than +-0.5 s.
+However, the precision of the clock adjustments is usually so fine that
+the error budget is dominated by the inherent short-term stability of
+typical computer local clock oscillators. Therefore, it is advisable to
+reduce the poll interval for the preferred peer from the default 64 s to
+something less, like 16 s. This is done using the minpoll and maxpoll
+parameters of the peer or server command associated with the clock.
+These parameters take as arguments a power of 2, in seconds, which
+becomes the poll interval and, indirectly, affects the bandwidth of the
+tracking loop.
+
+6. Results and Conclusions
+
+It is clear from the above that substantial improvements in timekeeping
+accuracy are possible with varying degrees of hardware and software
+intrusion. While the ultimate accuracy depends on the jitter and wander
+characteristics of the computer local oscillator, it is possible to
+reduce jitter to a negligible degree simply by processing with the NTP
+phase-lock loop and local clock algorithms. The residual jitter using
+the PPS mode on a Sun4 IPC is typically in the 40-100 usec range, while
+the wander is rarely more than twice that under typical environmental
+room conditions.
+
+David L. Mills <mills@udel.edu>
+Electrical Engineering Department
+University of Delaware
+Newark, DE 19716
+302 831 8247 fax 302 831 4316
+
+25 August 1993
diff --git a/usr.sbin/xntpd/doc/UofT b/usr.sbin/xntpd/doc/UofT
new file mode 100644
index 0000000..54420d5
--- /dev/null
+++ b/usr.sbin/xntpd/doc/UofT
@@ -0,0 +1,146 @@
+This file is the original README, and is a little out of date.  It
+is also very specific to UofT, since there was a time when the daemon
+was only run here.
+
+To run this:
+
+(1) Fix your kernel's value of tickadj.  Tickadj sets both the
+    precision with which time slews can be performed and the amount
+    of slew you can do in a given interval.  Xntpd operates by making
+    a bunch of little adjustments.  Make tickadj too large (the default
+    value almost always is) and xntpd will perform poorly since the
+    slews will disappear in the roundoff.  Make tickadj too small
+    and large slews won't complete before the next adjustment is
+    ready.
+
+    To determine a good value of tickadj to use, first determine your
+    kernel's value of hz (50 on a Sun 3, 100 on Sun 4's and vaxes).
+    Divide that number into 500 (i.e. compute 500/hz) and use an
+    integer near there as tickadj (say, 10 on Sun 3's, 5 on Sun 4's
+    and vaxes).  Then adb your kernel and write the new value.  You
+    should probably do both the running kernel and the disk image.
+
+    If your machine doesn't come with adb, or if the kernel is of a
+    non-Berkeley flavour, take a look at the util directory, particularly
+    util/tickadj.
+
+(2) Edit the Config file in this directory.  You *must* tell it whether
+    your machine uses big endian or little endian byte order.  Also,
+    Suns running SunOS 3.x require special consideration, as well as Vaxes
+    running Ultrix 2.0 and compilers which don't understand `signed char'
+    declarations.  When you've got all this worked out, type `make makefiles'
+    to distribute configuration information to Makefiles for individual
+    programs, followed by `make' to compile everything.
+
+(2a) Note that, among other things, two programs were made in the authstuff
+    directory, authcert and authspeed.  The last two are utilities for
+    checking the authentication code.  Type `authcert < certdata'.  If
+    this provokes a massive failure you probably got the byte order wrong
+    in the Config file.  Type `authspeed -n 10000 auth.samplekeys', or
+    something, a couple of times to get a value of authdelay to stick in
+    the configuration file.  The numbers for machines I've tried look like:
+
+	uVax II		0.001450
+	Sun 3/180	0.000620
+	uVax III	0.000515
+	Sun 3/60	0.000455
+	IBM RT Mdl 125	0.000323
+	Sun 3/280	0.000302
+	Sun 4/280	0.000110
+	MIPS M/1000	0.000100
+
+(3) Typing `make install' will nstall xntpd, xntpdc, ntpdate and ntpq.  Watch
+    the install location in the Config file.
+
+(4) If you will be running xntpd (see 4a below for the alternative),
+    configure it (configuration is necessary for all machines now, though
+    this restriction will go away when I get broadcast time fully tested).
+    xntpd reads its configuration from /etc/ntp.conf (by default) and
+    you must tell it which machines it is to get its time from in
+    here.
+
+    Note that NTP operates in a hierarchy.  Machines with radio clocks
+    (which are stratum 1 servers) are at the top of the heap, in that
+    all time originates with them.  The situation with servers locally
+    is in a state of flux.  We currently have one semi-reliable stratum 1
+    server on campus (suzuki.ccie), and maintain three other stratum 2
+    servers which (gently) access other people's off-campus stratum 1
+    servers.  All of these machines are lightly loaded and have good
+    quality clocks, and so will probably do until we get some more stratum 1
+    weight.
+
+    Thus you are probably faced with choosing whether your hosts should
+    be stratum 2 or stratum 3 (or stratum 3 or 4 when suzuki's clock is down).
+    The rule of thumb is to make your best clocks and/or your file servers
+    stratum 2 (or 3) by peering them with the four campus servers, and make
+    lesser clocks and clients stratum 3 (or 4) by peering them with near
+    by servers which are synchonized to the campus servers.  The second rule
+    of thumb is that more servers are better.  It is quite possible to
+    synchronize with just a single server, but if you do your xtnpd daemon
+    won't have any cross checks to tell it when the server has gone
+    wonky. 3 or 4 lower stratum peers is about right.  Note that while
+    you can also peer with same-stratum peers, you shouldn't do this
+    unless the same-stratum peer is exchanging time with a lower stratum
+    peer you don't talk to directly.
+
+    Anyway, for your stratum 2 servers you can probably use ntp.conf
+    from the conf directory directly.  You will have to handcraft the
+    peer assocations for your stratum 3 servers.
+
+    Oh, and a note about the drift file (see ntp.conf).  One of the
+    things xntpd does is accumulate a correction for the frequency of
+    the crystal in your computer.  It usually takes a day or so of
+    running to figure this out, after which the value will usually remain
+    pretty stable, especially if the computer is in a machine room.  The
+    value is printed in your syslog file (once a minute, currently, though
+    this will change), and can be obtained from the daemon using xntpdc.
+
+    To avoid having to wait a day after restarts before the computer
+    synchronizes really well, xntpd will optionally write its current
+    value of the frequency correction into a file, once an hour.  When
+    it is killed and restarted, xntpd reinitializes itself to this
+    value on start up.  This is an advantageous feature, so a driftfile
+    line should always be included in the configuration file.
+
+(4a) Xntpd is a daemon.  It will keep your time exquisitely precise under
+     normal conditions (it is quite capable of keeping a good clock within
+     a millisecond of a good server.  Our servers aren't normally this
+     good, yet, but may become so when we get a few more stable local
+     stratum 1 peers).  Even when cut off entirely from its servers xntpd
+     will prevent your clock from drifting seriously by continuing to apply
+     its accumulated frequency correction.  The cost of this is that xntpd
+     will permanently consume memory while it is running, and real memory
+     at that since xntpd is unlikely to ever swap out.  This cost is
+     currently over 100 kb.
+
+     If you aren't too worried about millisecond timing and feel religious
+     about keeping memory consumption at a minimum (perhaps on memory-poor
+     workstations), a passable alternative might be to run ntpdate instead.
+     Ntpdate is the NTP equivalent of rdate, a one shot date setting
+     program, and implements the same multiple sample/multiple server
+     filter algorithms as xntpd.  Ntpdate was explicitly designed to be
+     run repeatly from cron, though it also makes a good boot time date
+     setter.  Running ntpdate from cron on an hourly basis will keep all
+     but seriously broken clocks within 100 ms of on-time, and for most
+     clocks will probably do better than 50 ms.  If this is an attractive
+     alternative see the manual page.  You should choose ntpdate's servers
+     as you would the peer associations for a stratum 3 xntpd server.
+
+(5) Once everything is configured, start the daemon(s).  ntpq can be
+    used to see what xntpd is doing.  It runs both interactive and from
+    the command line, type ? to see the interactive commands and ? command
+    to see what a command does.  The `peers' command is a good one.  ntpq
+    can also be used to see what other peoples' servers are doing, in
+    particular the fuzzball primary servers.
+
+(6) If you want to use the authentication facility (this might be useful
+    if, for example, you were running Kerberos since this prevents people
+    from setting your time back and doing replay attacks on the server),
+    you might find a couple of useful programs in the auth_stuff directory.
+    mkrandkeys will generate some very random keys to use.  keyparity
+    generates odd parity bits for keys (needed for the key file) and will
+    convert between key formats.
+
+All bug reports gratefully received.
+
+Dennis
diff --git a/usr.sbin/xntpd/doc/notes.txt b/usr.sbin/xntpd/doc/notes.txt
new file mode 100644
index 0000000..5ea2b33
--- /dev/null
+++ b/usr.sbin/xntpd/doc/notes.txt
@@ -0,0 +1,1258 @@
+                      Notes on Xntpd Configuration
+
+                    David L. Mills (mills@udel.edu)
+                         University of Delaware
+                            14 January 1993
+
+Introduction
+
+This document is a collection of notes concerning the use of xntpd and
+related programs, and on coping with the Network Time Protocol (NTP) in
+general. It is a major rewrite and update of an earlier document written
+by Dennis Ferguson of the University of Toronto dated 5 November 1989.
+It includes many changes and additions resulting from the NTP Version 3
+specification and new implementation features. It supersedes the earlier
+document, which should no longer be used for new configurations.
+
+Xntpd is a complete implementation of the NTP Version 3 specification as
+defined in RFC 1305. It also retains compatibility with both NTP Version
+2, as defined in RFC 1119, and NTP Version 1, as defined in RFC 1059,
+although this compatibility is sometimes strained and only
+semiautomatic. In order to support in principle the ultimate precision
+of about 232 picoseconds in the NTP specification, xntpd does no
+floating-point arithmetic and instead manipulates the 64-bit NTP
+timestamps as unsigned 64-bit integers. Xntpd fully implements NTP
+Versions 2 and 3 authentication and a mode-6 control-message facility.
+As extensions to the specification, a flexible address-and-mask
+restriction facility has been included, along with a private mode-7
+control-message facility used to remotely reconfigure the system and
+monitor a considerable amount of internal detail.
+
+The code is biased towards the needs of a busy time server with
+numerous, possibly hundreds, of clients and other servers. Tables are
+hashed to allow efficient handling of many associations, though at the
+expense of additional overhead when the number of associations is small.
+Many fancy features have been included to permit efficient management
+and monitoring of a busy primary server, features which are simply
+excess baggage for a server on a high stratum client. The code was
+written with near demonic attention to details which can affect
+precision and as a consequence should be able to make good use of high
+performance, special purpose hardware such as precision oscillators and
+radio clocks. The present code supports a number of radio clocks,
+including those for the WWV, CHU, WWVB, DCF77, GOES and GPS radio and
+satellite services. The server methodically avoids the use of Unix-
+specific library routines where possible by implementing local versions,
+in order to aid in porting the code to perverse Unix and non-Unix
+platforms.
+
+While this implementation slavishly obeys the NTP specification RFC
+1305, it has been specifically tuned to achieve the highest accuracy
+possible on whatever hardware and operating-system platform is
+available. In general, its precision is limited only by that of the
+onboard time-of-day clock maintained by the hardware and operating
+system, while its stability is limited only by that of the onboard
+frequency source, usually an uncompensated crystal oscillator. On modern
+RISC-based processors connected directly to radio clocks via serial-
+asynchronous interfaces, the accuracy is usually limited by that of the
+radio clock and interface to the order of a few milliseconds. The code
+includes special features to support a one-pulse-per-second (1-pps)
+signal generated by some radio clocks. When used in conjunction with a
+suitable hardware level converter, the accuracy can be improved to the
+order of 100 microseconds. Further improvement is possible using an
+outboard, stabilized frequency source, in which the accuracy and
+stability are limited only by the characteristics of that source.
+
+The xntp3 distribution includes, in addition to the daemon itself
+(xntpd), several utility programs, including two remote-monitoring
+programs (ntpq, xntpdc), a remote clock-setting program similar to the
+Unix rdate program (ntpdate), a traceback utility useful to discover
+suitable synchronization sources (ntptrace), and various programs used
+to configure the local platform and calibrate the intrinsic errors. NTP
+has been ported to a large number of platforms, including most RISC and
+CISC workstations and mainframes manufactured today. Example
+configuration files for many models of these machines are included in
+the xntp3 distribution. While in most cases the standard version of the
+implementation runs with no hardware or operating-system modifications,
+not all features of the distribution are available on all platforms. For
+instance, a special feature allowing Sun 4s to achieve accuracies in the
+order of 100 microseconds requires some minor changes and additions to
+the kernel and input/output support.
+
+There are, however, several drawbacks to all of this. Xntpd is very,
+very fat. This is rotten if your intended platform for the daemon is
+memory-limited. Xntpd uses SIGIO for all input, a facility which appears
+to not enjoy universal support and whose use seems to exercise the parts
+of your vendors' kernels which are most likely to have been done poorly.
+The code is unforgiving in the face of kernel problems which affect
+performance, and generally requires that you repair the problems in
+order to achieve acceptable performance. The code has a distinctly
+experimental flavour and contains features which could charitably be
+termed failed experiments, but which have not been hacked out yet. There
+is code which has not been thoroughly tested (e.g. leap-second support)
+due to the inconvenience of setting up tests. Much was learned from the
+addition of support for a variety of radio clocks, with the result that
+this support could use some rewriting.
+
+How NTP Works
+
+The approach used by NTP to achieve reliable time synchronization from a
+set of possibly unreliable remote time servers is somewhat different
+than other such protocols. In particular, NTP does not attempt to
+synchronize clocks to each other. Rather, each server attempts to
+synchronize to UTC (i.e., Universal Coordinated Time) using the best
+available source and available transmission paths to that source. This
+is a fine point which is worth understanding. A group of NTP-
+synchronized clocks may be close to each other in time, but this is not
+a consequence of the clocks in the group having synchronized to each
+other, but rather because each clock has synchronized closely to UTC via
+the best source it has access to. As such, trying to synchronize a set
+of clocks to a set of servers whose time is not in mutual agreement may
+not result in any sort of useful synchronization of the clocks, even if
+you don't care about UTC. NTP operates on the premise that there is one
+true standard time, and that if several servers which claim
+synchronization to standard time disagree about what that time is, then
+one or more of them must be broken. There is no attempt to resolve
+differences more gracefully since the premise is that substantial
+differences cannot exist. In essence, NTP expects that the time being
+distributed from the root of the synchronization subnet will be derived
+from some external source of UTC (e.g. a radio clock). This makes it
+somewhat inconvenient (though not impossible) to synchronize hosts
+together without a reliable source of UTC to synchronize them to. If
+your network is isolated and you cannot access other people's servers
+across the Internet, a radio clock may make a good investment.
+
+Time is distributed through a hierarchy of NTP servers, with each server
+adopting a "stratum" which indicates how far away from an external
+source of UTC it is operating at. Stratum-1 servers, which are at the
+top of the pile (or bottom, depending on your point of view), have
+access to some external time source, usually a radio clock synchronized
+to time signal broadcasts from radio stations which explicitly provide a
+standard time service. A stratum-2 server is one which is currently
+obtaining time from a stratum-1 server, a stratum-3 server gets its time
+from a stratum-2 server, and so on. To avoid long lived synchronization
+loops the number of strata is limited to 15.
+
+Each client in the synchronization subnet (which may also be a server
+for other, higher stratum clients) chooses exactly one of the available
+servers to synchronize to, usually from among the lowest stratum servers
+it has access to. It is thus possible to construct a synchronization
+subnet where each server has exactly one source of lower stratum time to
+synchronize to. This is, however, not an optimal configuration, for
+indeed NTP operates under another premise as well, that each server's
+time should be viewed with a certain amount of distrust. NTP really
+prefers to have access to several sources of lower stratum time (at
+least three) since it can then apply an agreement algorithm to detect
+insanity on the part of any one of these. Normally, when all servers are
+in agreement, NTP will choose the best of these, where "best" is defined
+in terms of lowest stratum, closest (in terms of network delay) and
+claimed precision, along with several other considerations. The
+implication is that, while one should aim to provide each client with
+three or more sources of lower stratum time, several of these will only
+be providing backup service and may be of lesser quality in terms of
+network delay and stratum (i.e. a same-stratum peer which receives time
+from lower stratum sources the local server doesn't access directly can
+also provide good backup service).
+
+Finally, there is the issue of association modes. There are a number of
+modes in which NTP servers can associate with each other, with the mode
+of each server in the pair indicating the behaviour the other server can
+expect from it. In particular, when configuring a server to obtain time
+from other servers, there is a choice of two modes which may be
+alternatively used. Configuring an association in symmetric-active mode
+(usually indicated by a "peer" declaration in configuration files)
+indicates to the remote server that one wishes to obtain time from the
+remote server and that one is also willing to supply time to the remote
+server if need be. This mode is appropriate in configurations involving
+a number of redundant time servers interconnected via diverse network
+paths, which is presently the case for most stratum-1 and stratum-2
+servers on the Internet today. Configuring an association in client mode
+(usually indicated by a "server" declaration in configuration files)
+indicates that one wishes to obtain time from the remote server, but that
+one is not willing to provide time to the remote server. This mode is
+appropriate for file-server and workstation clients that do not provide
+synchronization to other local clients. Client mode is also useful for
+boot-date-setting programs and the like, which really have no time to
+provide and which don't retain state about associations over the longer
+term.
+
+Configuring Your Subnet
+
+At startup time the xntpd daemon running on a host reads the initial
+configuration information from a file, usually /etc/ntp.conf, unless a
+different name has been specified at compile time. Putting something in
+this file which will enable the host to obtain time from somewhere else
+is usually the first big hurdle after installation of the software
+itself, which is described in other documents included in the xntp3
+distribution. At its simplest, what you need to do in the configuration
+file is declare the servers that the daemon should poll for time
+synchronization. In principle, no such list is needed if some other time
+server explicitly mentions the host and is willing to provide
+synchronization; however, this is considered dangerous, unless the
+access control or authentication features (described later) are in use.
+
+In the case of a workstation operating in an enterprise network for a
+public or private organization, there is often an administrative
+department that coordinates network services, including NTP. Where
+available, the addresses of appropriate servers can be provided by that
+department. However, if this infrastructure is not available, it is
+necessary to explore some portion of the existing NTP subnet now running
+in the Internet. There are at present many thousands of time servers
+running NTP in the Internet, a significant number of which are willing
+to provide a public time-synchronization service. Some of these are
+listed in a file maintained on the Internet host louie.udel.edu
+(128.175.1.3) on the path pub/ntp/doc/clock.txt. This file is updated on
+a regular basis using information provided voluntarily by various site
+administrators. There are other ways to explore the nearby subnet using
+the ntptrace and ntpq programs. See the man pages for further
+information on these programs.
+
+It is vital to carefully consider the issues of robustness and
+reliability when selecting the sources of synchronization. Normally, not
+less than three sources should be available, preferably selected to
+avoid common points of failure. It is usually better to choose sources
+which are likely to be "close" to you in terms of network topology,
+though you shouldn't worry overly about this if you are unable to
+determine who is close and who isn't. Normally, it is much more serious
+when a server becomes faulty and delivers incorrect time than when it
+simply stops operating, since an NTP-synchronized host normally can
+coast for hours or even days without its clock accumulating serious
+error over one second, for instance. Selecting at least three sources
+from different operating administrations, where possible, is the minimum
+recommended, although a lesser number could provide acceptable service
+with a degraded degree of robustness.
+
+Normally, it is not considered good practice for a single workstation to
+request synchronization from a primary (stratum-1) time server. At
+present, these servers provide synchronization for hundreds of clients
+in many cases and could, along with the network access paths, become
+seriously overloaded if large numbers of workstation clients requested
+synchronization directly. Therefore, workstations located in sparsely
+populated administrative domains with no local synchronization
+infrastructure should request synchronization from nearby stratum-2
+servers instead. In most cases the keepers of those servers listed in
+the clock.txt file provide unrestricted access without prior permission;
+however, in all cases it is considered polite to notify the
+administrator listed in the file upon commencement of regular service.
+In all cases the access mode and notification requirements listed in the
+file must be respected.
+
+In the case of a gateway or file server providing service to a
+significant number of workstations or file servers in an enterprise
+network it is even more important to provide multiple, redundant sources
+of synchronization and multiple, diversity-routed, network access paths.
+The preferred configuration is at least three administratively
+coordinated time servers providing service throughout the administrative
+domain including campus networks and subnetworks. Each of these should
+obtain service from at least two different outside sources of
+synchronization, preferably via different gateways and access paths.
+These sources should all operate at the same stratum level, which is one
+less than the stratum level to be used by the local time servers
+themselves. In addition, each of these time servers should peer with all
+of the other time servers in the local administrative domain at the
+stratum level used by the local time servers, as well as at least one
+(different) outside source at this level. This configuration results in
+the use of six outside sources at a lower stratum level (toward the
+primary source of synchronization, usually a radio clock), plus three
+outside sources at the same stratum level, for a total of nine outside
+sources of synchronization. While this may seem excessive, the actual
+load on network resources is minimal, since the interval between polling
+messages exchanged between peers usually ratchets back to no more than
+one message every 17 minutes.
+
+The stratum level to be used by the local time servers is an engineering
+choice. As a matter of policy, and in order to reduce the load on the
+primary servers, it is desirable to use the highest stratum consistent
+with reliable, accurate time synchronization throughout the
+administrative domain. In the case of enterprise networks serving
+hundreds or thousands of client file servers and workstations,
+conventional practice is to obtain service from stratum-1 primary
+servers such as listed in the clock.txt file. When choosing sources away
+from the primary sources, the particular synchronization path in use at
+any time can be verified using the ntptrace program included in the
+xntp3 distribution. It is important to avoid loops and possible common
+points of failure when selecting these sources. Note that, while NTP
+detects and rejects loops involving neighboring servers, it does not
+detect loops involving intervening servers. In the unlikely case that
+all primary sources of synchronization are lost throughout the subnet,
+the remaining servers on that subnet can form temporary loops and, if
+the loss continues for an interval of many hours, the servers will drop
+off the subnet and free-run with respect to their internal (disciplined)
+timing sources.
+
+In many cases the purchase of one or more radio clocks is justified, in
+which cases good engineering practice is to use the configurations
+described above and connect the radio clock to one of the local servers.
+This server is then encouraged to participate in a special primary-
+server subnetwork in which each radio-equipped server peers with several
+other similarly equipped servers. In this way the radio-equipped server
+may provide synchronization, as well as receive synchronization, should
+the local or remote radio clock(s) fail or become faulty. Xntpd treats
+attached radio clock(s) in the same way as other servers and applies the
+same criteria and algorithms to the time indications, so can detect when
+the radio fails or becomes faulty and switch to alternate sources of
+synchronization. It is strongly advised, and in practice for most
+primary servers today, to employ the authentication or access-control
+features of the xntp3 distribution in order to protect against hostile
+penetration and possible destabilization of the time service.
+
+Using this or similar strategies, the remaining hosts in the same
+administrative domain can be synchronized to the three (or more)
+selected time servers. Assuming these servers are synchronized directly
+to stratum-1 sources and operate normally as stratum-2, the next level
+away from the primary source of synchronization, for instance various
+campus file servers, will operate at stratum 3 and dependent
+workstations at stratum 4. Engineered correctly, such a subnet will
+survive all but the most exotic failures or even hostile penetrations of
+the various, distributed timekeeping resources.
+
+The above arrangement should provide very good, robust time service with
+a minimum of traffic to distant servers and with manageable loads on the
+local servers. While it is theoretically possible to extend the
+synchronization subnet to even higher strata, this is seldom justified
+and can make the maintenance of configuration files unmanageable.
+Serving time to a higher stratum peer is very inexpensive in terms of
+the load on the lower stratum server if the latter is located on the
+same concatenated LAN. When justified by the accuracy expectations, NTP
+can be operated in broadcast mode, so that clients need only listen for
+periodic broadcasts and do not need to send anything.
+
+When planning your network you might, beyond this, keep in mind a few
+generic don'ts, in particular:
+
+1.   Don't synchronize a local time server to another peer at the same
+     stratum, unless the latter is receiving time from lower stratum
+     sources the former doesn't talk to directly. This minimizes the
+     occurance of common points of failure, but does not eliminate them
+     in cases where the usual chain of associations to the primary
+     sources of synchronization are disrupted due to failures.
+2.   Don't configure peer associations with higher stratum servers. Let
+     the higher strata configure lower stratum servers, but not the
+     reverse. This greatly simplifies configuration file maintenance,
+     since there is usually much greater configuration churn in the high
+     stratum clients such as personal workstations.
+
+3.   Don't synchronize more than one time server in a particular
+     administrative domain to the same time server outside that domain.
+     Such a practice invites common points of failure, as well as raises
+     the possibility of massive abuse, should the configuration file be
+     automatically distributed do a large number of clients.
+
+There are many useful exceptions to these rules. When in doubt, however,
+follow them.
+
+Dennis Ferguson writes: Note that mention was made of machines with
+"good" clocks versus machines with "bad" ones. There are two things that
+make a clock good, the precision of the clock (e.g. how many low order
+bits in a time value are actually significant) and the frequency of
+occurance (or lack thereof) of such things as lost clock interrupts.
+Among the most common computers I have observed there to be a fairly
+simple algorithm for determining the goodness of its clock. If the
+machine is a Vax, it probably has a good clock (the low order bit in the
+time is in the microseconds and most of these seem to manage to get
+along without losing clock interrupts). If the machine is a Sun 3 it
+probably doesn't (the low order clock bit is at the 10 or 20 millisecond
+mark and Sun 3s like to lose clock interrupts, particularly if they have
+a screen and particularly if they run SunOS 4.0.x). If you have IBM RTs
+running AOS 4.3, they have fair clocks (low order clock bit at about a
+millisecond and they don't lose clock interrupts, though they do have
+trouble with clock rollovers while reading the low order clock bits) but
+I recommend them as low stratum NTP servers anyway since they aren't
+much use as anything else. Sun 4s running SunOS 4.1.1 make very good
+time servers, once some native foolishness mentioned below is
+surmounted. [However, it is very important to avoid using the keyboard
+firmware, which can cause severe interrupt latencies, in favor of the
+software drivers ordinarily used in conjunction with a windowing system.
+- DLM] For other machines you are on your own since I don't have enough
+data points to venture an opinion. In any event, if at all possible you
+should try to use machines with good clocks for the lower strata.
+
+Configuring Your Server or Client
+
+As mentioned previously, the configuration file is usually called
+/etc/ntp.conf. This is an ASCII file conforming to the usual comment and
+whitespace conventions. A working configuration file might look like (In
+this and other examples, do not copy this directly.):
+
+     # peer configuration for 128.100.100.7
+     # (expected to operate at stratum 2)
+
+     server 128.4.1.1         # rackety.udel.edu
+     server 128.8.10.1        # umd1.umd.edu
+     server 192.35.82.50      # lilben.tn.cornell.edu
+     driftfile /etc/ntp.drift
+
+This particular host is expected to operate as a client at stratum 2 by
+virtue of the "server" keyward and the fact that two of the three
+servers declared (the first two, actually) have radio clocks and usually
+run at stratum 1. The third server in the list has no radio clock, but
+is known to maintain associations with a number of stratum 1 peers and
+usually operates at stratum 2. Of particular importance with the last
+host is that it maintains associations with peers besides the two
+stratum 1 peers mentioned. This can be verified using the ntpq program
+included in the xntp3 distribution. When configured using the "server"
+keyword, this host can receive synchronization from any of the listed
+servers, but can never provide synchronization to them.
+
+Unless restricted using facilities described later, this host can
+provide synchronization to dependent clients, which do not have to be
+listed in the configuration file. Associations maintained for these
+clients are transitory and result in no persistent state in the host.
+These clients are normally not visible using the ntpq program included
+in the xntp3 distribution; however, xntpd includes a monitoring feature
+(described later) which caches a minimal amount of client information
+useful for debugging administrative purposes.
+
+A time server expected to both receive synchronization from another
+server, as well as to provide synchronization to it, is delared using
+the "peer" keyword instead of the "server" keyword. In all other aspects
+the server operates the same in either mode and can provide
+synchronization to dependent clients or other peers. It is considered
+good engineering practice to declare time servers outside the
+administrative domain as "peer" and those inside as "server" in order to
+provide redundancy in the global Internet, while minimizing the
+possibility of instability within the domain itself. A time server in
+one domain can in principle heal another domain temporarily isolated
+from all other sources of synchronization. However, it is probably
+unwise for a casual workstation to bridge fragments of the local domain
+which have become temporarily isolated.
+
+Note the inclusion of a "driftfile" declaration. One of the things the
+NTP daemon does when it is first started is to compute the error in the
+intrinsic frequency of the clock on the computer it is running on. It
+usually takes about a day or so after the daemon is started to compute a
+good estimate of this (and it needs a good estimate to synchronize
+closely to its server). Once the initial value is computed, it will
+change only by relatively small amounts during the course of continued
+operation. The "driftfile" declaration indicates to the daemon the name
+of a file where it may store the current value of the frequency error so
+that, if the daemon is stopped and restarted, it can reinitialize itself
+to the previous estimate and avoid the day's worth of time it will take
+to recompute the frequency estimate. Since this is a desireable feature,
+a "driftfile" declaration should always be included in the configuration
+file.
+
+An implication in the above is that, should xntpd be stopped for some
+reason, the local platform time will diverge from UTC by an amount that
+depends on the intrinsic error of the clock oscillator and the time
+since last synchronized. In view of the length of time necessary to
+refine the frequency estimate, every effort should be made to operate
+the daemon on a continuous basis and minimize the intervals when for
+some reason it is not running.
+
+Xntpd3 Versus Previous Versions
+
+There are several items of note when dealing with a mixture of xntp3 and
+and previous distributions of xntp (NTP Version 2 xntpd) and ntp3.4 (NTP
+Version 1 ntpd). The xntp3 implementation of xntpd is an NTP Version 3
+implementation. As such, by default when no additional information is
+available concerning the preferences of the peer, xntpd claims to be
+version 3 in the packets that it sends.
+
+An NTP implementation conforming to a previous version specification
+ordinarily discards packets from a later version. However, in most
+respects documented in RFC 1305, the previous version is compatible with
+the version-3 algorithms and protocol. Ntpd, while implementing most of
+the version-2 algorithms, still believes itself to be a version-1
+implementation. The sticky part here is that, when either xntpd version
+2 or ntpd version 1 receives a packet claiming to be from a version-3
+server, it discards it without further processing. Hence there is a
+danger that in some situations synchronization with previous versions
+will fail.
+
+Xntpd is aware of this problem. In particular, when xntpd is polled
+first by a host claiming to be a previous version 1 or version 2
+implementation, xntpd claims to be a version 1 or 2 implementation,
+respectively, in packets returned to the poller. This allows xntpd to
+serve previous version clients transparently. The trouble occurs when an
+previous version is to be included in an xntpd configuration file. With
+no further indication, xntpd will send packets claiming to be version 3
+when it polls. To get around this, xntpd allows a qualifier to be added
+to configuration entries to indicate which version to use when polling.
+Hence the entry
+
+     # specify NTP version 1
+
+     peer 130.43.2.2 version 1     # apple.com (running ntpd version 1)
+     peer 130.43.2.2 version 2     # apple.com (running xntpd version 2)
+
+will cause version 1 packets to be sent to the host address 130.43.2.2.
+If you are testing xntpd against previous version servers you will need
+to be careful about this. Note that, as indicated in the RFC 1305
+specification, there is no longer support for the original NTP
+specification, popularly called NTP Version 0.
+
+There are a few other items to watch when converting an ntpd
+configuration file for use with xntpd. The first is to reconsider the
+precision entry from the configuration file, if there is one. There was
+a time when the precision claimed by a server was mostly commentary,
+with no particularly useful purpose. This is no longer the case,
+however, and so changing the precision a server claims should only be
+done with some consideration as to how this alters the performance of
+the server. The default precision claimed by xntpd will be right for
+most situations. A section later on will deal with when and how it is
+appropriate to change a server's precision without doing things you
+don't intend.
+
+Second, note that in the example configuration file above numeric
+addresses are used in the peer and server declarations. It is also
+possible to use names requiring resolution instead, but only if some
+additional configuration is done (xntpd doesn't include the resolver
+routines itself, and requires that a second program be used to do name
+resolution). If you find numeric addresses offensive, see below.
+
+Finally, "passive" and "client" entries in an ntpd configuration file
+have no useful equivalent semantics for xntpd and should be deleted.
+Xntpd won't reset the kernel variable tickadj when it starts, so you can
+remove anything dealing with this in the configuration file. The
+configuration of radio clock peers is done using different language in
+xntpd configuration files, so you will need to delete these entries from
+your ntpd configuration file and see below for the equivalent language.
+
+Traffic Monitoring
+
+Xntpd handles peers whose stratum is higher than the stratum of the
+local server and pollers using client mode by a fast path which
+minimizes the work done in responding to their polls, and normally
+retains no memory of these pollers. Sometimes, however, it is
+interesting to be able to determine who is polling the server, and how
+often, as well as who has been sending other types of queries to the
+server.
+
+To allow this, xntpd implements a traffic monitoring facility which
+records the source address and a minimal amount of other information
+from each packet which is received by the server. This can be enabled by
+adding the following line to the server's configuration file:
+
+     # enable monitoring feature
+
+     monitor yes
+
+The recorded information can be displayed using the xntpdc query
+program, described briefly below.
+
+Address-and-Mask Restrictions
+
+The address-and-mask configuration facility supported by xntpd is quite
+flexible and general, but is not an integral part of the NTP Version 3
+specification. The major drawback is that, while the internal
+implementation is very nice, the user interface sucks. For this reason
+it is probably worth doing an example here. Briefly, the facility works
+as follows. There is an internal list, each entry of which holds an
+address, a mask and a set of flags. On receipt of a packet, the source
+address of the packet is compared to each entry in the list, with a
+match being posted when the following is true:
+
+     (source_addr & mask) == (address & mask)
+
+A particular source address may match several list entries. In this case
+the entry with the most one bits in the mask is chosen. The flags
+associated with this entry are used to control the access.
+
+In the current implementation the flags always add restrictions. In
+effect, an entry with no flags set leaves matching hosts unrestricted.
+An entry can be added to the internal list using a "restrict"
+declaration. The flags associated with the entry are specified
+textually. For example, the "notrust" flag indicates that hosts matching
+this entry, while treated normally in other respects, shouldn't be
+trusted to provide synchronization even if otherwise so enabled. The
+"nomodify" flag indicates that hosts matching this entry should not be
+allowed to do run time configuration. There are many more flags, see the
+xntpd.8 man page.
+
+Now the example. Suppose you are running the server on a host whose
+address is 128.100.100.7. You would like to ensure that run time
+reconfiguration requests can only be made from the local host and that
+the server only ever synchronizes to one of a pair of off-campus servers
+or, failing that, a time source on net 128.100. The following entries in
+the configuration file would implement this policy:
+
+     # by default, don't trust and don't allow modifications
+
+     restrict default notrust nomodify
+
+     # these guys are trusted for time, but no modifications allowed
+
+     restrict 128.100.0.0 mask 255.255.0.0 nomodify
+     restrict 128.8.10.1 nomodify
+     restrict 192.35.82.50 nomodify
+
+     # the local addresses are unrestricted
+
+     restrict 128.100.100.7
+     restrict 127.0.0.1
+
+The first entry is the default entry, which all hosts match and hence
+which provides the default set of flags. The next three entries indicate
+that matching hosts will only have the nomodify flag set and hence will
+be trusted for time. If the mask isn't specified in the restrict
+keyward, it defaults to 255.255.255.255. Note that the address
+128.100.100.7 matches three entries in the table, the default entry
+(mask 0.0.0.0), the entry for net 128.100 (mask 255.255.0.0) and the
+entry for the host itself (mask 255.255.255.255). As expected, the flags
+for the host are derived from the last entry since the mask has the most
+bits set.
+
+The only other thing worth mentioning is that the restrict declarations
+apply to packets from all hosts, including those that are configured
+elsewhere in the configuration file and even including your clock
+pseudopeer(s), in any. Hence, if you specify a default set of
+restrictions which you don't wish to be applied to your configured
+peers, you must remove those restrictions for the configured peers with
+additional restrict declarations mentioning each peer separately.
+
+Authentication
+
+Xntpd supports the optional authentication procedure specified in the
+NTP Version 2 and 3 specifications. Briefly, when an association runs in
+authenticated mode, each packet transmitted has appended to it a 32-bit
+key ID and a 64-bit crypto checksum of the contents of the packet
+computed using either the Data Encryption Standard (DES) or Message
+Digest (MD5) algorithms. Note that while either of these algorithms
+provide sufficient protection from message-modification attacks,
+distribution of the former algorithm implementation is restricted to the
+U.S. and Canada, while the latter presently is free from such
+restrictions. With either algorithm the receiving peer recomputes the
+checksum and compares it with the one included in the packet. For this
+to work, the peers must share at least one encryption key and,
+furthermore, must associate the shared key with the same key ID.
+
+This facility requires some minor modifications to the basic packet
+processing procedures, as required by the specification. These
+modifications are enabled by the "authenticate" configuration
+declaration. In particular, in authenticated mode, peers which send
+unauthenticated packets, peers which send authenticated packets which
+the local server is unable to decrypt and peers which send authenticated
+packets encrypted using a key we don't trust are all marked
+untrustworthy and unsuitable for synchronization. Note that, while the
+server may know many keys (identified by many key IDs), it is possible
+to declare only a subset of these as trusted. This allows the server to
+share keys with a client which requires authenticated time and which
+trusts the server but which is not trusted by the server. Also, some
+additional configuration language is required to specify the key ID to
+be used to authenticate each configured peer association. Hence, for a
+server running in authenticated mode, the configuration file might look
+similar to the following:
+
+     # peer configuration for 128.100.100.7
+     # (expected to operate at stratum 2)
+     # fully authenticated this time
+
+     peer 128.100.49.105 key 22    # suzuki.ccie.utoronto.ca
+     peer 128.8.10.1 key 4    # umd1.umd.edu
+     peer 192.35.82.50 key 6  # lilben.tn.cornell.edu
+     authenticate yes         # enable authentication
+     keys /usr/local/bin/ntp.keys  # path for key file
+     trustedkey 1 2 14 15     # define trusted keys
+     requestkey 15            # key (7) for accessing server variables
+     controlkey 15            # key (6) for accessing server variables
+
+     #authdelay 0.000047      # authentication delay (Sun4c/50 IPX DES)
+     authdelay 0.000094       # authentication delay (Sun4c/50 IPX MD5)
+
+There are a couple of previously unmentioned things in here. The
+"authenticate yes" line enables authentication processing, while the
+"keys /usr/local/bin/ntp.keys" specifies the path to the keys file (see
+below and the xntpd.8 man page for detaiils of the file format). The
+"trustedkey" declaration identifies those keys that are known to be
+uncompromised; the remainder presumably represent the expired or
+possibly compromised keys. Both sets of keys must be declared by key
+identifier in the ntp.keys file described below. This provides a way to
+retire old keys while minimrequestkey 15izing the frequency of delicate
+key-distribution procedures. The "requestkey 15" line establishes the
+key to be used for mode-6 control messages as specified in RFC 1305 and
+used by the ntpq utility program, while the "controlkey 15" establishes
+the key to be used for mode-7 private control messages used by the
+xntpdc utility program these keys are used to prevent unauthorized
+modification of daemon variables.
+
+The "authdelay" declaration is an estimate of the amount of processing
+time taken between the freezing of a transmit timestamp and the actual
+transmission of the packet when authentication is enabled (i.e. more or
+less the time it takes for the DES or MD5 routine to encrypt a single
+block), and is used as a correction for the transmit timestamp. This can
+be computed for your CPU by the authspeed program included in the
+authstuff directory in the xntp3 distribution. The usage is illustrated
+to the following:
+
+     # for DES keys
+
+     authspeed -n 30000 auth.samplekeys
+
+     # for MD5 keys
+
+     authspeed -nd 30000 auth.samplekeys
+
+Additional utility programs included in the authstuff directory can be
+used to generate random keys, certify implementation correctness and
+display sample keys. As a general rule, keys should be chosen randomly,
+except possibly the request and control keys, which must be entered by
+the user as a password.
+
+The ntp.keys file contains the list of keys and associated key IDs the
+server knows about (for obvious reasons this file is better left
+unreadable by anyone except the server). The contents of this file might
+look like:
+
+     # ntp keys file (ntp.keys)
+
+     1    N    29233E0461ECD6AE    # des key in NTP format
+     2    M    RIrop8KPPvQvYotM    # md5 key as an ASCII random string
+     14   M    sundial             # md5 key as an ASCII string
+     15   A    sundial             # des key as an ASCII string
+
+     # the following 3 keys are identical
+
+     10   A    SeCReT
+     10   N    d3e54352e5548080
+     10   S    a7cb86a4cba80101
+
+In the keys file the first token on each line indicates the key ID, the
+second token the format of the key and the third the key itself. There
+are four key formats. An "A" indicates a DES key written as a 1-to-8
+character string in 7-bit ASCII representation, with each character
+standing for a key octet (like a Unix password). An "S" indicates a DES
+key written as a hex number in the DES standard format, with the low
+order bit (LSB) of each octet being the (odd) parity bit. An "N"
+indicates a DES key again written as a hex number, but in NTP standard
+format with the high order bit of each octet being the (odd) parity bit
+(confusing enough?). An "M" indicates an MD5 key written as a 1-to-31
+character ASCII string in the "A" format. Note that, because of the
+simple tokenizing routine, the characters ' ', '#', '\t', '\n' and '\0'
+can't be used in either a DES or MD5 ASCII key. Everything else is fair
+game, though. Key 0 (zero) is used for special purposes and should not
+appear in this file.
+
+The big trouble with the authentication facility is the keys file. It is
+a maintenance headache and a security problem. This should be fixed some
+day. Presumably, this whole bag of worms goes away if/when a generic
+security regime for the Internet is established.
+
+Query Programs
+
+Three utility query programs are included with the xntp3 distribution,
+ntpq, ntptrace and xntpdc. Ntpq is a rather handy program which sends
+queries and receives responses using NTP standard mode-6 control
+messages. Since it uses the standard control protocol specified in RFC
+1305, it may be used with NTP Version 2 and Version 3 implementations
+for both Unix and Fuzzball, but not Version 1 implementations. It is
+most useful to query remote NTP implementations to assess timekeeping
+accuracy and expose bugs in configuration or operation.
+
+Ntptrace can be used to display the current synchronization path from a
+selected host through possibly intervening servers to the primary source
+of synchronization, usually a radio clock. It works with both version 2
+and version 3 servers, but not version 1.
+
+Xnptdc is a horrid program which uses NTP private mode-7 control
+messages to query local or remote servers. The format and and contents
+of these messages are specific to xntpd. The program does allow
+inspection of a wide variety of internal counters and other state data,
+and hence does make a pretty good debugging tool, even if it is
+frustrating to use. The other thing of note about xntpdc is that it
+provides a user interface to the run time reconfiguration facility.
+
+See the respective man pages for details on the use of these programs.
+The primary reason for mentioning them here is to point out an
+inconsistancy which can be awfully annoying if it catches you, and which
+is worth keeping firmly in mind. Both xntpdc and xntpd demand that
+anything which has dimensions of time be specified in units of seconds,
+both in the configuration file and when doing run time reconfiguration.
+Both programs also print the values in seconds. Ntpq on the other hand,
+obeys the standard by printing all time values in milliseconds. This
+makes the process of looking at values with ntpq and then changing them
+in the configuration file or with xntpdc very prone to errors (by three
+orders of magnitude). I wish this problem didn't exist, but xntpd and
+its love of seconds predate the mode-6 protocol and the latter's
+(Fuzzball-inspired) millisecond orientation, making the inconsistancy
+irresolvable without considerable work.
+
+Run Time Reconfiguration
+
+Xntpd was written specifically to allow its configuration to be fully
+modifiable at run time. Indeed, the only way to configure the server is
+at run time. The configuration file is read only after the rest of the
+server has been initialized into a running, but default unconfigured,
+state. This facility was included not so much for the benefit of Unix,
+where it is handy but not strictly essential, but rather for dedicated
+platforms where the feature is more important for maintenance.
+Nevertheless, run time configuration works very nicely for Unix servers
+as well.
+
+Nearly all of the things it is possible to configure in the
+configuration file may be altered via NTP mode-7 messages using the
+xntpdc program. Mode-6 messages may also provide some limited
+configuration functionality (though the only thing you can currently do
+with mode-6 messages is set the leap-second warning bits) and the ntpq
+program provides generic support for the latter. The leap bits that can be
+set in the leap_warning variable (up to one month ahead) and in the
+leap_indication variable have a slighly different encoding than the
+usual interpretation:
+
+	Value		Action
+	 00		The daemon passes the leap bits of its 
+			synchronisation source (usual mode of operation)
+	01/10		A leap second is added/deleted
+	 11		Leap information from the sychronisation source
+			is ignored (thus LEAP_NOWARNING is passed on)
+
+Mode-6 and mode-7 messages which would modify the configuration of the
+server are required to be authenticated using standard NTP
+authentication. To enable the facilities one must, in addition to
+specifying the location of a keys file, indicate in the configuration
+file the key IDs to be used for authenticating reconfiguration commands.
+Hence the following fragment might be added to a configuration file to
+enable the mode-6 (ntpq) and mode-7 (xntpdc) facilities in the daemon:
+
+     # specify mode-6 and mode-7 trusted keys
+
+     requestkey 65535    # for mode-7 requests
+     controlkey 65534    # for mode-6 requests
+
+If the "requestkey" and/or the "controlkey" configuration declarations
+are omitted from the configuration file, the corresponding run time
+reconfiguration facility is disabled.
+
+The query programs require the user to specify a key ID and a key to use
+for authenticating requests to be sent. The key ID provided should be
+the same as the one mentioned in the configuration file, while the key
+should match that corresponding to the key ID in the keys file. As the
+query programs prompt for the key as a password, it is useful to make
+the request and control authentication keys typable (in ASCII format)
+from the keyboard.
+
+Name Resolution
+
+Xntpd includes the cability to specify host names requiring resolution
+in "peer" and "server" declarations in the configuration file. There are
+several reasons why this was not permitted in the past. Chief among
+these is the fact that name service is unreliable and the interface to
+the Unix resolver routines is synchronous. The hangups and delays
+resulting from name-resolver clanking can be unacceptable once the NTP
+server is running (and remember it is up and running before the
+configuration file is read). However, it is advantageous to resolve time
+server names, since their addresses are occasionally changed.
+
+Instead of running the resolver itself the daemon can defer this task to
+a separate program, xntpres. When the daemon comes across a "peer" or
+"server" entry with a non-numeric host address it records the relevant
+information in a temporary file and continues on. When the end of the
+configuration file has been reached and one or more entries requiring
+name resolution have been found, the server runs an instance of xntpres
+with the temporary file as an argument. The server then continues on
+normally but with the offending peers/servers omitted from its
+configuration.
+
+When xntpres successfully resolves a name from this file, it configures
+the associated entry into the server using the same mode-7 run time
+reconfiguration facility that xntpdc uses. If temporary resolver
+failures occur, xntpres will periodically retry the offending requests
+until a definite response is received. The program will continue to run
+until all entries have been resolved.
+There are several configuration requirements if xntpres is to be used.
+The path to the xntpres program must be made known to the daemon via a
+"resolver" configuration entry, and mode-7 run time reconfiguration must
+be enabled. The following fragment might be used to accomplish this:
+
+     # specify host name resolver data
+
+     resolver /local/etc/xntpres
+     keys /etc/ntp.keys
+     requestkey 65535
+
+Note that xntpres sends packets to the server with a source address of
+127.0.0.1. You should obviously avoid "restrict" modification requests
+from this address or xntpres will fail.
+
+Dealing with Frequency Tolerance Violations (Tickadj and Friends)
+
+The NTP Version 3 specification RFC 1305 calls for a maximum oscillator
+frequency tolerance of +-100 parts-per-million (ppm), which is
+representative of those components suitable for use in relatively
+inexpensive workstation platforms. For those platforms meeting this
+tolerance, NTP will automatically compensate for the frequency errors of
+the individual oscillator and no further adjustments are required,
+either to the configuration file or to various kernel variables.
+
+However, in the case of certain notorious platforms, in particular Sun
+4s, the 100-ppm tolerance is routinely violated. In such cases it may be
+necessary to adjust the values of certain kernel variables; in
+particular, "tick" and "tickadj". The variable tick is the increment in
+microseconds added to the system time on each interval-timer interrupt,
+while the variable tickadj is used by the time adjustment code as a slew
+rate. When the time is being adjusted via a call to the system routine
+adjtime(), the kernel increases or reduces tick by tickadj microseconds
+until the specified adjustment has been completed. Unfortunately, in
+most Unix implementations the tick increment must be either zero or
+plus/minus exactly tickadj microseconds, meaning that adjustments are
+truncated to be an integral multiple of tickadj (this latter behaviour
+is a misfeature, and is the only reason the xntpd code needs to concern
+itself with the internal implementation of adjtime() at all). In
+addition, the stock Unix implementation considers it an error to request
+another adjustment before a prior one has completed.
+
+Thus, to make very sure it avoids problems related to the roundoff, the
+xntpd daemon reads the values of tick and tickadj from /dev/kmem when it
+starts. It then ensures that all adjustments given to adjtime() are an
+even multiple of tickadj microseconds and computes the largest
+adjustment that can be completed in the adjustment interval (using both
+the value of tickadj and the value of tick) so it can avoid exceeding
+this limit.
+
+Unfortunately, the value of tickadj set by default is almost always too
+large for xntpd. NTP operates by continuously making small adjustments
+to the clock, usually at one-second intervals. If tickadj is set too
+large, the adjustments will disappear in the roundoff; while, if tickadj
+is too small, NTP will have difficulty if it needs to make an occasional
+large adjustment. While the daemon itself will read the kernel's values
+of tick and tickadj, it will not change the values, even if they are
+unsuitable. You must do this yourself before the daemon is started,
+either with adb or, in the running kernel only, with the tickadj program
+included in the util directory of the xntp3 distribution. Note that the
+latter program will also computes an optimal value of tickadj for NTP
+use based on the kernel's value of tick.
+
+The tickadj program can reset several other kernel variables if asked.
+It can also change the value of tick if asked, this being necessary on a
+few machines with very broken clocks, like Sun 4s. With these machines
+it should also set the value of the kernel dosynctodr variable to zero.
+This variable controls whether to synchronize the system clock to the
+time-of-day clock, something you really don't want to be happen when
+xntpd is trying to keep it under control.
+
+In order to maintain reasonable correctness bounds, as well as
+reasonably good accuracy with acceptable polling intervals, xntpd will
+complain if the frequency error is greater than 100 ppm. For machines
+with a value of tick in the 10-ms range, a change of one in the value of
+tick will change the frequency by about 100 ppm. In order to determine
+the value of tick for a particular CPU, disconnect the machine from all
+sources of time (dosynctodr = 0) and record its actual time compared to
+an outside source (eyeball-and-wristwatch will do) over a day or more.
+Multiply the time change over the day by 0.116 and add or subtract the
+result to tick, depending on whether the CPU is fast or slow. An example
+call to tickadj useful on Sun 4s is:
+
+     tickadj -t 9999 -a 5 -s
+
+which sets tick 100 ppm fast, tickadj to 5 microseconds and turns off
+the clock/calendar chip fiddle. This line can be added to the rc.local
+configuration file to automatically set the kernel variables at boot
+time.
+
+All this stuff about diddling kernel variables so the NTP daemon will
+work is really silly. If vendors would ship machines with clocks that
+kept reasonable time and would make their adjtime() system call apply
+the slew it is given exactly, independent of the value of tickadj, all
+this could go away.
+
+Tuning Your Subnet
+
+There are several parameters available for tuning the NTP subnet for
+maximum accuracy and minimum jitter. Two important parameters are the
+the "precision" and "prefer" configuration declarations. The precision
+declaration specifies the number of significant bits of the system clock
+representation relative to one second. For instance, the default value
+of -6 corresponds to 1/64 second or about 16 milliseconds.
+
+The NTP protocol makes use of the precision parameter in several places.
+It is included in packets sent to peers and is used by them to calculate
+the maximum absolute error and maximum statistical error. When faced
+with selecting one of several servers of the same stratum and about the
+same network path delay for synchronization purposes, clients will
+usually prefer to synchronize to those servers claiming the smallest
+(most negative) precision, since this maximizes the accuracy and
+minimizes the jitter apparent to application programs running on the
+client platform. Therefore, when the maximum attainable accuracy is
+required, it is important that every platform configure an accurate
+value for the precision variable. This can be done using the optional
+"precision" declaration in the configuration file:
+
+     # precision declaration
+
+     precision -18       # for microsecond clocks (Sun 4s, DEC 5000/240)
+
+When more than one eligible server exists, the NTP clock-selection and
+combining algorithms act to winnow out all except the "best" set of
+servers using several criteria based on differences between the readings
+of different servers and between successive readings of the same server.
+The result is usually a set of surviving servers that are apparently
+statistically equivalent in accuracy, jitter and stability. The
+population of survivors remaining in this set depends on the individual
+server characteristics measured during the selection process and may
+vary from time to time as the result of normal statistical variations.
+In LANs with high speed RISC-based time servers, the population can
+become somewhat unstable, with individual servers popping in and out of
+the surviving population, generally resulting in a regime called
+clockhopping.
+
+When only the smallest residual jitter can be tolerated, it may be
+convenient to elect one of the servers at each stratum level as the
+preferred one using the keyword "prefer" on the configuration
+declaration for the selected server:
+
+     # prefered server declaration
+
+     peer 128.4.1.1 prefer    # preferred server
+
+The preferred server will always be included in the surviving
+population, regardless of its characteristics and as long as it survives
+preliminary sanity checks and validation procedures.
+
+The most useful application of the prefer keyword is in high speed LANs
+equipped with precision radio clocks, such as a GPS receiver. In order
+to insure robustness, the hosts need to include outside peers as well as
+the GPS-equipped server; however, as long as that server is running, the
+synchronization preference should be that server. The keyword should
+normally be used in all cases in order to prefer an attached radio
+clock. It is probably inadvisable to use this keyword for peers outside
+the LAN, since it interferes with the carefully crafted judgement of the
+selection and combining algorithms.
+
+Provisions for Leap Seconds and Accuracy Metrics
+
+Xntpd understands leap seconds and will attempt to take appropriate
+action when one occurs. In principle, every host running xntpd will
+insert a leap second in the local timescale in precise synchronization
+with UTC. This requires that the leap-warning bits be manually activated
+some time prior to the occurance of a leap second at the primary
+(stratum 1) servers. Subsequently, these bits are propagated throughout
+the subnet depending on these servers by the NTP protocol itself and
+automatically implemented by xntpd and the time-conversion routines of
+each host. The implementation is independent of the idiosyncracies of
+the particular radio clock, which vary widely among the various devices,
+as long as the idiosyncratic behavior does not last for more than about
+20 minutes following the leap. Provisions are included to modify the
+behavior in cases where this cannot be guaranteed.
+
+While provisions for leap seconds have been carefully crafted so that
+correct timekeeping immediately before, during and after the occurance
+of a leap second is scrupulously correct, stock Unix systems are mostly
+inept in responding to the available information. This caveat goes also
+for the maximum-error and statistical-error bounds carefully calculated
+for all clients and servers, which could be very useful for application
+programs needing to calibrate the delays and offsets to achieve a near-
+simulataneous commit procedure, for example. While this information is
+maintained in the xntpd data structures, there is at present no way for
+application programs to access it. This may be a topic for further
+development.
+
+Clock Support Overview
+
+Xntpd was designed to support radio (and other external) clocks and does
+some parts of this function with utmost care. Clocks are treated by the
+protocol as ordinary NTP peers, even to the point of referring to them
+with an (invalid) IP host address. Clock addresses are of the form
+127.127.t.u, where t specifies the particular type of clock (i.e. refers
+to a particular clock driver) and u is a unit number whose
+interpretation is clock-driver dependent. This is analogous to the use
+of major and minor device numbers by Unix and permits multiple
+instantiations of clocks of the same type on the same server, should
+such magnificant redundancy be required.
+
+Because clocks look much like peers, both configuration file syntax and
+run time reconfiguration commands can be be used to control clocks in
+the same way as ordinary peers. Clocks are configured via "server"
+declarations in the configuration file, can be started and stopped using
+xntpdc and are subject to address-and-mask restrictions much like a
+normal peer, should this stretch of imagination ever be useful. As a
+concession to the need to sometimes transmit additional information to
+clock drivers, an additional configuration file is available: the
+"fudge" statement. This enables one to specify the values two time
+quantities, two integral values and two flags, the use of which is
+dependent on the particular clock driver. For example, to configure a
+PST radio clock which can be accessed through the serial device
+/dev/pst1, with propagation delays to WWV and WWVH of 7.5 and 26.5
+milliseconds, respectively, on a machine with an imprecise system clock
+and with the driver set to disbelieve the radio clock once it has gone
+30 minutes without an update, one might use the following configuration
+file entries:
+
+     # radio clock fudge fiddles
+
+     server 127.127.3.1
+     fudge 127.127.3.1 time1 0.0075 time2 0.0265
+     fudge 127.127.3.1 value2 30 flag1 1
+
+Additional information on the interpretation of these data with respect
+to various radio clock drivers is given in the xntpd.8 man page.
+
+Towards the Ultimate Tick
+
+This section consideres issues in providing precision time
+synchronization in NTP subnets which need the highest quality time
+available in the present technology. These issues are important in
+subnets supporting real-time services such as distributed multimedia
+conferencing and wide-are experiment control and monitoring.
+
+In the Internet of today synchronization paths often span continents and
+oceans with moderate to high variations in delay due to traffic spasms.
+NTP is specifically designed to minimize timekeeping jitter due to delay
+variations using intricately crafted filtering and selection algorithms;
+however, in cases where these variations are as much as a second or
+more, the residual jitter following these algorithms may still be
+excessive. Sometimes, as in the case of some isolated NTP subnets where
+a local source of precision time is available, such as a 1-pps signal
+produced by a calibrated cesium clock, it is possible to remove the
+jitter and retime the local clock oscillator of the NTP server. This has
+turned out to be a useful feature to improve the synchronization quality
+of time distributed in remote places where radio clocks are not
+available. In these cases special features of the xntp3 distribution are
+used together with the 1-pps signal to provide a jitter-free timing
+signal, while NTP itself is used to provide the coarse timing and
+resolve the seconds numbering.
+
+Most available radio clocks can provide time to an accuracy in the order
+of milliseconds, depending on propagation conditions, local noise levels
+and so forth. However, as a practical matter, all clocks can
+occasionally display errors significantly exceeding nominal
+specifications. Usually, the algorithms used by NTP for ordinary network
+peers, as well as radio clock "peers" will detect and discard these
+errors as discrepancies between the disciplined local clock oscillator
+and the decoded time message produced by the radio clock. Some radio
+clocks can produce a special 1-pps signal which can be interfaced to the
+server platform in a number of ways and used to substantially improve
+the (disciplined) clock oscillator jitter and wander characteristics by
+at least an order of magnitude. Using these features it is possible to
+achieve accuracies in the order of 100 microseconds with a fast RISC-
+based platform.
+
+There are three ways to implement 1-pps support, depending on the radio
+clock model, platform model and serial line interface. Each of these
+requires circuitry to convert the TTL signal produced by most clocks to
+the the EIA levels used by most serial interfaces. An example of a
+device designed to do this is presented in the gadget subdirectory
+included in the xntp3 distribtuion. Besides being useful for this
+purpose, this device includes an inexpensive modem designed for use with
+the Canadian CHU time/frequency radio station.
+
+In order to select the appropriate implementation, it is important to
+understand the underlying 1-pps mechanism used by xntpd. The 1-pps
+suport depends on a continuous source of 1-pps pulses used to calculate
+an offset within +-500 milliseconds relative to the local clock. The
+serial timecode produced by the radio or the time determined by NTP in
+absence of the radio is used to adjust the local clock within +-128
+milliseconds of the actual time. As long as the local clock is within
+this interval the 1-pps support is used to discipline the local clock
+and the timecode used only to verify that the local clock is in fact
+within the interval. Outside this interval the 1-pps support is disabled
+and the timecode used directly to control the local clock.
+
+The first method of implementation uses a dedicated serial port and
+either the bsd line discipline or System V streams module, which can be
+found in the kernel directory of the xntp3 distribution. This method can
+be used with any radio clock or in the absence of any clock. The line
+discipline and streams modules take receive timestamps in the kernel,
+specifically the interrupt routine of the serial port hardware driver.
+Using this method the port is dedicated to serve the 1-pps signal and
+cannot be used for other purposes. Instructions for implementing the
+feature, which requires rebuilding the kernel, are included in the
+modules themselves. Note that xndpd must be compiled with the -DPPSDEV
+compiler switch in this case. There is an inherent error in this method
+due to the latency of the interrupt system and remaining serial-line
+protocol modules in the order of a millisecond with Sun 4s. While the
+jitter in this latency is unavoidable, the systematic component can be
+calibrated out using a special configuration declaration:
+
+     # pps delay and baud rate
+
+     pps delay .0017 baud 19200    # pps delay (ms) and baud rate
+
+Note that the delay defaults to zero and the baud to 38400.
+
+The second method uses mechanisms embedded in the radio clock driver,
+which call the 1-pps support directly and do not require a dedicated
+serial port. Currently, only the DCF77 (German radio time service)
+driver uses this method. Instructions for implementing this are given in
+README files in the xntp3 distribution.
+
+The third method and the most accurate and intrusive of all uses the
+carrier-detect modem-control lead monitored by the serial port driver.
+This method can be used with any radio clock and 1-pps interface
+mentioned above. It requires in addition to a special streams module,
+replacement of the kernel high resolution time-of-day clock routine.
+This method is applicable only to Sun 4 platforms running SunOS 4.1.1
+and then only with either of the two onboard serial ports. It does not
+work with other platforms, operating systems or external (SBus) serial
+multiplexors.
+
+Swatting Bugs
+
+Let's say you have compiled and installed the code and put up an
+apparently relevant configuration file. In many Unix systems the xntpd
+daemon and utility programs (ntpq, ntptrace and xntpdc) are usually
+installed in the /usr/local directory along with the key file
+(ntp.keys), while the configuration file (ntp.conf) and drift file
+(ntp.drift) are installed in the /etc directory. The daemon can is
+usually started from the rc.local shell script at system boot time, but
+could be started (and stopped) at other times for debugging, etc. How do
+you verify that the daemon can form associations with remote peers and
+verify correct synchronization? For this you need the ntpq utility
+described in the ntpq.8 man page.
+
+After starting the daemon, run the ntpq program using the -n switch,
+which will avoid possible distractions due to name resolutions. Use the
+peer command to display a billboard showing the status of configured
+peers and possibly other clients poking the daemon. After operating for
+a few minutes, the display should be something like:
+
+  remote           refid      st when poll reach   delay  offset    disp
+========================================================================
++128.4.2.6    132.249.16.1     2  131  256  373     9.89   16.28   23.25
+*128.4.1.20   .WWVB.           1  137  256  377   280.62   21.74   20.23
+-128.8.2.88   128.8.10.1       2   49  128  376   294.14    5.94   17.47
++128.4.2.17   .WWVB.           1  173  256  377   279.95   20.56   16.40
+
+The hosts shown in the "remote" column should agree with the entries in
+the configuration file, plus any peers not mentioned in the file at the
+same or lower than your stratum that happen to be configured to peer
+with you. The "refid" entry shows the current source of synchronization
+for that peer, while the "st" reveals its stratum and the "poll" entry
+the polling interval, in seconds. The "when" entry shows the time since
+the peer was last heard, in seconds, while the "reach" entry shows the
+status of the reachability register (see specification), which is in
+octal format. The remaining entries show the latest delay, offset and
+dispersion computed for the peer, in milliseconds.
+
+*** This section incomplete. Soon.
+
+status=0664 leap_none, sync_ntp, 6 events, event_peer/strat_chg
+system="UNIX", leap=00, stratum=2, rootdelay=280.62,
+rootdispersion=45.26, peer=11673, refid=128.4.1.20,
+reftime=af00bb42.56111000  Fri, Jan 15 1993  4:25:38.336, poll=8,
+clock=af00bbcd.8a5de000  Fri, Jan 15 1993  4:27:57.540, phase=21.147,
+freq=13319.46, compliance=2
+
+status=7414 reach, auth, sel_sync, 1 event, event_reach
+srcadr=128.4.2.6, srcport=123, dstadr=128.4.2.7, dstport=123, keyid=1,
+stratum=2, precision=-10, rootdelay=362.00, rootdispersion=21.99,
+refid=132.249.16.1,
+reftime=af00bb44.849b0000  Fri, Jan 15 1993  4:25:40.517,
+delay=    9.89, offset=   16.28, dispersion=23.25, reach=373, valid=8,
+hmode=2, pmode=1, hpoll=8, ppoll=10, leap=00, flash=0x0,
+org=af00bb48.31a90000  Fri, Jan 15 1993  4:25:44.193,
+rec=af00bb48.305e3000  Fri, Jan 15 1993  4:25:44.188,
+xmt=af00bb1e.16689000  Fri, Jan 15 1993  4:25:02.087,
+filtdelay=  16.40   9.89 140.08   9.63   9.72   9.22  10.79 122.99,
+filtoffset= 13.24  16.28 -49.19  16.04  16.83  16.49  16.95 -39.43,
+filterror=  16.27  20.17  27.98  31.89  35.80  39.70  43.61  47.52
+
+ind assID status  conf reach auth condition  last_event cnt
+===========================================================
+  1 11670  7414    no   yes   ok    synchr.   reachable  1
+  2 11673  7614    no   yes   ok   sys.peer   reachable  1
+  3 11833  7314    no   yes   ok    outlyer   reachable  1
+  4 11868  7414    no   yes   ok    synchr.   reachable  1
+
+Parting Shots
+
+There are several undocumented programs which are useful if you are
+trying to set up a clock. They can be found in the clockstuff directory
+of the xntp3 distribution. The most useful of these is the propdelay
+program, which can compute high frequency radio propagation delays
+between any two points whose latitude and longitude are known. The
+program understands something about the phenomena which allow high
+frequency radio propagation to occur, and will generally provide a
+better estimate than a calculation based on the great circle distance.
+The other two programs in the directory are clktest, which allows one to
+exercise the generic clock line discipline, and chutest, which runs the
+basic reduction algorithms used by the daemon on data received from a
+serial port.
diff --git a/usr.sbin/xntpd/doc/ntpdate.8 b/usr.sbin/xntpd/doc/ntpdate.8
new file mode 100644
index 0000000..05be737
--- /dev/null
+++ b/usr.sbin/xntpd/doc/ntpdate.8
@@ -0,0 +1,185 @@
+''' $Header
+''' 
+.de Sh
+.br
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp
+.if t .sp .5v
+.if n .sp
+..
+.de Ip
+.br
+.ie \\n.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+'''
+'''     Set up \*(-- to give an unbreakable dash;
+'''     string Tr holds user defined translation string.
+'''     Bell System Logo is used as a dummy character.
+'''
+.tr \(bs-|\(bv\*(Tr
+.ie n \{\
+.ds -- \(bs-
+.if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch
+.if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch
+.ds L" ""
+.ds R" ""
+.ds L' '
+.ds R' '
+'br\}
+.el\{\
+.ds -- \(em\|
+.tr \*(Tr
+.ds L" ``
+.ds R" ''
+.ds L' `
+.ds R' '
+'br\}
+.TH NTPDATE 8 LOCAL
+.SH NAME
+ntpdate - set the date and time via NTP
+.SH SYNOPSIS
+.B ntpdate
+[
+.B -bdos
+] [
+.B -a
+.I key#
+] [
+.B -e
+.I authdelay
+] [
+.B -k
+.I keyfile
+] [
+.B -p
+.I samples
+] [
+.B -t
+.I timeout
+]
+server ...
+.SH DESCRIPTION
+.I Ntpdate
+sets the local date and time by polling the Network Time Protocol
+server(s) on the host(s) given as arguments to determine
+the correct time.  It must be run as root on the local host.  A number
+of samples are obtained from each of the servers specified and the
+standard NTP clock filter and selection algorithms are applied to select
+the best of these.  Typically,
+.I ntpdate
+can be inserted in the
+.I /etc/rc.local
+startup up script to set the time of day at boot time and/or can be run
+from time\-to\-time via
+.IR cron (8).
+Note that
+.IR ntpdate 's
+reliability and precision will improve dramatically with greater numbers
+of servers.  While a single server may be used, better performance and
+greater resistance to insanity on the part of any one server
+will be obtained by providing at least three or four servers, if not more.
+.PP
+Time adjustments are made by
+.I ntpdate
+in one of two ways.  If
+.I ntpdate
+determines your clock is off by more than 0.5 seconds it will simply
+step the time by calling
+.IR settimeofday (2).
+If the error is less than 0.5 seconds, however, it will by default slew
+the clock's time via a call to
+.IR adjtime (2)
+with the offset.  The latter technique is less disruptive and more
+accurate when the offset is small, and works quite well when
+.I ntpdate
+is run by
+.I cron (8)
+every hour or two.  The adjustment made in the latter
+case is actually 50% larger than the measured offset since this will
+tend to keep a badly drifting clock more accurate (at some expense to
+stability, though this tradeoff is usually advantageous).  At boot time,
+however, it is usually better to always step the time.  This can be forced
+in all cases by specifying the
+.B -b
+switch on the command line.  The
+.B -s
+switch tells
+.I ntpdate
+to log its actions via the
+.IR syslog (3)
+facility rather than to the standard output, a useful option when
+running the program from
+.IR cron (8).
+.PP
+The
+.B -d
+flag may be used to determine what
+.I ntpdate
+will do without it actually doing it.  Information useful for general
+debugging will also be printed.  By default
+.I ntpdate
+claims to be an NTP version 2 implementation in its outgoing packets.  As
+some older software will decline to respond to version 2 queries, the
+.B -o
+switch can be used to force the program to poll as a version 1 implementation
+instead.
+.PP
+The number of samples
+.I ntpdate
+acquires from each server can be set to between 1 and 8 inclusive
+using the
+.B -p
+switch.  The default is 4.  The time it will spend waiting for a
+response can be set using the
+.B -t
+switch, and will be rounded to a multiple of 0.2 seconds.  The default
+is 1 second, a value suitable for polling across a LAN.
+.PP
+.I Ntpdate
+will authenticate its transactions if need be.  The
+.B -a
+switch specifies that all packets should be authenticated using the
+key number indicated.  The
+.B -k
+switch allows the name of the file from which the keys may be read
+to be modified from the default of
+.I /etc/ntp.keys.
+This file should be in the format described in
+.IR xntpd (8).
+The
+.B -e
+option allows the specification of an authentication processing delay,
+in seconds (see
+.IR xntpd (8)
+for details).  This number is usually small enough to be negligible for
+.IR ntpdate 's
+purposes, though specifying a value may improve timekeeping on very slow
+CPU's.
+.PP
+.I Ntpdate
+will decline to set the date if an NTP server daemon (e.g.
+.IR xntpd (8))
+is running on the same host.  When running
+.I ntpdate
+on a regular basis from
+.IR cron (8)
+as an alternative to running a daemon, doing so once every hour or two
+will result in precise enough timekeeping to avoid stepping the clock.
+.SH FILES
+.nf
+/etc/ntp.keys\0\0contains the encription keys used by \fIntpdate\fP.
+.fi
+.SH SEE ALSO
+xntpd(8)
+.SH HISTORY
+Written by Dennis Ferguson at the University of Toronto
+.SH BUGS
+The technique used for improving accuracy by compensating for clock
+oscillator errors sucks, but doing better would require the program
+to save state from previous runs.
diff --git a/usr.sbin/xntpd/doc/ntpq.8 b/usr.sbin/xntpd/doc/ntpq.8
new file mode 100644
index 0000000..81aca09
--- /dev/null
+++ b/usr.sbin/xntpd/doc/ntpq.8
@@ -0,0 +1,566 @@
+''' $Header
+''' 
+.de Sh
+.br
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp
+.if t .sp .5v
+.if n .sp
+..
+.de Ip
+.br
+.ie \\n.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+'''
+'''     Set up \*(-- to give an unbreakable dash;
+'''     string Tr holds user defined translation string.
+'''     Bell System Logo is used as a dummy character.
+'''
+.tr \(bs-|\(bv\*(Tr
+.ie n \{\
+.ds -- \(bs-
+.if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch
+.if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch
+.ds L" ""
+.ds R" ""
+.ds L' '
+.ds R' '
+'br\}
+.el\{\
+.ds -- \(em\|
+.tr \*(Tr
+.ds L" ``
+.ds R" ''
+.ds L' `
+.ds R' '
+'br\}
+.TH NTPQ 8 LOCAL
+.SH NAME
+ntpq - standard Network Time Protocol query program
+.SH SYNOPSIS
+.B ntpq
+[
+.B -inp
+] [
+.B -c 
+.I command
+] [
+.I host
+] [
+.I ...
+]
+.SH DESCRIPTION
+.I Ntpq
+is used to query NTP servers which implement the recommended NTP
+mode 6 control message format about current state and to request
+changes in that state.  The
+program may be run either in interactive mode or controlled using
+command line arguments.  Requests to read and write arbitrary
+variables can be assembled, with raw and pretty\-printed output
+options being available.
+.I Ntpq
+can also obtain and print a list of peers in a common format
+by sending multiple queries to the server.
+.PP
+If one or more request options is included on the command line when
+.I ntpq
+is executed, each of the requests will be sent to the NTP servers running
+on each of the hosts given as command line arguments, or on
+.I localhost
+by default.  If no request options are given,
+.I ntpq
+will attempt to read commands from the standard input and execute these
+on the NTP server running on the first host given on the command line, again
+defaulting to
+.I localhost
+when no other host is specified.
+.I Ntpq
+will prompt for commands if the standard input is a terminal device.
+.PP
+.I Ntpq
+uses NTP mode 6 packets to communicate with the NTP server, and hence
+can be used to query any compatable server on the network which permits
+it.  Note that since NTP is a UDP protocol this communication will be
+somewhat unreliable, especially over large distances in terms of network
+topology.
+.I Ntpq
+makes one attempt to retransmit requests, and will time requests out if
+the remote host is not heard from within a suitable time out time.
+.PP
+Command line options are described following.  Specifying a command
+line option other than
+.B -i
+or
+.B -n
+will cause the specified query (queries) to be sent to the indicated
+host(s) immediately.  Otherwise,
+.I ntpq
+will attempt to read interactive format commands from the standard input.
+.Ip -c 8
+The following argument is interpreted as an interactive format command
+and is added to the list of commands to be executed on the specified
+host(s).  Multiple
+.B -c
+options may be given.
+.Ip -i 8
+Force
+.I ntpq
+to operate in interactive mode.  Prompts will be written to the
+standard output and commands read from the standard input.
+.Ip -n 8
+Output all host addresses in dotted\-quad numeric format rather than
+converting to the canonical host names.
+.Ip -p 8
+Print a list of the peers known to the server as well as a summary
+of their state.  This is equivalent to the \*(L"peers\*(R" interactive
+command.
+.SH INTERNAL COMMANDS
+.PP
+Interactive format commands consist of a keyword followed by zero
+to four arguments.  Only enough characters of the full keyword to
+uniquely identify the command need be typed.  The output of a command
+is normally sent to the standard output, but optionally the output of
+individual commands may be sent to a file by appending a \*(L">\*(R",
+followed by a file name, to the command line.
+.PP
+A number of interactive format commands are executed entirely within the
+.I ntpq
+program itself and do not result in NTP mode 6 requests being sent
+to a server.  These are described following.
+.PP
+.B ?
+[
+.I command_keyword
+}
+.PP
+A \*(L"?\*(R" by itself will print a list of all the command keywords
+known to this incarnation of
+.IR ntpq .
+A \*(L"?\*(R" followed by a command keyword will print funcation and
+usage information about the command.  This command is probably a better
+source of information about
+.I ntpq
+than this manual page.
+.PP
+.B timeout
+.I millseconds
+.PP
+Specify a time out period for responses to server queries.  The default
+is about 5000 milliseconds.  Note that since
+.I ntpq
+retries each query once after a time out the total waiting time for a
+time out will be twice the time out value set.
+.PP
+.B delay
+.I milliseconds
+.PP
+Specify a time interval to be added to timestamps included in requests
+which require authentication.  This is used to enable (unreliable) server
+reconfiguration over long delay network paths or between machines whose
+clocks are unsynchronized.  Actually the server does not now require
+time stamps in authenticated requests, so this command may be obsolete.
+.PP
+.B host
+.I hostname
+.PP
+Set the host to which future queries will be sent.
+.I Hostname
+may be either a host name or a numeric
+address.
+.PP
+.B poll
+[
+.I #
+] [
+.B verbose
+]
+.PP
+Poll the current server in client mode.  The first argument is the
+number of times to poll (default is 1) while the second argument may
+be given to obtain a more detailed output of the results.  This command
+is currently just wishful thinking.
+.PP
+.B keyid
+.I #
+.PP
+This command allows the specification of a key number to be used to
+authenticate configuration requests.  This must correspond to a
+key number the server has been configured to use for this purpose.
+.PP
+.B passwd
+.PP
+This command prompts you to type in a password (which will not be
+echoed) which will be used to authenticate configuration requests.  The
+password must correspond to the key configured for use by the NTP
+server for this purpose if such requests are to be successful.
+.PP
+.B "hostnames yes|no"
+.PP
+If \*(L"yes\*(R" is specified, host names are printed in information
+displays.  If \*(L"no\*(R" is given, numeric addresses are printed
+instead.  The default is \*(L"yes\*(R" unless modified using the command
+line
+.B -n
+switch.
+.PP
+.B raw
+.PP
+Causes all output from query commands is printed as received from the
+remote server.  The only formating/intepretation done on the data is
+to transform nonascii data into a printable (but barely understandable)
+form.
+.PP
+.B cooked
+.PP
+Causes output from query commands to be \*(L"cooked\*(R".  Variables
+which are recognized by the server will have their values reformatted
+for human consumption.  Variables which
+.I ntpq
+thinks should have a decodeable value but didn't are marked with a
+trailing \*(L"?\*(R".
+.PP
+.B ntpversion
+.B 1|2|3
+.PP
+Sets the NTP version number which
+.I ntpq
+claims in packets.  Defaults to 3, Note that mode 6 control messages (and modes,
+for that matter) didn't exist in NTP version 1.  There appear to be no
+servers left which demand version 1.
+.PP
+.B authenticate
+.B yes|no
+.PP
+Normally
+.I ntpq
+does not authenticate requests unless they are write requests.  The command
+.B authenticate yes
+causes
+.I ntpq
+to send authentication with all requests it makes.  Authenticated requests
+causes some servers to handle requests slightly differently, and can
+occasionally melt the CPU in fuzzballs if you turn authentication on before
+doing a peer display.
+.PP
+.B addvars
+.IR <variable_name>[=<value>] [,...]
+.B rmvars
+.IR <variable_name> [,...]
+.B clearvars
+.PP
+The data carried by NTP mode 6 messages consists of a list of items
+of the form
+.IP "" 8
+<variable_name>=<value>
+.PP
+where the \*(L"=<value>\*(R" is ignored, and can be omitted, in requests
+to the server to read variables.
+.I Ntpq
+maintains an internal list in which data to be included in control messages
+can be assembled, and sent using
+the
+.B readlist
+and
+.B writelist
+commands described below.  The
+.B addvars
+command allows variables and their optional values to be added to the
+list.  If more than one variable is to be added, the list should be
+comma\-separated and not contain white space.  The
+.B rmvars
+command can be used to remove individual variables from the list, while
+the
+.B clearlist
+command removes all variables from the list.
+.PP
+.B debug
+.I more|less|off
+.PP
+Turns internal query program debugging on and off.
+.PP
+.B quit
+.PP
+Exit
+.IR ntpq .
+.SH CONTROL MESSAGE COMMANDS
+.PP
+Each peer known to an NTP server has a 16 bit integer
+.I association
+.I identifier
+assigned to it.  NTP control messages which carry peer variables
+must identify the peer the values correspond to by including
+its association ID.  An association ID of 0 is special, and indicates
+the variables are system variables, whose names are drawn from a
+separate name space.
+.PP
+Control message commands result in one or more NTP mode 6
+messages being sent to the server, and cause the data returned to be
+printed in some format.  Most commands currently implemented send a single
+message and expect a single response.  The current exceptions are the
+.B peers
+command, which will send a preprogrammed series of messages to obtain
+the data it needs, and the
+.B mreadlist
+and
+.B mreadvar
+commands, which will iterate over a range of associations.
+.PP
+.B associations
+.PP
+Obtains and prints a list of association identifiers and
+peer statuses for in\-spec
+peers of the server being queried.  The list is printed in
+columns.  The first of these is an index numbering the associations
+from 1 for internal use, the second the actual association identifier
+returned by the server and the third the status word for the peer.  This
+is followed by a number of columns containing data decoded from the
+status word.  Note
+that the data returned by the \*(L"associations\*(R" command is cached
+internally in
+.IR ntpq .
+The index is then of use when dealing with stupid servers which use
+association identifiers which are hard for humans to type, in that
+for any subsequent commands which require an association identifier
+as an argument, the form
+.I &index
+may be used as an alternative.
+.PP
+.B lassocations
+.PP
+Obtains and prints a list of association identifiers and peer statuses
+for all associations for which the server is maintaining state.  This
+command differs from the
+\*(L"associations\*(R"
+command only for servers which retain state for out\-of\-spec client
+associations (i.e. fuzzballs).  Such associations are normally omitted
+from the display when the
+\*(L"associations\*(R"
+command is used, but are included in the output of
+\*(L"lassociations\*(R".
+.PP
+.B passociations
+.PP
+Prints association data concerning in\-spec peers from the internally cached
+list of associations.  This command performs
+identically to the \*(L"associations\*(R" except that it displays the
+internally stored data rather than making a new query.
+.PP
+.B lpassociations
+.PP
+Print data for all associations, including out\-of\-spec client
+associations, from the internally cached list of associations.  This command
+differs from \*(L"passociations\*(R" only when dealing with fuzzballs.
+.PP
+.B pstatus
+.I assocID
+.PP
+Sends a read status request to the server for the given association.
+The names and values of the peer variables returned will be printed.  Note
+that the status word from the header is displayed preceding the variables,
+both in hexidecimal and in pidgeon English.
+.PP
+.B readvar
+[
+.I assocID
+] [
+.IR <variable_name>[=<value>] [,...]
+]
+.PP
+Requests that the values of the specified variables be returned by the
+server by sending a read variables request.  If the association ID
+is omitted or is given as zero the variables
+are system variables, otherwise they
+are peer variables and the values returned will be those
+of the corresponding peer.  Omitting the variable list will send a
+request with no data which should induce the server to return a
+default display.
+.PP
+.B rv
+[
+.I assocID
+] [
+.IR <variable_name>[=<value>] [,...]
+]
+.PP
+An easy\-to\-type short form for the
+.B readvar
+command.
+.PP
+.B writevar
+.I assocID
+.IR <variable_name>=<value> [,...]
+.PP
+Like the
+.B readvar
+request, except the specified variables are written instead of read.
+.PP
+.B readlist
+[
+.I assocID
+]
+.PP
+Requests that the values of the variables in the internal variable
+list be returned by the server.  If the association ID is omitted
+or is 0 the variables are assumed to be system variables.  Otherwise
+they are treated as peer variables.  If the internal variable list
+is empty a request is sent without data, which should induce the remote
+server to return a default display.
+.PP
+.B rl
+[
+.I assocID
+]
+.PP
+An easy\-to\-type short form of the
+.B readlist
+command.
+.PP
+.B writelist
+[
+.I assocID
+]
+.PP
+Like the
+.B readlist
+request, except the internal list variables are written instead of
+read.
+.PP
+.B mreadvar
+.I assocID
+.I assocID
+[
+.IR <variable_name>[=<value>] [,...]
+]
+.PP
+Like the
+.B readvar
+command except the query is done for each of a range of (nonzero)
+association IDs.  This range is determined from the association list
+cached by the most recent
+.B associations
+command.
+.PP
+.B mrv
+.I assocID
+.I assocID
+[
+.IR <variable_name>[=<value>] [,...]
+]
+.PP
+An easy\-to\-type short form of the
+.B mreadvar
+command.
+.PP
+.B mreadlist
+.I assocID
+.I assocID
+.PP
+Like the
+.B readlist
+command except the query is done for each of a range of (nonzero)
+association IDs.  This range is determined from the association list
+cached by the most recent
+.B associations
+command.
+.PP
+.B mrl
+.I assocID
+.I assocID
+.PP
+An easy\-to\-type short form of the
+.B mreadlist
+command.
+.PP
+.B clockvar
+[
+.I assocID
+]
+[
+.IR <variable_name>[=<value>] [,...]
+]
+.PP
+Requests that a list of the server's clock variables be sent.  Servers
+which have a radio clock or other external synchronization will respond
+positively to this.  If the association identifier is omitted or zero
+the request is for the variables of the \*(L"system clock\*(R" and will
+generally get a positive response from all servers with a clock.  If the
+server treats clocks as pseudo\-peers, and hence can possibly have more than
+one clock connected at once, referencing the appropriate
+peer association ID will show the variables of a particular clock.  Omitting
+the variable list will cause the server to return a default variable display.
+.PP
+.B cv
+[
+.I assocID
+]
+[
+.IR <variable_name>[=<value>] [,...]
+]
+.PP
+An easy\-to\-type short form of the
+.B clockvar
+command.
+.PP
+.B peers
+.PP
+Obtains a list of in\-spec peers of the server, along
+with a summary of each peer's state.  Summary information includes the address
+of the remote peer, the reference ID (0.0.0.0 if the refID is unknown),
+the stratum of the remote peer, the polling interval,
+in seconds, the reachability
+register, in octal, and the current estimated delay, offset and dispersion
+of the peer, all in seconds.
+.PP
+The character in the left margin indicates the fate of this peer in the
+clock selection process. The codes mean: <sp> discarded due to high stratum
+and/or failed sanity checks; \*(L"x\*(R" designated falsticker by the
+intersection algorithm; \*(L".\*(R" culled from the end of the candidate
+list; \*(L"-\*(R" discarded by the clustering algorithmi; \*(L"+\*(R"
+included in the final selection set; \*(L"#\*(R" selected for synchronizatio;n
+but distance exceeds maximum; \*(L"*\*(R" selected for synchronization; and
+\*(L"o\*(R" selected for synchronization, pps signal in use.
+.PP
+Note that since the
+.B peers
+command depends on the ability to parse the values in the
+responses it gets it may fail to work from time to time with servers
+which poorly control the data formats.
+.PP
+The contents of the host field may be one of four forms. It may be a host name,
+an IP address, a reference clock implementation name with its parameter or
+\*(L"REFCLK(<implementation number>, <parameter>)\*(R". On \*(L"hostnames no\*(R"
+only IP\-addresses will be displayed.
+.PP
+.B lpeers
+.PP
+Like
+.BR peers ,
+except a summary of all associations for which the server is maintaining
+state is printed.  This can produce a much longer list of peers from
+fuzzball servers.
+.PP
+.B opeers
+.PP
+An old form of the \*(L"peers\*(R" command with the reference ID
+replaced by the local interface address.
+.SH HISTORY
+.PP
+Written by Dennis Ferguson at the University of Toronto.
+.SH BUGS
+.PP
+The
+.B peers
+command is non\-atomic and may occasionally result in spurious error
+messages about invalid associations occuring and terminating the
+command.
+.PP
+The timeout time is a fixed constant, which means you wait a long time
+for time outs since it assumes sort of a worst case.  The program
+should improve the time out estimate as it sends queries to a particular
+host, but doesn't.
diff --git a/usr.sbin/xntpd/doc/ntptrace.8 b/usr.sbin/xntpd/doc/ntptrace.8
new file mode 100644
index 0000000..fb93ebb
--- /dev/null
+++ b/usr.sbin/xntpd/doc/ntptrace.8
@@ -0,0 +1,104 @@
+''' $Header
+''' 
+.de Sh
+.br
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp
+.if t .sp .5v
+.if n .sp
+..
+.de Ip
+.br
+.ie \\n.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+'''
+'''     Set up \*(-- to give an unbreakable dash;
+'''     string Tr holds user defined translation string.
+'''     Bell System Logo is used as a dummy character.
+'''
+.tr \(bs-|\(bv\*(Tr
+.ie n \{\
+.ds -- \(bs-
+.if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch
+.if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch
+.ds L" ""
+.ds R" ""
+.ds L' '
+.ds R' '
+'br\}
+.el\{\
+.ds -- \(em\|
+.tr \*(Tr
+.ds L" ``
+.ds R" ''
+.ds L' `
+.ds R' '
+'br\}
+.TH NTPTRACE 8 LOCAL
+.SH NAME
+ntptrace - trace a chain of NTP hosts back to their master time source
+.SH SYNOPSIS
+.B ntptrace
+[
+.B -vdn
+] [
+.B -r
+.I retries
+] [
+.B -t
+.I timeout
+] [
+.I server
+]
+.SH DESCRIPTION
+.I Ntptrace
+determines where a given Network Time Protocol (NTP) server gets
+its time from, and follows the chain of NTP servers back to their
+master time source.
+If given no arguments, it starts with ``localhost.''
+.PP
+Here is an example of the output from
+.IR ntptrace :
+.RS 2
+.nf
+
+% ntptrace
+localhost: stratum 4, offset 0.0019529, synch distance 0.144135
+server2.bozo.com: stratum 2, offset 0.0124263, synch distance 0.115784
+usndh.edu: stratum 1, offset 0.0019298, synch distance 0.011993, refid 'WWVB'
+
+.fi
+.RE
+On each line, the fields are (left to right): the host name, the
+host's stratum,
+the time offset between that host and the local host
+(as measured by
+.IR ntptrace ;
+this is why it is not always zero for ``localhost''),
+the host's ``synchronization distance,''
+and (only for stratum-1 servers) the reference clock ID.  All times
+are given in seconds.  (Synchronization distance is a measure of the
+goodness of the clock's time.)
+.SH OPTIONS
+.IP "\-d" 5
+Turns on some debugging output.
+.IP "\-n" 5
+Turns off the printing of host names; instead, host IP addresses
+are given.  This may be necessary if a nameserver is down.
+.IP "\-r retries" 5
+Sets the number of retransmission attempts for each host; default = 5.
+.IP "\-t timeout" 5
+Sets the retransmission timeout (in seconds); default = 2.
+.IP "\-v" 5
+Prints verbose information about the NTP servers.
+.SH SEE ALSO
+xntpd(8), xntpdc(8)
+.SH BUGS
+This program makes no attempt to improve accuracy by doing multiple
+samples.
diff --git a/usr.sbin/xntpd/doc/tickadj.8 b/usr.sbin/xntpd/doc/tickadj.8
new file mode 100644
index 0000000..5fce088
--- /dev/null
+++ b/usr.sbin/xntpd/doc/tickadj.8
@@ -0,0 +1,143 @@
+''' $Header
+''' 
+.de Sh
+.br
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp
+.if t .sp .5v
+.if n .sp
+..
+.de Ip
+.br
+.ie \\n.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+'''
+'''     Set up \*(-- to give an unbreakable dash;
+'''     string Tr holds user defined translation string.
+'''     Bell System Logo is used as a dummy character.
+'''
+.tr \(bs-|\(bv\*(Tr
+.ie n \{\
+.ds -- \(bs-
+.if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch
+.if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch
+.ds L" ""
+.ds R" ""
+.ds L' '
+.ds R' '
+'br\}
+.el\{\
+.ds -- \(em\|
+.tr \*(Tr
+.ds L" ``
+.ds R" ''
+.ds L' `
+.ds R' '
+'br\}
+.TH TICKADJ 8 LOCAL
+.SH NAME
+tickadj - fiddle time\-related variables in the kernel
+.SH SYNOPSIS
+.B tickadj
+[
+.B -Aqs
+] [
+.B -a
+.I new_tickadj
+] [
+.B -t
+.I new_tick
+]
+.SH DESCRIPTION
+The
+.I tickadj
+program reads, and optionally modifies, several time\-keeping\-related
+variables in the running kernel, via
+.IR /dev/kmem .
+The particular variables it is concerned with are
+.IR tick ,
+which is the number of microseconds added to the system time during a
+clock interrupt,
+.IR tickadj ,
+which sets the slew rate and resolution used by the
+.IR adjtime (2)
+system call, and
+.IR dosynctodr ,
+which indicates to the kernels on some machines whether they should internally
+adjust the system clock to keep it in line with with time\-of\-day clock
+or not.
+.PP
+By default, with no arguments,
+.I tickadj
+reads the variables of interest in the kernel and prints them.  At the
+same time it determines an \*(L"optimal\*(R" value for the value of the
+.I tickadj
+variable if the intent is to run the
+.IR xntpd (8)
+Network Time Protocol daemon, and prints this as well.  Since the operation
+of
+.I tickadj
+when reading the kernel mimics the operation of similar parts of the
+.IR xntpd (8)
+program fairly closely, this is useful for doing debugging of problems
+with
+.IR xntpd (8).
+.PP
+Various flags may be specified to change the variables of interest in
+the running kernel.  The
+.B -a
+flag allows one to set the the variable
+.I tickadj
+to the value specified as an argument.  The
+.B -A
+flag will also cause
+.I tickadj
+to be modified, but instead will set it to the internally computed
+\*(L"optimal\*(R" value.  The
+.B -t
+flag may be used to reset the kernel's value of
+.IR tick ,
+a capability which is useful on machines with very broken clocks.  The
+.B -s
+flag tells the program to set the value of the variable
+.I dosynctodr
+to zero, a prerequisite for running the
+.IR xntpd (8)
+daemon under SunOS 4.0.  Normally
+.I tickadj
+is quite verbose about what it is doing.  The
+.B -q
+flag tells it to shut up about everything except errors.
+.PP
+Note that
+.I tickadj
+should be run with some caution when being used for the first time on
+different types of machines.  The operations which
+.I tickadj
+trys to perform are not guaranteed to work on all Unix machines.
+.SH FILES
+.nf
+/vmunix
+/unix
+/dev/kmem
+.fi
+.SH SEE ALSO
+xntpd(8)
+.SH HISTORY
+Written by Dennis Ferguson at the University of Toronto
+.SH BUGS
+Fiddling with kernel variables at run time as a part of ordinary
+operations is a hideous practice which is only necessary to make
+up for deficiencies in the implementation of
+.IR adjtime (8)
+in many kernels and/or brokenness of the system clock in some
+vendors' kernels.  It would be much better if the kernels were fixed
+and the
+.I tickadj
+program went away.
diff --git a/usr.sbin/xntpd/doc/xntpd.8 b/usr.sbin/xntpd/doc/xntpd.8
new file mode 100644
index 0000000..b021019
--- /dev/null
+++ b/usr.sbin/xntpd/doc/xntpd.8
@@ -0,0 +1,1352 @@
+''' $Header
+''' 
+.de Sh
+.br
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp
+.if t .sp .5v
+.if n .sp
+..
+.de Ip
+.br
+.ie \\n.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+'''
+'''     Set up \*(-- to give an unbreakable dash;
+'''     string Tr holds user defined translation string.
+'''     Bell System Logo is used as a dummy character.
+'''
+.tr \(bs-|\(bv\*(Tr
+.ie n \{\
+.ds -- \(bs-
+.if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch
+.if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch
+.ds L" ""
+.ds R" ""
+.ds L' '
+.ds R' '
+'br\}
+.el\{\
+.ds -- \(em\|
+.tr \*(Tr
+.ds L" ``
+.ds R" ''
+.ds L' `
+.ds R' '
+'br\}
+.TH XNTPD 8 LOCAL
+.SH NAME
+xntpd - Network Time Protocol daemon
+.SH SYNOPSIS
+.B xntpd
+[
+.B -ab
+] [
+.B -c 
+.I conffile
+] [
+.B -e
+.I authdelay
+] [
+.B -f
+.I driftfile
+] [
+.B -k
+.I keyfile
+] [
+.B -l
+.I loopfile
+] [
+.B -p
+.I pidfile
+] [
+.B -r
+.I broaddelay
+] [
+.B -s
+.I statsdir
+] [
+.B -t
+.I trustedkey
+]
+.SH DESCRIPTION
+.I Xntpd
+is a daemon which maintains a Unix system's time\-of\-day in agreement
+with Internet standard time servers.
+.I Xntpd
+is a complete implementation of the Network Time Protocol (NTP) version
+3 standard as defined by RFC 1305 and also retains
+compatability with version 1 and 2 servers as defined
+by RFC 1059 and RFC 1119, respectively.
+.I Xntpd
+does all computations in fixed point arithmetic and is entirely free of
+floating point code.  The computations done in the protocol and clock
+adjustment code are carried out with high precision and with attention
+to the details which might introduce systematic bias into the integrations,
+to try to maintain an accuracy suitable for synchronizing with even the
+most precise external time source.
+.PP
+Ordinarily,
+.I xntpd
+reads its configuration from a file at startup time.  The default configuration
+file is
+.I /etc/ntp.conf,
+though this may be overridden from the command line.  It is also possible to
+specify a working, though limited,
+.I xntpd
+configuration entirely on the command line, obviating the need for a
+configuration file.  This may be particularly appropriate when xntpd is
+to be configured as a broadcast client, with all peers being determined
+by listening to broadcasts at run time.  Various internal
+.I xntpd
+variables can be displayed, and configuration options altered, while the
+daemon is running through use of the
+.IR ntpq (8)
+and
+.IR xntpdc (8)
+programs.
+.PP
+The following command line arguments are understood by
+.I xntpd
+(see the configuration file description for a more complete functional
+description):
+.Ip -a 8
+run in \*(L"authenticate\*(R" mode
+.Ip -b 8
+listen for broadcast NTP and sync to this if available
+.Ip -c 8
+specify an alternate configuration file
+.Ip -d 8
+specify debugging options
+.Ip -e 8
+specify the time (in seconds) it takes to compute the NTP encryption field
+on this computer
+.Ip -f 8
+specify the location of the drift file
+.Ip -k 8
+specify the location of the file which contains the NTP authentication keys
+.Ip -p 8
+specify the name of the file to record the daemon's process id
+.Ip -r 8
+specify the default round trip delay (in seconds)
+to be used when synchronizing to broadcasts
+.Ip -s 8
+specify a directory to be used for creating statistics files
+.Ip -t 8
+add a key number to the trusted key list
+.SH "CONFIGURATION FILE OPTIONS"
+.IR Xntpd 's
+configuration file is relatively free format.  Comments, which may be
+freely inserted, begin with a \*(L"#\*(R" character
+and extend to the end of the line.  Blank lines are ignored.  Configuration
+statements include an initial keyword followed by white space separated
+arguments, some of which may be optional.  Configuration statements
+may not be continued over multiple lines.  Arguments may be network
+numbers (which must be written in numeric, dotted\-quad form), integers,
+floating point numbers (when specifying times in seconds) and text
+strings.  Optional arguments are delimited by \*(L"[]\*(R" in the following
+descriptions, while alternatives are separated by \*(L"|\*(R".
+.PP
+.B peer
+.I host_address
+[
+.B key
+.I #
+] [
+.B version
+.I #
+] [
+.B prefer
+]
+.br
+.B server
+.I host_address
+[
+.B key
+.I #
+] [
+.B version
+.I #
+] [
+.B prefer
+]
+.br
+.B broadcast
+.I host_address
+[
+.B key
+.I #
+] [
+.B version
+.I #
+] [
+.B prefer
+]
+.PP
+These three statements specify various time servers to be used and/or
+time services to be provided.  The
+.B peer
+statement specifies that the given host is to be polled in
+\*(L"symmetric active\*(R" mode, i.e. that the host is requested to
+provide time which you might synchronize to and, in addition, indicates
+that you are willing to have to remote host synchronize to your time
+if need be.  The
+.B server
+statement specifies that the given host is to be polled in
+\*(L"client\*(R" mode, i.e. that the host is requested to provide
+time which you might synchronize with but that you are unwilling to have
+the remote host synchronize to your own time.  The
+.B broadcast
+statement requests your local daemon to transmit broadcast NTP to
+the specified address.  The latter is usually the broadcast address
+on [one of] your local network[s].
+.PP
+The
+.B key
+option, when included, indicates that all packets sent to the address
+are to include authentication fields encrypted using the specified key
+number (the range of which is that of an unsigned 32 bit integer).  The
+default is to not include an encryption field.  The
+.B version
+option allows one to specify the version number to be used for outgoing
+NTP packets.  Versions 1, 2, and 3 are the choices, version 3 is the default.
+The
+.B prefer
+option marks the host as a preferred host. All other things being equal, this
+host will be chosen for synchronization among a set of correctly operating
+hosts.
+.PP
+.B precision
+.I #
+.PP
+Indicates the precision of local timekeeping.  The value is an integer
+which is approximately the base 2 logarithm of the local timekeeping
+precision in seconds.  By default this value is set to -6.
+.PP
+The precision declared by an implementation can affect several aspects
+of server operation, and can be used as a tuning parameter for your
+synchronization subnet.  It should probably not be changed from the
+default value, however, unless there is a good reason to do so.
+.PP
+.B logfile
+.I filename
+.PP
+Gives the file which is to be used instead of syslog output. This
+configuration option is also a compile time option (SYSLOG_FILE).
+So in order to be able to use this xntpd must be compiled with
+-DSYSLOG_FILE.
+.PP
+.B driftfile
+.I filename
+.PP
+Specifies the name of the file used to record the \*(L"drift\*(R" (or
+frequency error) value
+.I xntpd
+has computed.  If the file exists on startup, it is read and the value
+used to initialize
+.IR xntpd 's
+internal value of the frequency error.  The file is then updated once
+every hour by replacing the old file with a new one containing the
+current value of the frequency error.  Note that the file is updated
+by first writing the current drift value into a temporary file and
+then using
+.IR rename (3)
+to replace the old version.  This implies that
+.I xntpd
+must have write permission for the directory the drift file is located
+in, and that file system links, symbolic or otherwise, should probably
+be avoided.
+.PP
+.B "monitor yes|no"
+.PP
+Indicates whether the
+.I xntpd
+traffic monitoring function should be enabled or not.  When enabled,
+this causes the origin address of each packet received by the server
+to be recorded along with a limited amount of additional information, such
+as the mode of the request and whether it originated from an NTP server port
+or not.  Traffic monitoring data may be inspected using the
+.IR xntpdc (8)
+.I monlist
+command.  The default is \*(L"no\*(R", i.e. traffic monitoring should not
+be done.
+.PP
+Note that the traffic monitoring facility will increase the CPU used
+by
+.IR xntpd ,
+as well as increasing the daemon's memory utilization by as much as
+8.5 kilobytes.  This facility is normally useful for the detection of
+peers with malfunctioning software or which are sending bogus data.  It
+is primarily intended for very popular servers which exchange time with
+large numbers of peers, though it may also be useful for access monitoring
+of local servers if you are willing to accept the overhead.
+.PP
+.B "broadcastclient yes|no"
+.PP
+This indicates whether the local server should listen for, and attempt to
+synchonize to, broadcast NTP.  The default is \*(L"no\*(R".
+.PP
+.B broadcastdelay
+.I seconds
+.PP
+Specifies the default round trip delay to the host whose broadcasts
+are being synchronized to.  The value is specified in seconds and is
+typically (for ethernet) a number between 0.007 and 0.015 seconds.  This
+initial estimate may be improved by polling each server to determine a
+more accurate value.  Defaults to 0.008 seconds.
+.PP
+.B "authenticate yes|no"
+.PP
+Indicates whether the local server should operate in authenticate mode
+or not.  If \*(L"yes\*(R", only peers which include an authentication field
+encrypted with one of our trusted keys (see below) will be considered
+as candidates for synchonizing to.  The default is \*(L"no\*(R".
+.PP
+.B authdelay
+.I seconds
+.PP
+Indicates the amount of time it takes to encrypt an NTP authentication
+field on the local computer.  This value is used to correct transmit
+timestamps when the authentication is used on outgoing packets.  The
+value usually lies somewhere in the range 0.0001 seconds to 0.003 seconds,
+though it is very dependent on the CPU speed of the host computer.  The
+value is usually computed using the
+.I authspeed
+program included with the distribution.
+.PP
+.B keys
+.I filename
+.PP
+Specifies the name of a file which contains the encryption keys which
+are to be used by
+.IR xntpd .
+The format of this file is described below.
+.PP
+.B trustedkey
+.I #
+[
+.I "# ..."
+]
+.PP
+Allows the specification of the encryption key numbers which are trusted
+for the purposes of determining peers suitable for time sychonization,
+when authentication is enabled.  Only peers using one of these keys for
+encryption of the authentication field, and whose authenticity can be
+verified by successful decryption, will be considered as synchonization
+candidates.  The arguments are 32 bit unsigned integers.  Note, however,
+that NTP key 0 is fixed and globally known.  If meaningful authentication
+is to be performed the 0 key should not be trusted.
+.PP
+.B requestkey
+.I #
+.PP
+.I Xntpd
+allows run time reconfiguration to be performed using the
+.IR xntpdc (8)
+program.  Such requests must be authenticated.  The
+.B requestkey
+statement allows the specification of a 32 bit unsigned integer
+key number to be used for authenticating such requests.  Note that
+if no
+.B requestkey
+statement is included in the configuration file the run time reconfiguration
+facility will be disabled.
+.PP
+.B controlkey
+.I #
+.PP
+Certain changes can be made to the
+.I xntpd
+server via mode 6 control messages, in particular the setting of
+leap second indications in a server with a radio clock.  The
+.B controlkey
+statement specifies an encription key number to be used for authenticating
+such messages.  Omitting this statement will cause control messages
+which would change the state of the server to be ignored.
+.PP
+.B restrict
+.I address
+[
+.B mask
+.I numeric_mask
+] [
+.I flag
+] [
+.I ...
+]
+.PP
+.I Xntpd
+implements a general purpose address\-and\-mask based restriction
+list.  The list is sorted by address and by mask, and the list is
+searched in this order for matches, with the last match found defining
+the restriction flags associated with the incoming packets.  The source
+address of incoming packets is used for the match, with the 32 bit address
+being and'ed with the mask associated with the restriction entry and
+then compared with the entry's address (which has also been and'ed with
+the mask) to look for a match.  The \*(L"mask\*(R" argument defaults
+to 255.255.255.255, meaning that the \*(L"address\*(R" is treated as the
+address of an individual host.  A default entry (address 0.0.0.0, mask
+0.0.0.0) is always included and, given the sort algorithm, is always the
+first entry in the list.  Note that, while \*(L"address\*(R" is normally
+given as a dotted\-quad address, the text string \*(L"default\*(R", with
+no mask option, may be used to indicate the default entry.
+.PP
+In the current implementation flags always restrict access, i.e. an entry
+with no flags indicates that free access to the server is to be given.  The
+flags are not orthogonal, in that more restrictive flags will often make
+less restrictive ones redundant.  The flags can generally be classed into
+two catagories, those which restrict time service and those which restrict
+informational queries and attempts to do run time reconfiguration of the
+server.  One or more of the following flags may be specified:
+.Ip ignore 10
+Ignore all packets from hosts which match this entry.  If this flag
+is specified neither queries nor time server polls will be responded
+to.
+.Ip noquery 10
+Ignore all NTP mode 6 and 7 packets (i.e. information queries and configuration
+requests) from the source.  Time service is not affected.
+.Ip nomodify 10
+Ignore all NTP mode 6 and 7 packets which attempt to modify the state of the
+server (i.e. run time reconfiguration).  Queries which return information
+are permitted.
+.Ip notrap 10
+Decline to provide mode 6 control message trap service to matching
+hosts.  The trap service is a subsystem of the mode 6 control message
+protocol which is intended for use by remote event logging programs.
+.Ip lowpriotrap 10
+Declare traps set by matching hosts to be low priority.  The number
+of traps a server can maintain is limited (the current limit is 3).
+Traps are usually assigned on a first come, first served basis, with
+later trap requestors being denied service.  This flag modifies the
+assignment algorithm by allowing low priority traps to be overridden
+by later requests for normal priority traps.
+.Ip noserve 10
+Ignore NTP packets whose mode is other than 6 or 7.  In effect, time service is
+denied, though queries may still be permitted.
+.Ip nopeer 10
+Provide stateless time service to polling hosts, but do not allocate peer
+memory resources to these hosts even if they otherwise might be considered
+useful as future synchronization partners.
+.Ip notrust 10
+Treat these hosts normally in other respects, but never use them as
+synchronization sources.
+.Ip ntpport 10
+This is actually a match algorithm modifier, rather than a restriction
+flag.  Its presence causes the restriction entry to be matched only if
+the source port in the packet is the standard NTP UDP port (123).  Both
+\*(L"ntpport\*(R" and non\-\*(L"ntpport\*(R" may be specified.  The
+\*(L"ntpport\*(R" is considered more specific and is sorted later in the
+list.
+.PP
+Default restriction list entries, with the flags \*(L"ignore, ntpport\*(R",
+for each of the local host's interface addresses are inserted into the
+table at startup to prevent the server from attempting to synchronize to
+its own time.  A default entry is also always present, though if it is
+otherwise unconfigured no flags are associated with the default entry (i.e.
+everything besides your own NTP server is unrestricted).
+.PP
+The restriction facility was added to allow the current access policies
+of the time servers running on the NSFnet backbone to be implemented with
+.I xntpd
+as well.  While this facility may be otherwise useful for keeping unwanted or
+broken remote time servers from affecting your own, it should not be
+considered an alternative to the standard NTP authentication facility.  Source
+address based restrictions are easily circumvented by a determined cracker.
+.PP
+.B trap
+.I host_address
+[
+.B port
+.I port_number
+] [
+.B interface
+.I interface_addess
+]
+.PP
+Configures a trap receiver at the given host address and port number, 
+sending messages with the specified local interface address.  If the
+port number is unspecified a value of 18447 is used.  If the interface
+address is not specified the message is sent with a source address
+which is that of the local interface the message is sent through.  Note
+that on a multihomed host the interface used may vary from time to time
+with routing changes.
+.PP
+The trap receiver will generally log event messages and other information
+from the server in a log file.  While such monitor programs may also
+request their own trap dynamically, configuring a trap receiver will
+ensure that no messages are lost when the server is started.
+.PP
+.B maxskew
+.I seconds
+.PP
+This command is obsolete and not available in this version of
+.I xntpd.
+.PP
+.B select
+.I algorithm_number
+.PP
+This command is obsolete and not available in this version of
+.I xntpd.
+.PP
+.B resolver
+.I /path/xntpres
+.PP
+Normally, names requiring resolution (rather than numeric addresses)
+in the configuration file are resolved by code internal to
+.I xntpd;
+However, in those cases that require it, the code can be installed
+in a standalone program called
+.I xntpres.
+In these cases the full path to the
+.I xntpres
+program is given as the argument the command.
+As
+.I xntpres
+makes use of mode 7 runtime reconfiguration, this facility must also be
+enabled if the procedure is to exceed (see the
+.B requestkey
+and
+.B keys
+statements above).
+.PP
+.B statsdir
+.I /directory path/
+.PP
+Indicates the full path of a directory where statistics files should
+be created (see below). This keyword allows the (otherwise constant) filegen
+filename prefix to be modified for file generation sets used for
+handling statistics logs (see
+.B filegen
+statement below).
+.PP
+.B statistics
+.IR name \.\.\.
+.PP
+Enables writing of statistics records.
+Currently, three kinds of statistics are supported.
+.Ip loopstats 10
+enables recording of loop filter statistics information.
+Each update of the local clock outputs a line of the
+following form to the file generation set named \*(L"loopstats\*(R": 
+.PP
+.RS 5
+48773 10847.650 0.0001307 17.3478 2
+.RE
+
+.RS 10
+The first two fields show the date (Modified Julian Day) and time (seconds
+and fraction past UTC midnight). The next three fields show time offset
+in seconds, frequency offset in parts-per-million and time constant of
+the clock-discipline algorithm at each update of the clock.
+.RE
+.Ip peerstats 10
+enables recording of peer statistics information. This includes
+statistics records of all peers of a NTP server and of the 1-pps signal,
+where present and configured. Each
+valid update appends a line of the following form to the current
+element of a file generation set named \*(L"peerstats\*(R":
+.PP
+.RS 5
+48773 10847.650 127.127.4.1 9714 -0.001605 0.00000 0.00142
+.RE
+
+.RS 10
+The first two fields show the date (Modified Julian Day) and time (seconds
+and fraction past UTC midnight). The next two fields show the peer
+address in dotted-quad notation and status,
+respectively. The status field is encoded in hex in the format described
+in Appendix A of the NTP specification RFC 1305. The final three fields
+show the offset, delay and dispersion, all in seconds.
+.RE
+.Ip clockstats 10
+enables recording of clock driver statistics information. Each update
+received from a clock driver outputs a line of the following form to the
+file generation set named \*(L"clockstats\*(R":
+.PP
+.RS 5
+49213 525.624 127.127.4.1   93 226 00:08:29.606  D
+.RE
+
+.RS 10
+The first two fields show the date (Modified Julian Day) and time (seconds
+and fraction past UTC midnight). The next field shows the clock
+address in dotted-quad notation, The final field shows the last timecode
+received from the clock in decoded ASCII format, where meaningful. In
+some clock drivers a good deal of additional information can be gathered
+and displayed as well. See information specific to each clock
+for further details.
+.RE
+.PP
+Statistic files are managed using file generation sets (see 
+.B filegen
+below). The information obtained by enabling statistics recording
+allows analysis of temporal properties of a
+.I xntpd
+server. It is usually only useful to primary servers or maybe main
+campus servers.
+.PP
+.B filegen
+.I name
+[
+.B file
+.I filename
+] [
+.B type
+.I typename
+] [
+.B flag
+.I flagval
+] [
+.BR link \| nolink
+] [
+.BR enable \| disable
+]
+.PP
+Configures setting of generation file set
+.IR name .
+Generation file sets provide a means for handling files that are
+continously growing during the lifetime of a server. Server statistics
+are a typical example for such files. Generation file sets provide
+access to a set of files used to store the actual data. At any time at
+most one element of the set is being written to. The 
+.I type
+given specifies when and how data will be directed to a new element
+of the set. This way, information stored in elements of a file set
+that are currently unused are available for administrational
+operations
+without the risc of desturbing the operation of
+.IR xntpd .
+(Most important: they can be removed to free space for new data
+produced.)
+Filenames of set members are built from three elements.
+.Ip prefix 10
+This is a constant filename path. It is not subject to modifications
+via the 
+.B filegen
+statement. It is defined by the server, usually specified as a compile
+time constant. It may, however, be configurable for individual file
+generation sets via other commands. For example, the prefix used with
+"loopstats" and  "peerstats" filegens can be configured using the
+.B statsdir 
+statement explained above.
+.Ip filename 10
+This string is directly concatenated to the
+.I prefix
+mentioned above (no intervening \*(L'/\*(R' (slash)). This can be
+modified using the \*(L"file\*(R" argument to the \*(L"filegen\*(R"
+statement. No  \*(L"..\*(R" elements are allowed in this component to
+prevent filenames referring to parts outside the filesystem hierarchy
+denoted by  \*(L"prefix\*(R".
+.Ip suffix 10
+This part is reflects individual elements of a file set. It is generated
+according to the 
+.I type
+of a file set as explained below.
+.PP
+A file generation set is characterized by its type.
+The following types are supported:
+.Ip none 10
+The file set is actually a single plain file.
+.Ip pid 10
+One element of file set is used per incarnation of a
+.I xntpd
+server. This type does not perform any changes to file set members
+during runtime, however it provides an easy way of seperating files
+belonging to different 
+.I xntpd
+server incarnations.
+The set member filename is built by appending a dot (\*(L'.\*(R') to
+concatentated \*(L"prefix\*(R" and \*(L"filename\*(R" strings, and
+appending the decimal representation of the process id of the 
+.I xntpd
+server process.
+.Ip day 10
+One file generation set element is created per day. The term
+.I day
+is based on 
+.IR UTC .
+A day is defined as the period between 00:00 and 24:00 UTC.
+The file set member suffix consists of a dot \*(L".\*(R"
+and a day specification in the form 
+.RI < YYYYMMDD >.
+.I YYYY
+is a 4 digit year number (e.g. 1992).
+.I MM
+is a two digit month number.
+.I DD
+is a two digit day number.
+Thus, all information written at December 10th, 1992 would end up
+in a file named
+\*(L"<prefix><filename>.19921210\*(R".
+.Ip week 10
+Any file set member contains data related to a certain week of a year.
+The term
+.I week
+is definied by computing \*(L"day of year\*(R" modulo 7. Elements of
+such a file generation set are distinguished by appending the
+following suffix to the file set  filename base: 
+A dot, a four digit year number, the letter \*(L"W\*(R",
+and a two digit week number. For example, information from Jamuary,
+10th 1992 would end up in a file with suffix \*(L".1992W1\*(R". 
+.Ip month 10
+One generation file set element is generated per month. The file name
+suffix consists of a dot, a four digit year number, and a two digit
+month.
+.Ip year 10
+One generation file elment is generated per year. The filename suffix
+consists of a dot and a 4 digit year number.
+.Ip age 10
+This type of file generation sets changes to a new element of the file
+set every 24 hours of server operation. The filename suffix consists
+of a dot, the letter \*(L"a\*(R", and an eight digit number. This
+number is taken to be the number of seconds the server is running at
+the start of the corresponding 24 hour period. 
+.PP
+Information is only written to a file generation set when this set is
+\*(L"enabled\*(R". Output is prevented by specifying
+\*(L"disabled\*(R". 
+.PP
+It is convenient to be able to access the 
+.I current
+element of a file generation set by a fixed name. This feature is
+enabled by specifying \*(L"link\*(R" and disabled using
+\*(L"nolink\*(R". If \*(L"link\*(R" is specified, a hard link from the
+current file set element to a file without suffix is created. When
+there is already a file with this name and the number of links of this
+file is one, it is renamed appending a dot, the letter \*(L"C\*(R",
+and the pid of the
+.I xntpd
+server process. When the number of links is greater than one, the file
+is unlinked. This allows the current file to be accessed by a constant
+name. 
+.SH "AUTHENTICATION KEY FILE FORMAT"
+.PP
+The NTP standard specifies an extension allowing
+verification of the authenticity of received NTP packets, and to provide
+an indication of authenticity in outgoing packets.  This is implemented
+in
+.I xntpd
+using the DES encryption algorithm.  The specification
+allows any one of a possible 4 billion keys, numbered with 32 bit unsigned
+integers, to be used to
+authenticate an association.  The servers involved in an association
+must agree on the value of the key used to authenticate their data, though
+they must each learn the key independently.  The keys are standard 56 bit
+DES keys.
+.PP
+Addionally, a new experimental authentication algorithm is available which
+uses an MD5 message digest to compute an authenticator.  Currently the length
+of the key or password is limited to 8 characters, but this will eventually
+be changed to accomodate an effectively unlimited password phrase.
+.I Xntpd
+reads its keys from a file specified using the
+.B -k
+command line option or the
+.B keys
+statement in the configuration file.  While key number 0 is fixed by the
+NTP standard (as 56 zero bits) and may not be changed, one or more of
+the keys numbered 1 through 15 may be arbitrarily set in the keys file.
+.PP
+The key file uses the same comment conventions as the configuration
+file.  Key entries use a fixed format of the form
+.Ip "" 5
+.I "keyno  type  key"
+.PP
+where \*(L"keyno\*(R" is a positive integer,
+\*(L"type\*(R" is a single character which defines the format the key
+is given in, and \*(L"key\*(R" is the key itself.
+.PP
+The key may be given in one of three different formats, controlled by
+the \*(L"type\*(R" character.  The three key types, and corresponding
+formats, are listed following.
+.Ip "S" 5
+The \*(L"key\*(R" is a 64 bit hexadecimal number in the format specified
+in the DES document, that is the high order 7 bits of each octet are used
+to form the 56 bit key while the low order bit of each octet is given a
+value such that odd parity is maintained for the octet.  Leading zeroes
+must be specified (i.e. the key must be exactly 16 hex digits long) and
+odd parity must be maintained.  Hence a zero key, in standard format,
+would be given as
+.I 0101010101010101 .
+.Ip "N" 5
+The \*(L"key\*(R" is a 64 bit hexadecimal number in the format specified
+in the NTP standard.  This is the same as the DES format except the bits
+in each octet have been rotated one bit right so that the parity bit is
+now the high order bit of the octet.  Leading zeroes must be specified
+and odd parity must be maintained.  A zero key in NTP format would be specified
+as
+.I 8080808080808080
+.Ip "A" 5
+The \*(L"key\*(R" is a 1\-to\-8 character ASCII string.  A key is formed
+from this by using the lower order 7 bits of the ASCII representation
+of each character in the string, with zeroes being added on the right
+when necessary to form a full width 56 bit key, in the same way that
+encryption keys are formed from Unix passwords.
+.Ip "M" 5
+The \*(L"key\*(R" is a 1\-to\-8 character ASCII string, using the MD5
+authentication scheme.  Note that both the keys and the authentication
+schemes (DES or MD5) must be identical between a set of peers sharing 
+the same key number.
+.PP
+One of the keys may be chosen,
+by way of the configuration file
+.B requestkey
+statement, to authenticate run time configuration
+requests made using the
+.IR xntpdc (8)
+program.  The latter program obtains the key from the terminal as
+a password, so it is generally appropriate to specify the key chosen
+to be used for this purpose in ASCII format.
+.SH PRIMARY CLOCK SUPPORT
+.PP
+.I Xntpd
+can be optionally compiled to include support for a number of types
+of reference clocks.  A reference clock will generally (though
+not always) be a radio timecode receiver which is synchronized to a
+source of standard time such as the services offered by the NRC in
+Canada and NIST in the U.S.  The interface between the computer and
+the timecode receiver is device dependent and will vary, but is
+often a serial port.
+.PP
+For the purposes of configuration,
+.I xntpd
+treats reference clocks in a manner analogous to normal NTP peers
+as much as possible.  Reference clocks are referred to by address,
+much as a normal peer is, though an invalid IP address is used to
+distinguish them from normal peers.  Reference clock addresses are
+of the form
+.I 127.127.t.u
+where
+.I t
+is an integer denoting the clock type and
+.I u
+indicates the type\-specific unit number.  Reference clocks are normally
+enabled by configuring the clock as a server using a
+.B server
+statement in the configuration file which references the clock's
+address (configuring a reference clock with a
+.B peer
+statement can also be done, though with some clock drivers this may cause
+the clock to be treated somewhat differently and by convention is used
+for debugging purposes).  Clock addresses may generally
+be used anywhere else in the configuration file a normal IP address
+can be used, for example in
+.B restrict
+statements.
+.PP
+There is one additional configuration statement which becomes valid
+when reference clock support has been compiled in.  Its format is:
+.PP
+.B fudge
+.I 127.127.t.u
+[
+.B time1
+.I secs
+] [
+.B time2
+.I secs
+] [
+.B value1
+.I int
+] [
+.B value2
+.I int
+] [
+.B flag1
+.I 0|1
+] [
+.B flag2
+.I 0|1
+]
+.PP
+There are two times (whose values are specified in fixed point seconds),
+two integral values and two binary flags available for customizing
+the operation of a clock.  The interpretation of these values, and
+whether they are used at all, is a function of the needs of the particular
+clock driver.
+.PP
+.I Xntpd
+on Unix machines currently supports several different types of clock hardware
+plus a special pseudo\-clock used for backup or when no other clock
+source is available.  In the case of most of the clock drivers, support
+for a 1-pps precision timing signal is available as described in the
+pps.txt file in the doc directory of the xntp3 distribution. 
+The clock drivers, and the addresses used to configure
+them, are described following:
+.PP
+.B 127.127.1.u
+\- Local synchronization clock driver
+.PP
+This driver doesn't support an actual clock, but rather allows the
+server to synchronize to its own clock, in essence to free run without
+its stratum increasing to infinity.  This can be used to run an
+isolated NTP synchronization network where no standard time source is
+available, by allowing a free running clock to appear as if it has
+external synchronization to other servers.  By running the local clock
+at an elevated stratum it can also be used to prevent a server's stratum
+from rising above a fixed value, this allowing a synchronization subnet
+to synchonize to a single local server for periods when connectivity
+to the primary servers is lost.
+.PP
+The unit number of the clock (the least significant octet in the address)
+must lie in the range 0 through 15 inclusive and is used as the stratum
+the local clock will run at.  Note that the server, when synchronized
+to the local clock, will advertise a stratum one greater than the clock
+peer's stratum.  More than one local clock may be configured (indeed all
+16 units may be active at once), though this hardly seems useful.
+.PP
+The local clock driver uses only the fudge time1 parameter.  This parameter
+provides read and write access to the local clock drift compensation
+register.  This value, which actually provides a fine resolution speed
+adjustment for the local clock, is settable but will remain unchanged
+from any set value
+when the clock is free running without external synchronization.  The
+fudge time1 parameter thus provides a way to manually adjust the speed of the
+clock to maintain reasonable synchronization with, say, a voice
+time announcement.  It is actually more useful to manipulate this value
+with the
+.IR xntpdc (8)
+program.
+.PP
+.B 127.127.3.u
+\- Precision Standard Time/Traconex 1010/1020 WWV/H Receiver
+.PP
+This driver can be used with a PST/Traconex Time Source 1010 or 1020 WWV/WWVH
+Synchronized Clock connected via a serial port.  Up to
+four units, with unit numbers in the range 0 through 3, can be
+configured.  The driver assumes the serial port device name is
+/dev/pst%d (i.e. unit 1, at 127.127.3.1, opens the clock at
+/dev/pst1) and that the clock is configured for 9600-baud operation.
+.PP
+The fudge time1 and time2 parameters are configured directly into the receiver
+as nominal propagation delays when synchronized to WWV and WWVH,
+respectively; the internal DIPswitches ordinarily used for that purpose
+are disabled. The default values are 0.0075 and 0.0265 seconds,
+respectively, which are about right for Toronto.  Values for other
+locations can be calculated using the
+.I propdelay
+program in the util directory of the xntp3 distribution or equivalent
+means described in the user's manual.
+.PP
+The fudge value1 parameter can be used to set the stratum at which
+the peer operates.  The default is 0, which is correct if you want the
+clock to be considered for synchonization whenever it is operating, though
+higher values may be assigned if you only want the clock to provide backup
+service when all other primary sources have failed.  The value2 parameter
+is set to the number of minutes which the daemon will allow the clock to go
+without synchronization before it starts disbelieving it.  The default
+is 20, which is suitable if you have good quality backup NTP peers.  If
+your network is isolated or your network connections are poor it might
+be advantageous to increase this value substantially.
+.PP
+The fudge flag1 can be used to modifiy the averaging algorithm used
+to smooth the clock indications. Ordinarily, the algorithm picks the
+median of a set of samples, which is appropriate under conditions
+of poor to fair radio propagation conditions. If the clock is located
+relatively close to the WWV or WWVH transmitters, setting this flag
+will cause the algorithm to average the set of samples, which can
+reduce the residual jitter and improve accuracy.
+.PP
+The fudge flag2 can be used to force the driver to send to
+the clock the commands required to reprogram the current WWV and WWVH fudge
+delays into it.  This is normally done only when the values are to be changed,
+such as during inital setup and calibration.  Setting
+the (otherwise undocumented) fudge flag3 will cause the driver to reset
+the clock.  The latter two flags are generally useful primarily for debugging.
+.PP
+127.127.4.u
+\- Spectracom 8170 and Netclock/2 WWVB Synchronized Clocks
+.PP
+This driver can be used with a Spectracom 8170 or Netclock/2 WWVB
+Synchronized Clock connected via a serial port.  Up to
+four units, with unit numbers in the range 0 through 3, can be
+configured.  The driver assumes the serial port device name is
+/dev/wwvb%d (i.e., unit 1 at 127.127.4.1 opens the clock at
+/dev/wwvb1) and that the clock is configured for 9600-baud operation.
+.PP
+The fudge time1 parameter can be used to compensate for inherent
+latencies in the serial port hardware and operating system.
+The value, which defaults to zero, is in addition to the value
+programmed by the propagation switches on the receiver. The
+fudge value1 parameter can be used to specify the stratum of the clock
+in the same way described above for the WWV/WWVH clock 127.127.3.u.
+.PP
+.B 127.127.5.u
+\- Kinemetrics/TrueTime Timing Receivers
+.PP
+This driver can be used with at least two models of Kinemetrics/TrueTime
+Timing Receivers, the 468-DC MK III GOES Synchronized Clock and GPS-DC
+MK III GPS Synchronized Clock and very likely others in the same model
+family that use the same timecode formats. The clocks are connected
+via a serial port.  Up to
+four units, with unit numbers in the range 0 through 3, can be
+configured.  The driver assumes the serial port device name is
+/dev/goes%d (i.e., unit 1 at 127.127.5.1 opens the clock at
+/dev/goes1) and that the clock is configured for 9600-baud operation.
+.PP
+The fudge time1 parameter can be used to compensate for inherent
+latencies in the serial port hardware and operating system in the same
+way as described above for the WWVB clock 127.127.4.u.
+The fudge value1 parameter can be used to specify the stratum of the clock
+in the same way described above for the WWV/WWVH clock 127.127.3.u.
+.PP
+.B 127.127.6.0
+\- IRIG-B Audio Decoder
+.PP
+This driver can be used in conjuction with the Inter-Range Instrumentation
+Group standard time-distribution signal IRIG-B. This signal is generated
+by several radio clocks, including those made by Austron, TrueTime, Odetics
+and Spectracom, among others, although it is generally an add-on option.
+The signal is connected via an attenuator box and cable to the audio
+codec input on a Sun SPARCstation and requires a specially modified
+kernel audio driver. Details are in the irig.txt file in the doc
+directory of the xntp3 distribution.  As only a single audio codec
+is built into a workstation, the driver assumes the device name is /dev/irig.
+.PP
+Timing jitter using the decoder and a Sun IPC is in the order of a few 
+microseconds, although the overal timing accuracy is limited by the
+wander of the CPU oscillator used for timing purposes to a few hundred
+microseconds.  These figures are comparable with what can be achieved
+using the 1-pps signal described in the pps.txt file in the doc 
+directory of the xntp3 distribution. 
+.PP
+.B 127.127.7.u
+\- CHU Modem Decoder
+.PP
+This driver can be used with a shortwave receiver and special modem
+circuitry described in the gadget directory of the xntp3 distribution.
+It requires the chu-clk line discipline or chu_clk STREAMS module
+described in the kernel directory of that distribution. It is connected
+via a serial port operating at 300 baud.  Up to
+four units, with unit numbers in the range 0 through 3, can be
+configured.  The driver assumes the serial port device name is
+/dev/chu%d (i.e., unit 1 at 127.127.7.1 opens the clock at
+/dev/chu1).
+.PP
+Unlike the NIST time services, whose timecode requires quite specialized
+hardware to interpret, the CHU timecode can be received directly via
+a serial port after demodulation.  While there are currently no commercial
+CHU receivers, the hardware required to receive the CHU timecode is fairly
+simple to build.  While it is possible to configure several CHU units
+simultaneously this is not recommended as the character interrupts from all
+units will be occuring at the same time and will interfere with each other.
+.PP
+The fudge time1 parameter is used to specify the propagation delay between
+the CHU transmitter at Ottawa, Ontario, and the receiver. The default
+value is 0.0025 seconds, which is about right for Toronto.  Values for other
+locations can be calculated using the
+.I propdelay
+program in the util directory of the xntp3 distribution or equivalent
+means.
+The fudge time2
+parameter is used to compensate for inherent latencies in the modem,
+serial port hardware and operating system in the same way as described
+above for the WWVB clock 127.127.4.u. The default value is
+0.0002 seconds, which is about right for typical telephone modem chips.
+The fudge value1 parameter can be used to specify the stratum of the clock
+in the same way described above for the WWV/WWVH clock 127.127.3.u.
+The fudge flag1 can be used to modify the averaging algorithm in the
+same way as described for that clock.
+.PP
+.B 127.127.8.u
+\- Synchronisation to several receivers (DCF77, GPS)
+.PP
+The timecode of
+the receivers will be sampled via a STREAMS module in the kernel (The STREAMS module
+has been designed for use with SUN Systems under SunOS 4.1.x. It can be
+linked directly into the kernel or loaded via the loadable driver mechanism)
+This STREAMS module can be adepted to be able to convert different time code
+formats.
+If the daemon is compiled without the STREAM definition synchronisation
+will work without the Sun streams module, though accuracy is significantly
+degraded.
+.br
+The actual receiver status is mapped into various synchronisation
+states generally used by receivers. The STREAMS module is configured to
+interpret the time codes of DCF U/A 31, PZF535, GPS166, Trimble SV6 GPS, ELV DCF7000,
+Schmid and low cost receivers (see list below).
+.br
+The reference clock support in xntp contains the necessary configuration tables
+for those receivers. In addition to supporting up to 32 different clock types and
+4 devices the generation a a PPS signal is also provided as an configuration
+option. The PPS configuration option uses the receiver generated time stamps
+for feeding the PPS loopfilter control for much finer clock synchronisation.
+.br
+CAUTION: The PPS configuration option is different from the hardware PPS signal,
+which is also supported (see below), as it controls the way xntpd is synchronised
+to the reference clock, while the hardware PPS signal controls the way time
+offsets are determined.
+.br
+The use of the PPS option requires receivers with an accuracy of better than 1ms.
+.PP
+Fudge factors
+.PP
+Only two fudge factors are utilized. The
+.I time1
+fudge factor defines the phase offset of the sychnronisation character to the actual
+time.
+On the availability of PPS information the
+.I time2
+fudge factor show the difference betwteen the PPS time stamp and the reception
+time stamp of the serial signal. This parameter is read only attempts to
+set this parameter will be ignored.
+The
+.I flag0
+enables input filtering. This a median filter with continuous sampling. The
+.I flag1
+selects averaging of the samples remaining after the filtering. Leap second
+handling is controlled with the
+.I flag2.
+When set a leap second will be deleted on receipt of a leap second indication
+from the receiver. Otherwise the leap second will be added (which is the default).
+.PP
+.I ntpq
+timecode variable
+.PP
+The timecode variable in the ntpq read clock variable command contains several
+fields. The first field is the local time in Unix format. The second field is
+the offset to UTC (format HHMM). The currently active receiver flags are listed
+next. Additional feature flags of the receiver are optionally listed in paranthesis.
+The actual time code is enclosed in angle brackets < >. A qualification of the
+decoded time code format is following the time code. The last piece of information
+is the overall running time and the accumulated times for the clock event states.
+.PP
+Unit encoding
+.PP
+The unit field <u> encodes the device, clock type and the PPS generation option.
+There are 4 possible devices which are encoded in the lower 2 bits of the <u>
+field. The devices are named
+.IR /dev/refclock-0
+through
+.IR /dev/refclock-3 .
+Bits 2 thru 6 encode the clock type. The fudge factors
+of the clock type are take from a table
+.I clockinfo
+in refclock_parse.c. The generation of PPS information for disciplining the
+local NTP clock is encoded in bit 7 of <u>.
+.PP
+Currently nine clock types (devices /dev/refclock-0 - /dev/refclock-3) are supported.
+.Ip 127.127.8.0-3 16
+Meinberg PZF535 receiver (FM demodulation/TCXO / 50us)
+.Ip 127.127.8.4-7 16
+Meinberg PZF535 receiver (FM demodulation/OCXO / 50us)
+.Ip 127.127.8.8-11 16
+Meinberg DCF U/A 31 receiver (AM demodulation / 4ms)
+.Ip 127.127.8.12-15 16
+ELV DCF7000 (sloppy AM demodulation / 50ms)
+.Ip 127.127.8.16-19 16
+Walter Schmid DCF receiver Kit (AM demodulation / 1ms)
+.Ip 127.127.8.20-23 16
+RAW DCF77 100/200ms pulses (Conrad DCF77 receiver module / 5ms)
+.Ip 127.127.8.24-27 16
+RAW DCF77 100/200ms pulses (TimeBrick DCF77 receiver module / 5ms)
+.Ip 127.127.8.28-31 16
+Meinberg GPS166 receiver (GPS / <<1us)
+.Ip 127.127.8.32-35 16
+Trimble SV6 GPS receiver (GPS / <<1us)
+.PP
+The reference clock support carefully monitors the state transitions of
+the receiver. All state changes and exceptional events such as loss of time code
+transmission are logged via the
+.I syslog
+facility.
+Every hour a summary of the accumulated times for the clock states is
+listed via syslog.
+.PP
+PPS support is only available when the receiver is completely
+synchronised. The receiver is believed to deliver correct time for an additional
+period of time after losing sychronisation unless a disruption in time code
+transmission is detected (possible power loss). The trust period is dependent
+on the receiver oscillator and thus a function of clock type. This is one of
+the parameters in the
+.I clockinfo
+field of the reference clock implementation. This parameter cannot be
+configured by xntpdc.
+.PP
+In addition to the PPS loopfilter control a true PPS hardware signal can be applied
+on Sun Sparc stations via the CPU serial ports on the CD pin. This signal is
+automatically detected and will be used for offset calculation. The input signal
+must be the time mark for the following time code. (The edge sensitivity can be
+selected - look into the appropriate kernel/parsestreams.c for details).
+Meinberg receivers can be connected by feeding the PPS pulse of the receiver via
+a 1488 level converter to Pin 8 (CD) of a Sun serial zs\-port.
+.PP
+There exists a special firmware release for the PZF535 Meinberg receivers.
+This release (PZFUERL 4.6 (or higher - The UERL is important)) is absolutely
+recommended for XNTP use, as it provides LEAP warning, time code time zone information
+and alternate antenna indication. Please check with Meinberg for this
+firmware release.
+For the Meinberg GPS166 receiver is also a special firmaware release available
+(Uni-Erlangen). This release must be used for proper operation.
+.PP
+The raw DCF77 pulses can be fed via a level converter directly into Pin 3 (Rx)
+of the Sun. The telegrams will be decoded an used for synchronisation.
+AM DCF77 receivers are running as low as $25. The accuracy is dependent on
+the receiver and is somewhere between 2ms (expensive) to 10ms (cheap).
+Upon bad signal reception of DCF77 sychronisation will cease as no backup
+oscillator is available as usually found in other reference clock receivers.
+So it is important to have a good place for the DCF77 antenna. For transmitter
+shutdowns you are out of luck unless you have other NTP servers with alternate
+time sources available.
+.PP
+127.127.9.u
+\- Magnavox MX4200 Navigation Receiver used as GPS Synchronized Clocks
+.PP
+This driver can be used with a Magnavox MX4200 Navigation Receiver
+adapted to precision timing applications. This requires an interface
+box described in the ppsclock directory of the xntp3 distribution.
+It is connected via a serial port and requires the ppsclock STREAMS
+module described in the same directory.  Up to
+four units, with unit numbers in the range 0 through 3, can be
+configured.  The driver assumes the serial port device name is
+/dev/gps%d (i.e., unit 1 at 127.127.9.1 opens the clock at
+/dev/gps1) and that the clock is configured for 9600-baud operation.
+.PP
+The fudge time1 parameter can be used to compensate for inherent
+latencies in the serial port hardware and operating system in the
+same way described above for the WWVB clock 127.127.4.u.  The
+fudge value1 parameter can be used to specify the stratum of the clock
+in the same way described above for the WWV/WWVH clock 127.127.3.u.
+.PP
+127.127.10.u
+\- Austron 2200A/2201A GPS/LORAN Synchronized Clock and Timing Receiver
+.PP
+This driver can be used with an Austron 2200A/2201A GPS/LORAN Synchronized
+Clock and Timing Receiver connected via a serial port.  It supports
+several special features of the clock, including the Input Burffer Module,
+Output Buffer Module, IRIG-B Interface Module and LORAN Assist Module. It
+requires the RS232 Serial Interface module for communication with
+the driver. Up to four units (which hardly seems affordable), with unit
+numbers in the range 0 through 3, can be
+configured.  The driver assumes the serial port device name is
+/dev/gps%d (i.e., unit 1 at 127.127.10.1 opens the clock at
+/dev/gps1) and that the clock is configured for 9600-baud operation.
+.PP
+The fudge time1 parameter can be used to compensate for inherent
+latencies in the serial port hardware and operating system in the
+same way described above for the WWVB clock 127.127.4.u.  The
+fudge value1 parameter can be used to specify the stratum of the clock
+in the same way described above for the WWV/WWVH clock 127.127.3.u.
+.PP
+This receiver is capable of a comprehensive and large volume of
+statistics and operational data. The specific data-collection
+commands and attributes are embedded in the driver source code;
+however, the collection process can be enabled or disabled
+using the flag4 flag. If set, collection is enabled; if not,
+which is the default, it is disabled. A comprehensive suite of data reduction
+and summary scripts is in the ./scripts/stats directory of the xntp
+distribution.
+.PP
+127.127.11.u
+\- Kinemetrics/TrueTime OMEGA-DC OMEGA Synchronized Clock
+.PP
+This driver can be used with a Kinemetrics/TrueTime OMEGA-DC OMEGA
+Synchronized Clock connected via a serial port.  This clock is
+sufficiently different than other Kinemetrics/TrueTime models
+to require a separate driver. Up to
+four units, with unit numbers in the range 0 through 3, can be
+configured.  The driver assumes the serial port device name is
+/dev/omega%d (i.e., unit 1 at 127.127.11.1 opens the clock at
+/dev/omega1) and that the clock is configured for 9600-baud operation.
+.PP
+The fudge time1 parameter can be used to compensate for inherent
+latencies in the serial port hardware and operating system in the
+same way described above for the WWVB clock 127.127.4.u.  The
+fudge value1 parameter can be used to specify the stratum of the clock
+in the same way described above for the WWV/WWVH clock 127.127.3.u.
+.PP
+127.127.12.0
+\- KSI/Odeteics TPRO IRIG-B Decoder
+.PP
+This driver can be used with a KSI/Odeteics TPRO or TPRO-SAT IRIG-B
+Decoder, which is a module connected directly to the SBus of a
+Sun workstation.  The module works with the IRIG-B signal generated
+by several radio clocks, including those made by Austron, TrueTime, Odetics
+and Spectracom, among others, although it is generally an add-on option.
+In the case of the TPRO-SAT, the module is an integral part of a GPS
+receiver, which serves as the primary timing source. 
+As only a single module of this type can be
+used on a single workstation, only the unit number 0 is acceptable.
+The driver assumes the device name is /dev/tpro0.
+.PP
+The fudge time1 parameter can be used to compensate for inherent
+latencies in the serial port hardware and operating system in the
+same way described above for the WWVB clock 127.127.4.u.  The
+fudge value1 parameter can be used to specify the stratum of the clock
+in the same way described above for the WWV/WWVH clock 127.127.3.u.
+.PP
+127.127.13.u
+\- Leitch CSD 500 Controller with HP 5061A Atomic Clock
+.PP
+This driver can be used with a Leitch CSD 500 Controller
+connected to an HP 5061A Atomic Clock or equivalent primary timing source
+and connected via a serial port.  Up to
+four units, with unit numbers in the range 0 through 3, can be
+configured.  The driver assumes the serial port device name is
+/dev/leitch%d (i.e., unit 1 at 127.127.13.1 opens the clock at
+/dev/leitch1) and that the clock is configured for 300-baud operation.
+.PP
+The fudge time1 parameter can be used to compensate for inherent
+latencies in the serial port hardware and operating system in the
+same way described above for the WWVB clock 127.127.4.u.  The
+fudge value1 parameter can be used to specify the stratum of the clock
+in the same way described above for the WWV/WWVH clock 127.127.3.u.
+.PP
+127.127.14.u
+\- EES M201 MSF receiver
+.PP
+This driver can be used with an EES M201 MSF receiver connected
+to a Sun running SunOS 4.x with the "ppsclock" STREAMS module.
+.PP
+The fudge time1 and time2 parameters can be used to compensate for
+inherent latencies in the serial port hardware and operating system
+respectively in the same way described above for the WWVB clock 127.127.4.u.
+The bottom 4 bits of fudge value1 parameter can be used to specify
+the stratum of the clock in the same way described above for the
+WWV/WWVH clock 127.127.3.u.
+The fudge value2 parameter can be used to specify the debug mask.
+bit 0x1 causes logging of smoothing processing.
+bit 0x4 causes the clock buffer to be dumped.
+If flag1 is set, then the system clock is assumed to be sloppy
+(e.g. Sun4 with 20ms clock), so samples are averaged.
+If flag2 is set, then leaphold is set.
+If flag3 is set, then the sample information is dumped.
+If flag4 is set, then the input data is smoothed, and all data
+points are used.
+.SH FILES
+.Ip /etc/ntp.conf 20
+the default name of the configuration file
+.Ip /etc/ntp.drift 20
+the conventional name of the drift file
+.Ip /etc/ntp.keys 20
+the conventional name of the key file
+.SH SEE ALSO
+.PP
+.IR xntpdc (8),
+.IR ntpq (8),
+.IR ntpdate (8)
+.SH HISTORY
+.PP
+Written by Dennis Ferguson at the University of Toronto.
+Text amended by David Mills at the University of Delaware.
+.SH BUGS
+.PP
+.I Xntpd
+has gotten rather fat.  While not huge, it has gotten larger
+than might be desireable for an elevated\-priority daemon running on a
+workstation, particularly since many of the fancy features which
+consume the space were designed more with a busy primary server, rather
+than a high stratum workstation, in mind.  This will eventually be corrected
+either by adopting the
+.I ntpd
+daemon as an alternative when it becomes able to match
+.IR xntpd 's
+performance, or if not than by producing a stripped down version of
+.I xntpd
+specifically for workstation use.
diff --git a/usr.sbin/xntpd/doc/xntpdc.8 b/usr.sbin/xntpd/doc/xntpdc.8
new file mode 100644
index 0000000..20209b5
--- /dev/null
+++ b/usr.sbin/xntpd/doc/xntpdc.8
@@ -0,0 +1,659 @@
+''' $Header
+''' 
+.de Sh
+.br
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp
+.if t .sp .5v
+.if n .sp
+..
+.de Ip
+.br
+.ie \\n.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+'''
+'''     Set up \*(-- to give an unbreakable dash;
+'''     string Tr holds user defined translation string.
+'''     Bell System Logo is used as a dummy character.
+'''
+.tr \(bs-|\(bv\*(Tr
+.ie n \{\
+.ds -- \(bs-
+.if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch
+.if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch
+.ds L" ""
+.ds R" ""
+.ds L' '
+.ds R' '
+'br\}
+.el\{\
+.ds -- \(em\|
+.tr \*(Tr
+.ds L" ``
+.ds R" ''
+.ds L' `
+.ds R' '
+'br\}
+.TH XNTPDC 8 LOCAL
+.SH NAME
+xntpdc - query/control program for the Network Time Protocol daemon
+.SH SYNOPSIS
+.B xntpdc
+[
+.B -ilnps
+] [
+.B -c 
+.I command
+] [
+.I host
+] [
+.I ...
+]
+.SH DESCRIPTION
+.I Xntpdc
+is used to query the
+.IR xntpd (8)
+daemon about its current state and to request changes in that state.  The
+program may be run either in interactive mode or controlled using
+command line arguments.  Extensive state and statistics information is
+available through the
+.I xntpdc
+interface.  In addition, nearly all the configuration options which can
+be specified at start up using
+.IR xntpd 's
+configuration file may also be specified at run time using
+.IR xntpdc .
+.PP
+If one or more request options is included on the command line when
+.I xntpdc
+is executed, each of the requests will be sent to the NTP servers running
+on each of the hosts given as command line arguments, or on
+.I localhost
+by default.  If no request options are given,
+.I xntpdc
+will attempt to read commands from the standard input and execute these
+on the NTP server running on the first host given on the command line, again
+defaulting to
+.I localhost
+when no other host is specified.
+.I Xntpdc
+will prompt for commands if the standard input is a terminal device.
+.PP
+.I Xntpdc
+uses NTP mode 7 packets to communicate with the NTP server, and hence
+can be used to query any compatable server on the network which permits
+it.  Note that since NTP is a UDP protocol this communication will be
+somewhat unreliable, especially over large distances in terms of network
+topology.
+.I Xntpdc
+makes no attempt to retransmit requests, and will time requests out if
+the remote host is not heard from within a suitable time out time.
+.PP
+Command line options are described following.  Specifying a command
+line option other than
+.B -i
+or
+.B -n
+will cause the specified query (queries) to be sent to the indicated
+host(s) immediately.  Otherwise,
+.I xntpdc
+will attempt to read interactive format commands from the standard input.
+.Ip -c 8
+The following argument is interpreted as an interactive format command
+and is added to the list of commands to be executed on the specified
+host(s).  Multiple
+.B -c
+options may be given.
+.Ip -i 8
+Force
+.I xntpdc
+to operate in interactive mode.  Prompts will be written to the
+standard output and commands read from the standard input.
+.Ip -l 8
+Obtain a list of peers which are known to the server(s).  This switch
+is equivalent to \*(L"-c listpeers\*(R".
+.Ip -n 8
+Output all host addresses in dotted\-quad numeric format rather than
+converting to the canonical host names.
+.Ip -p 8
+Print a list of the peers known to the server as well as a summary
+of their state.  This is equivalent to \*(L"-c peers\*(R".
+.Ip -s 8
+Print a list of the peers known to the server as well as a summary
+of their state, but in a slightly different format than the
+.B -p
+switch.  This is equivalent to \*(L"-c dmpeers\*(R".
+.SH INTERNAL COMMANDS
+.PP
+Interactive format commands consist of a keyword followed by zero
+to four arguments.  Only enough characters of the full keyword to
+uniquely identify the command need be typed.  The output of a command
+is normally sent to the standard output, but optionally the output of
+individual commands may be sent to a file by appending a \*(L">\*(R",
+followed by a file name, to the command line.
+.PP
+A number of interactive format commands are executed entirely within the
+.I xntpdc
+program itself and do not result in NTP mode 7 requests being sent
+to a server.  These are described following.
+.PP
+.B ?
+[
+.I command_keyword
+}
+.PP
+A \*(L"?\*(R" by itself will print a list of all the command keywords
+known to this incarnation of
+.IR xntpdc .
+A \*(L"?\*(R" followed by a command keyword will print funcation and
+usage information about the command.  This command is probably a better
+source of information about
+.I xntpdc
+than this manual page.
+.PP
+.B help
+[
+.I command_keyword
+]
+.PP
+A synonym for the
+.B ?
+command.
+.PP
+.B timeout
+.I millseconds
+.PP
+Specify a time out period for responses to server queries.  The default
+is about 8000 milliseconds.
+.PP
+.B delay
+.I milliseconds
+.PP
+Specify a time interval to be added to timestamps included in requests
+which require authentication.  This is used to enable (unreliable) server
+reconfiguration over long delay network paths or between machines whose
+clocks are unsynchronized.
+.PP
+.B host
+.I hostname
+.PP
+Set the host to which future queries will be sent.
+.I Hostname
+may be either a host name or a numeric
+address.
+.PP
+.B poll
+[
+.I #
+] [
+.B verbose
+]
+.PP
+Poll the current server in client mode.  The first argument is the
+number of times to poll (default is 1) while the second argument may
+be given to obtain a more detailed output of the results.  This command
+is currently just wishful thinking.
+.PP
+.B keyid
+.I #
+.PP
+This command allows the specification of a key number to be used to
+authenticate configuration requests.  This must correspond to the
+key number the server has been configured to use for this purpose.
+.PP
+.B passwd
+.PP
+This command prompts you to type in a password (which will not be
+echoed) which will be used to authenticate configuration requests.  The
+password must correspond to the key configured for use by the NTP
+server for this purpose if such requests are to be successful.
+.PP
+.B "hostnames yes|no"
+.PP
+If \*(L"yes\*(R" is specified, host names are printed in information
+displays.  If \*(L"no\*(R" is given, numeric addresses are printed
+instead.  The default is \*(L"yes\*(R" unless modified using the command
+line
+.B -n
+switch.
+.PP
+.B quit
+.PP
+Exit
+.IR xntpdc .
+.SH QUERY COMMANDS
+.PP
+Query commands result in NTP mode 7 packets containing requests for
+information being sent to the server.  These are \*(L"read\-only\*(R"
+commands in that they make no modification of the server configuration
+state.
+.PP
+.B listpeers
+.PP
+Obtains and prints a brief list of the peers for which the
+server is maintaining state.  These should include all configured
+peer associations as well as those peers whose stratum is such that
+they are considered by the server to be possible future synchonization
+candidates.
+.PP
+.B peers
+.PP
+Obtains a list of peers for which the server is maintaining state, along
+with a summary of that state.  Summary information includes the address
+of the remote peer, the local interface address (0.0.0.0 if a local address
+has yet to be determined), the stratum of the remote peer (a stratum of
+16 indicates the remote peer is unsynchronized), the polling interval,
+in seconds, the reachability
+register, in octal, and the current estimated delay, offset and dispersion
+of the peer, all in seconds.  In addition, the character in the left
+margin indicates the mode this peer entry is operating in.  A
+\*(L"+\*(R" denotes symmetric active, a \*(L"-\*(R" indicates symmetric
+passive, a \*(L"=\*(R" means the remote server is being polled in
+client mode, a \*(L"^\*(R" indicates that the server is broadcasting
+to this address, a \*(L"~\*(R" denotes that the remote peer is sending
+broadcasts and a \*(L"*\*(R" marks the peer the server is currently
+synchonizing to.
+.PP
+The contents of the host field may be one of four forms. It may be a host name,
+an IP address, a reference clock implementation name with its parameter or
+\*(L"REFCLK(<implementation number>, <parameter>)\*(R". On \*(L"hostnames no\*(R"
+only IP\-addresses will be displayed.
+.PP
+.B dmpeers
+.PP
+A slightly different peer summary list.  Identical to the output of the
+.B peers
+command except for the character in the leftmost column.  Characters
+only appear beside peers which were included in the final stage of
+the clock selection algorithm.  A \*(L".\*(R" indicates that this
+peer was cast off in the falseticker detection, while a \*(L"+\*(R"
+indicates that the peer made it through.  A \*(L"*\*(R" denotes the
+peer the server is currently synchronizing with.
+.PP
+.B showpeer
+.I peer_address
+[
+.I addr2
+] [
+.I addr3
+] [
+.I addr4
+]
+.PP
+Shows a detailed display of the current peer variables for one or more
+peers.  Most of these values are described in the NTP Version 2
+specification.
+.PP
+.B pstats
+.I peer_address
+[
+.I addr2
+] [
+.I addr3
+] [
+.I addr4
+]
+.PP
+Show per\-peer statistic counters associated with the specified peer(s).
+.PP
+.B loopinfo
+[
+.B oneline|multiline
+]
+.PP
+Print the values of selected loop filter variables.  The loop filter is
+the part of NTP which deals with adjusting the local system clock.  The
+\*(L"offset\*(R" is the last offset given to the loop filter by the
+packet processing code.  The \*(L"frequency\*(R" is actually the
+frequency error, or drift, of your system's clock in the units NTP
+uses for internal computations.  Dividing this number by 4096 should
+give you the actual drift rate.  The \*(L"compliance\*(R" is actually
+a long term average offset and is used by NTP to control the gain of
+the loop filter.  The \*(L"timer\*(R" value is the number of seconds
+which have elapsed since a new sample offset was given to the loop
+filter.  The \*(L"oneline\*(R" and \*(L"multiline\*(R" options specify
+the format in which this information is to be printed.  \*(L"multiline\*(R"
+is the default.
+.PP
+.B sysinfo
+.PP
+Print a variety of system state variables, i.e. state related to the
+local server.  Many of these values are described in the NTP Version 2
+specification, RFC 1119.
+.PP
+.B sysstats
+.PP
+Print a number of stat counters maintained in the protocol module.
+.PP
+.B memstats
+.PP
+Print a number of counters related to the peer memory allocation
+code.
+.PP
+.B iostats
+.PP
+Print counters maintained in the input\-output module.
+.PP
+.B timerstats
+.PP
+Print counters maintained in the timer/event queue support code.
+.PP
+.B reslist
+.PP
+Obtain and print the server's restriction list.  This list is (usually)
+printed in sorted order and may help to understand how the restrictions
+are applied.
+.PP
+.B monlist
+.PP
+Obtain and print traffic counts collected and maintained by the
+monitor facility.
+.PP
+.B clockinfo
+.I clock_peer_address
+[
+.I addr2
+] [
+.I addr3
+] [
+.I addr4
+]
+.PP
+Obtain and print information concerning a peer clock.  The values
+obtained provide information on the setting of fudge factors and
+other clock performance information.
+.PP
+.B clkbug
+.I clock_peer_address
+[
+.I addr2
+] [
+.I addr3
+] [
+.I addr4
+]
+.PP
+Obtain debugging information for a clock peer.  This information is
+provided only by some clock drivers and is mostly undecodable without
+a copy of the driver source in hand.
+.SH RUNTIME CONFIGURATION REQUESTS
+.PP
+All requests which cause state changes in the server are authenticated
+by the server using a configured NTP key (the facility can also be
+disabled by
+the server by not configuring a key).  The key number and the corresponding
+key must also be made known to
+.IR xtnpdc .
+This can be done using the
+.B keyid
+and
+.B passwd
+commands, the latter of which will prompt at the
+terminal for a password to use
+as the encryption key.  You will also be prompted automatically for
+both the key number and password the
+first time a command which would result in an authenticated request
+to the server is given.  Authentication not only provides verification
+that the requester has permission to make such changes, but also gives
+an extra degree of protection again transmission errors.
+.PP
+Authenticated requests always include a timestamp in the packet data, which
+is included in the computation of the authentication code.  This timestamp
+is compared by the server to its receive time stamp.  If they differ
+by more than a small amount the request is rejected.  This is done for
+two reasons.  First, it makes simple replay attacks on the server, by someone
+who might be able to overhear traffic on your LAN, much more difficult.
+Second, it makes it more difficult to request configuration changes
+to your server from topologically remote hosts.  While the reconfiguration
+facility will work well with a server on the local host, and may work
+adequately between time\-synchronized hosts on the same LAN, it will
+work very poorly for more distant hosts.  As such, if reasonable passwords
+are chosen, care is taken in the distribution and protection of keys and
+appropriate source address restrictions are applied, the
+run time reconfiguration facility should provide an adequate level of
+security.
+.PP
+The following commands all make authenticated requests.
+.PP
+.B addpeer
+.I peer_address
+[
+.I keyid
+] [
+.I version#
+] [
+.B minpoll|prefer
+]
+.PP
+Add a configured, symmetric active peer association with a peer at the
+given address.  If the optional \*(L"keyid\*(R" is a nonzero integer
+all outgoing packets to the remote server will
+have an authentication field attached encrypted with this key.  If the
+value is 0 (or not given) no authentication will be done.  The
+\*(L"version#\*(R" can be 1 or 2, and defaults to 2.  If \*(L"minpoll\*(R"
+is specified the polling interval for the association will remain
+clamped at the minimum.  The latter option is only useful for testing.
+Note that an existing association with the same peer may be deleted
+when this command is executed, or may simply be converted to conform to
+the new configuration, as appropriate. The prefer keyword indicates
+a preferred peer (and thus will be used primarily for clock synchronisation
+if possible). The preferred peer also determines the validity of the PPS
+signal - if the preferred peer is suitable for synchronisation so is the
+PPS signal.
+.PP
+.B addserver
+.I peer_address
+[
+.I keyid
+] [
+.I version#
+] [
+.B minpoll|prefer
+]
+.PP
+Identical to the
+.B addpeer
+command except that polling is done in client mode rather than
+symmetric active mode.
+.PP
+.B broadcast
+.I peer_address
+[
+.I keyid
+] [
+.I version#
+] [
+.B minpoll
+]
+.PP
+Identical to the
+.B addpeer
+command except that packets are instead sent in broadcast mode.  The
+\*(L"peer_address\*(R" parameter will generally be a broadcast address
+on one of your local networks.
+.PP
+.B unconfig
+.I peer_address
+[
+.I addr2
+] [
+.I addr3
+] [
+.I addr4
+]
+.PP
+This command causes the configured bit to be removed from the specified
+peer(s).  In many cases this will cause the peer association to be
+deleted.  When appropriate, however, the association may persist in
+an unconfigured mode if the remote peer is willing to continue on in
+this fashion.
+.PP
+.B set bclient|auth
+[
+.I ...
+]
+.PP
+Allows the setting of the broadcast client and/or authenticate system
+flags.  Setting the former causes the server to listen for broadcast
+NTP to to synchronize to broadcasts when appropriate.  Setting the
+latter flag causes the server to only synchronize with peers which
+include an authentication field encrypted with one of the local server's
+trusted keys.
+.PP
+.B clear bclient|auth
+[
+.I ...
+]
+.PP
+Allows the broadcast client and/or authenticate system flags to be
+cleared.  Clearing the former causes incoming broadcast NTP packets
+to be ignored.  Clearing the latter allows peers which have not included
+an authentication field, or which have included one but have encrypted
+it with an untrusted key, to be considered synchronization candidates.
+.PP
+.B restrict
+.I address
+.I mask
+.I flag
+[
+.I flag
+]
+.PP
+Causes flag(s) to be added to an existing restrict list entry, or adds
+a new entry to the list with the specified flag(s).  The possible choices
+for the flags arguments are given in the following list:
+.Ip ignore 10
+Ignore all packets from hosts which match this entry.  If this flag
+is specified neither queries nor time server polls will be responded
+to.
+.Ip noquery 10
+Ignore all NTP mode 7 packets (i.e. information queries and configuration
+requests) from the source.  Time service is not affected.
+.Ip nomodify 10
+Ignore all NTP mode 7 packets which attempt to modify the state of the
+server (i.e. run time reconfiguration).  Queries which return information
+are permitted.
+.Ip noserve 10
+Ignore NTP packets whose mode is other than 7.  In effect, time service is
+denied, though queries may still be permitted.
+.Ip nopeer 10
+Provide stateless time service to polling hosts, but do not allocate peer
+memory resources to these hosts even if they otherwise might be considered
+useful as future synchronization partners.
+.Ip notrust 10
+Treat these hosts normally in other respects, but never use them as
+synchronization sources.
+.Ip ntpport 10
+This is actually a match algorithm modifier, rather than a restriction
+flag.  Its presence causes the restriction entry to be matched only if
+the source port in the packet is the standard NTP UDP port (123).  Both
+\*(L"ntpport\*(R" and non\-\*(L"ntpport\*(R" may be specified.  The
+\*(L"ntpport\*(R" is considered more specific and is sorted later in the
+list.
+.PP
+.B unrestrict
+.I address
+.I mask
+.I flag
+[
+.I flag
+]
+.PP
+Remove the specified flag(s) from the restrict list entry indicated
+by the
+.I address
+and
+.I mask
+arguments.
+.PP
+.B delrestrict
+.I address
+.I mask
+[
+.B ntpport
+]
+.PP
+Delete the matching entry from the restrict list.
+.PP
+.B "monitor yes|no"
+.PP
+Enable or disable the monitoring facility.  Note that a
+.B "monitor no"
+command followed by a
+.B "monitor yes"
+command is a good way of resetting the packet counts.
+.PP
+.B readkeys
+.PP
+Causes the current set of authentication keys to be purged and a
+new set to be obtained by rereading the keys file (which must have
+been specified in the
+.I xntpd
+configuration file).  This allows encryption keys to be changed without
+restarting the server.
+.PP
+.B trustkey
+.I keyid
+[
+.I keyid
+] [
+.I keyid
+] [
+.I keyid
+]
+.PP
+Adds one or more keys to the trusted key list.  When authentication
+is enabled, peers whose time is to be trusted must be authenticated using
+a trusted key.
+.PP
+.B untrustkey
+.I keyid
+[
+.I keyid
+] [
+.I keyid
+] [
+.I keyid
+]
+.PP
+Removes one or more keys from the trusted key list.
+.PP
+.B authinfo
+.PP
+Returns information concerning the authentication module, including
+known keys and counts of encryptions and decryptions which have been
+done.
+.PP
+.B setprecision
+.I precision_value
+.PP
+Sets the precision which the server advertises to the specified value.  This
+should be a negative integer in the range -4 through -20.
+.PP
+.B setselect
+.I algorithm_number
+.PP
+Sets the selection weight algorithm to that indicated by the specified number.
+This should be an integer value between 1 and 5 inclusive.  Algorithm 1
+is that specified in RFC 1119, the other 4 algorithms are experimental
+and should be used with caution.
+.SH SEE ALSO
+.PP
+.IR xntpd (8)
+.SH HISTORY
+.PP
+Written by Dennis Ferguson at the University of Toronto.
+.SH BUGS
+.PP
+.I Xntpdc
+is a crude hack.  Much of the information it shows is deadly boring
+and could only be loved by its implementer.  The program was designed
+so that new (and temporary) features were easy to hack in, at great
+expense to the program's ease of use.  Despite this, the program
+is occasionally useful.