diff options
| author | roberto <roberto@FreeBSD.org> | 1999-12-22 15:24:45 +0000 |
|---|---|---|
| committer | roberto <roberto@FreeBSD.org> | 1999-12-22 15:24:45 +0000 |
| commit | 07fa87617ade0f00e9d60fa4b1079cac165d6059 (patch) | |
| tree | daf1c2e9a599e9dfc97305d8b5252e8630bea9b9 /usr.sbin/xntpd/doc | |
| parent | 5960602b89278a9a46eb40f3716de826681c1072 (diff) | |
| download | FreeBSD-src-07fa87617ade0f00e9d60fa4b1079cac165d6059.zip FreeBSD-src-07fa87617ade0f00e9d60fa4b1079cac165d6059.tar.gz | |
Bye bye xntpd.
Diffstat (limited to 'usr.sbin/xntpd/doc')
| -rw-r--r-- | usr.sbin/xntpd/doc/README.irig | 306 | ||||
| -rw-r--r-- | usr.sbin/xntpd/doc/README.kern | 1374 | ||||
| -rw-r--r-- | usr.sbin/xntpd/doc/README.magic | 346 | ||||
| -rw-r--r-- | usr.sbin/xntpd/doc/README.refclock | 1421 | ||||
| -rw-r--r-- | usr.sbin/xntpd/doc/UofT | 146 | ||||
| -rw-r--r-- | usr.sbin/xntpd/doc/acts.c | 878 | ||||
| -rw-r--r-- | usr.sbin/xntpd/doc/notes.txt | 1258 | ||||
| -rw-r--r-- | usr.sbin/xntpd/doc/ntpdate.8 | 147 | ||||
| -rw-r--r-- | usr.sbin/xntpd/doc/ntpq.8 | 480 | ||||
| -rw-r--r-- | usr.sbin/xntpd/doc/ntptrace.8 | 65 | ||||
| -rw-r--r-- | usr.sbin/xntpd/doc/tickadj.8 | 124 | ||||
| -rw-r--r-- | usr.sbin/xntpd/doc/xntpd.8 | 1075 | ||||
| -rw-r--r-- | usr.sbin/xntpd/doc/xntpdc.8 | 674 |
13 files changed, 0 insertions, 8294 deletions
diff --git a/usr.sbin/xntpd/doc/README.irig b/usr.sbin/xntpd/doc/README.irig deleted file mode 100644 index f293f4c..0000000 --- a/usr.sbin/xntpd/doc/README.irig +++ /dev/null @@ -1,306 +0,0 @@ - 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 deleted file mode 100644 index aac26fa..0000000 --- a/usr.sbin/xntpd/doc/README.kern +++ /dev/null @@ -1,1374 +0,0 @@ - A Kernel Model for Precision Timekeeping - - Revised 3 April 1994 - -Note: This memorandum is a substantial revision of RFC-1589, "A Kernel -Model for Precision Timekeeping," March, 1994. It includes several -changes to the daemon and user interfaces, as well as a new feature -which disciplines the CPU clock oscillator in both time and frequency to -a source of precision time signals. This memorandum is included in the -distributions for the SunOS, Ultrix and OSF/1 kernels and in the NTP -Version 3 distribution (xntp3.v.tar.Z) as the file README.kern, where v -is the version identifier. 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 identifier should be 3q -or later. - -Overview - -This memorandum describes an engineering model which implements a -precision time-of-day function for a generic operating system. The model -is based on the principles of disciplined oscillators and phase-lock -loops (PLL) and frequency-lock loops (FLL) often found in the -engineering literature. It has been implemented in the Unix kernels for -several workstations, including those made by Sun Microsystems and -Digital Equipment. The model changes the way the system clock is -adjusted in time and frequency, as well as provides mechanisms to -discipline its frequency to an external precision timing source. The -model incorporates a generic system-call interface for use with the -Network Time Protocol (NTP) or similar time synchronization protocol. -The NTP Version 3 daemon xntpd operates with this model to provide -synchronization limited in principle only by the accuracy and stability -of the external timing source. - -This memorandum does not obsolete or update any RFC. It does not propose -a standard protocol, specification or algorithm. It is intended to -provoke comment, refinement and implementations for kernels not -considered herein. While a working knowledge of NTP is not required for -an understanding of the design principles or implementation of the -model, it may be helpful in understanding how the model behaves in a -fully functional timekeeping system. The architecture and design of NTP -is described in [MIL91], while the current NTP Version 3 protocol -specification is given in RFC-1305 [MIL92a] and a subset of the -protocol, the Simple Network Time Protocol (SNTP), is given in RFC-1361 -[MIL92c]. - -The model has been implemented in the Unix kernels for three Sun -Microsystems and Digital Equipment workstations. In addition, for the -Digital machines the model provides improved precision to one -microsecond (us). Since these specific implementations involve -modifications to licensed code, they cannot be provided directly. -Inquiries should be directed to the manufacturer's representatives. -However, the engineering model for these implementations, including a -simulator with code segments almost identical to the implementations, -but not involving licensed code, is available via anonymous FTP from -host louie.udel.edu in the directory pub/ntp and compressed tar archive -kernel.tar.Z. The NTP Version 3 distribution can be obtained via -anonymous ftp from the same host and directory in the compressed tar -archive xntp3.3q.tar.Z, where the version number shown as 3.3q may be -adjusted for new versions as they occur. - -1. Introduction - -This memorandum describes a model and programming interface for generic -operating system software that manages the system clock and timer -functions. The model provides improved accuracy and stability for most -computers using the Network Time Protocol (NTP) or similar time -synchronization protocol. This memorandum describes the design -principles and implementations of the model, while related technical -reports discuss the design approach, engineering analysis and -performance evaluation of the model as implemented in Unix kernels for -modern workstations. The NTP Version 3 daemon xntpd operates with these -implementations to provide improved accuracy and stability, together -with diminished overhead in the operating system and network. In -addition, the model supports the use of external timing sources, such as -precision pulse-per-second (PPS) signals and the industry standard IRIG -timing signals. The NTP daemon automatically detects the presence of the -new features and utilizes them when available. - -There are three prototype implementations of the model presented in this -memorandum, one each for the Sun Microsystems SPARCstation with the -SunOS 4.1.x kernel, Digital Equipment DECstation 5000 with the Ultrix -4.x kernel and Digital Equipment 3000 AXP Alpha with the OSF/1 V1.x -kernel. In addition, for the DECstation 5000/240 and 3000 AXP Alpha -machines, a special feature provides improved precision to 1 us (stock -Sun kernels already do provide this precision). Other than improving the -system clock accuracy, stability and precision, these implementations do -not change the operation of existing Unix system calls which manage the -system clock, such as gettimeofday(), settimeofday() and adjtime(); -however, if the new features are in use, the operations of -gettimeofday() and adjtime() can be controlled instead by new system -calls ntp_gettime() and ntp_adjtime() as described below. - -A detailed description of the variables and algorithms that operate upon -them 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 specific README files included -in the kernel distributions. - -In this memorandum, NTP Version 3 and the Unix implementation xntp3 are -used as an example application of the new system calls for use by a -synchronization daemon. In principle, these system calls can be used by -other protocols and 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 -[LEV89], the ability to precisely adjust the system clock frequency -simplifies the synchronization procedures and allows the telephone call -frequency to be considerably reduced. - -2. Design Approach - -While not strictly necessary for an understanding or implementation of -the model, it may be helpful to briefly describe how NTP operates to -control the system clock in a client computer. As described in [MIL91], -the NTP protocol exchanges timestamps with one or more peers sharing a -synchronization subnet to calculate the time offsets between peer clocks -and the local clock. These offsets are processed by several algorithms -which refine and combine the offsets to produce an ensemble average, -which is then used to adjust the local clock time and frequency. The -manner in which the local clock is adjusted represents the main topic of -this memorandum. The goal in the enterprise is the most accurate and -stable system clock possible with the available computer hardware and -kernel software. - -In order to understand how the new model works, it is useful to review -how most Unix kernels maintain the system clock. In the Unix design a -hardware counter 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 timer interval (reciprocal of the rate) does -not evenly divide one second in microseconds, the kernel adds 64 us once -each second, so the timescale consists of 255 advances of 3906 us plus -one of 3970 us. Similarly, the OSF/1 kernel adds 576 us once each -second, so its timescale consists of 1023 advances of 976 us plus one of -1552 us. - -2.1. Mechanisms to Adjust Time and Frequency - -In most Unix kernels it is possible to slew the system clock to a new -offset relative to the current time by using the 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 timer interrupts. 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 larger. This results in a roundoff error which -can accumulate to an unacceptable degree, so that special provisions -must be made in the clock adjustment procedures of the synchronization -daemon. - -In order to implement a frequency discipline function, it is necessary -to provide time offset adjustments to the kernel at regular adjustment -intervals using the adjtime() system call. In order to reduce the system -clock jitter to the regime consistent with the model, it is necessary -that the adjustment interval be relatively small, in the neighborhood of -1 s. However, the Unix adjtime() implementation requires each offset -adjustment to complete before another one can be begun, which means that -large adjustments must be amortized over possibly many adjustment -intervals. The requirement to implement the adjustment interval and -compensate for roundoff error considerably complicates the synchronizing -daemon implementation. - -In the new model this scheme is replaced by another that represents the -system clock as a multiple-word, precision-time variable in order to -provide very precise clock adjustments. At each timer interrupt a -precisely calibrated quantity is added to the kernel time variable and -overflows propagated as required. The quantity is computed as in the NTP -local clock model described in [MIL92b], which operates as an adaptive- -parameter, first-order, type-II phase-lock loop (PLL). In principle, -this PLL design can provide precision control of the system clock -oscillator within 1 us and frequency to within parts in 10^11. While -precisions of this order are surely well beyond the capabilities of the -CPU clock oscillator used in typical workstations, they are appropriate -using precision external oscillators, as described below. - -The PLL design is identical to the one originally implemented in NTP and -described in [MIL92b]. In the original design the software daemon -simulates the PLL using the adjtime() system call; however, the daemon -implementation is considerably complicated by the considerations -described above. The modified kernel routines implement the PLL in the -kernel using precision time and frequency representations, so that these -complications are avoided. A new system call ntp_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 frequency -compensation in the kernel means that the system clock runs true even if -the daemon were to cease operation or the network paths to the primary -synchronization source fail. - -In the new model the new ntp_adjtime() operates in a way similar to the -original adjtime() system call, but does so independently of adjtime(), -which continues to operate in its traditional fashion. When used with -NTP, it is the design intent that settimeofday() or adjtime() be used -only for system clock adjustments greater than +-128 ms, although the -dynamic range of the new model is much larger at +-512 ms. It has been -the Internet experience that the need to change the system clock in -increments greater than +-128 ms is extremely rare and is usually -associated with a hardware or software malfunction or system reboot. - -The easiest way to set the time is with the settimeofday() system call; -however, this can under some conditions cause the clock to jump -backwards. If this cannot be tolerated, adjtime() can be used to slew -the clock to the new value without running backward or affecting the -frequency discipline process. Once the system clock has been set within -+-128 ms, 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 and time constant depend -on the measured delay and dispersion; however, the scheme is quite -forgiving and neither moderate loss of updates nor variations in the -update interval are serious. - -2.2 Daemon and Application Interface - -Unix application programs can 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 the primary synchronization source. However, in the new model -the PLL adjusts the system clock to compensate for its intrinsic -frequency error, so that the time error expected in normal operation -will usually be much less than the maximum error. The programming -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 programming interface also includes a -new system call ntp_adjtime(), which can be used to read and write -kernel variables for time and frequency adjustment, PLL time constant, -leap-second warning and related data. - -In addition, the kernel adjusts the indicated maximum error to grow by -an amount equal to the maximum oscillator frequency tolerance times the -elapsed time since the last update. The default engineering parameters -have been optimized for update intervals in the order of 64 s. As shown -in [MIL93], this is near the optimum interval for NTP used with ordinary -room-temperature quartz oscillators. For other intervals the PLL time -constant can be adjusted to optimize the dynamic response over intervals -of 16-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 using typical modern workstations. - -While any synchronization 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 system file -and provides it and the initial time constant via ntp_adjtime(). In -subsequent calls to ntp_adjtime(), only the time offset 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 a -system 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 oscillator can be avoided. - -2.3. Precision Clocks for DECstation 5000/240 and 3000 AXP Alpha - -The stock microtime() routine in the Ultrix kernel for Digital Equipment -MIPS-based workstations returns system time to the precision of the -timer interrupt interval, which is in the 1-4 ms range. However, in the -DECstation 5000/240 and possibly other machines of that family, there is -an undocumented IOASIC hardware register that counts system bus cycles -at a rate of 25 MHz. The new microtime() routine for the Ultrix kernel -uses this register to interpolate system time between timer interrupts. -This results in a precision of 1 us for all time values obtained via the -gettimeofday() and ntp_gettime() system calls. For the Digital Equipment -3000 AXP Alpha, the architecture provides a hardware Process Cycle -Counter and a machine instruction (rpcc) to read it. This counter -operates at the fundamental frequency of the CPU clock or some -submultiple of it, 133.333 MHz for the 3000/400 for example. The new -microtime() routine for the OSF/1 kernel uses this counter in the same -fashion as the Ultrix routine. Support for this feature is conditionally -compiled in the kernel only if the MICRO option is used in the kernel -configuration file. - -In both the Ultrix and OSF/1 kernels the gettimeofday() and -ntp_gettime() system call use the new microtime() routine, which returns -the interpolated value to 1-us resolution, but does not change the -kernel time variable. Therefore, other 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. - -The SunOS kernel already includes a system clock with 1-us resolution; -so, in principle, no microtime() routine is necessary. An existing -kernel routine uniqtime() implements this function, but it is coded in -the C language and is rather slow at 42-85 us per call on a SPARCstation -IPC. A replacement microtime() routine coded in assembler language is -available in the NTP Version 3 distribution and is much faster at about -3 us per call. Note that, as explained later, this routine should be -called at an interrupt priority level not greater than that of the timer -interrupt routine. Otherwise, it is possible to miss a tick increment, -with result the time returned can be late by one tick. This is always -true in the case of gettimeofday() and ntp_gettime(), but might not be -true in other cases, such as when using the PPS signal described later -in this memorandum. - -2.4. External Time and Frequency Discipline - -The overall accuracy of a time synchronization subnet with respect to -Coordinated Universal Time (UTC) depends on the accuracy and stability -of the primary synchronization source, usually a radio or satellite -receiver, and the CPU clock oscillator of the primary server. As -discussed in [MIL93], the traditional interface using a ASCII serial -timecode and RS232 port precludes the full accuracy of most radio -clocks. In addition, the poor frequency stability of typical CPU clock -oscillators limits the accuracy, whether or not precision time sources -are available. There are, however, several ways in which the system -clock accuracy and stability can be improved to the degree limited only -by the accuracy and stability of the synchronization source and the -jitter of the interface and operating system. - -Many radio clocks produce special signals that can be used by external -equipment to precisely synchronize time and frequency. Most produce a -pulse-per-second (PPS) signal that can be read via a modem-control lead -of a serial port and some produce a special IRIG signal that can be read -directly by a bus peripheral, such as the KSI/Odetics TPRO IRIG SBus -interface, or indirectly via the audio codec of some workstations, as -described in [MIL93]. In the NTP Version 3 daemon xntpd, the PPS signal -can be used to augment the less precise ASCII serial timecode to improve -accuracy to the order of a few tens of microseconds. Support is also -included in the NTP distribution for the TPRO interface, as well as the -audio codec; however, the latter requires a modified kernel audio driver -contained in the compressed tar archive bsd_audio.tar.Z in the same host -and directory as the NTP Version 3 distribution mentioned previously. -2.4.1. PPS Signal - -The most convenient way to interface a PPS signal to a computer is -usually with a serial port and RS232-compatible signal; however, the PPS -signal produced by most radio clocks and laboratory instruments is -usually a TTL pulse signal. Therefore, some kind of level -converter/pulse generator is necessary to adapt the PPS signal to a -serial port. An example design, including schematic and printed-circuit -board artwork, is in the compressed tar archive gadget.tar.Z in the same -host and directory as the NTP Version 3 distribution mentioned -previously. There are several ways the PPS signal can be used in -conjunction with the NTP Version 3 daemon xntpd, as described in [MIL93] -and in the documentation included in the distribution. - -The NTP Version 3 distribution includes a special ppsclock module for -the SunOS 4.1.x kernel that captures the PPS signal presented via a -modem-control lead of a serial port. Normally, the ppsclock module -produces a timestamp at each transition of the PPS signal and provides -it to the synchronization daemon for integration with the serial ASCII -timecode, also produced by the radio clock. With the conventional PLL -implementation in either the daemon or the kernel as described in -[MIL93], the accuracy of this scheme is limited by the intrinsic -stability of the CPU clock oscillator to a millisecond or two, depending -on environmental temperature variations. - -The ppsclock module has been modified to in addition call a new kernel -routine hardpps() once each second. In addition, the Ultrix 4.3 kernel -has been modified to provide a similar functionality. The hardpps() -routine compares the timestamp with a sample of the CPU clock oscillator -in order to discipline the oscillator to the time and frequency of the -PPS signal. Using this method, the time accuracy is improved to -typically 20 us or less and frequency stability a few parts in 10^8, -which is about two orders of magnitude better than the undisciplined -oscillator. The new feature is conditionally compiled in the code -described below only if the PPS_SYNC option is used in the kernel -configuration file. - -When using the PPS signal to adjust the time, there is a problem with -some kernels which is very difficult to fix. The serial port interrupt -routine often operates at an interrupt priority level above the timer -interrupt routine. Thus, as explained below, it is possible that a tick -increment can be missed and the time returned late by one tick. It may -happen that, if the CPU clock oscillator frequency is close to the PPS -oscillator frequency (less than a few ppm), this condition can persist -for two or more successive PPS interrupts. A useful workaround in the -code is to use a glitch detector and median filter to process the PPS -sample offsets. The glitch detector suppresses offset bursts greater -than half the tick interval and which last less than 30 successive PPS -interrupts. The median filter ranks the offsets in a moving window of -three samples and uses the median as the output and the difference -between the other two as a dispersion measure. - -2.4.2. External Clocks - -It is possible to replace the system clock function with an external bus -peripheral. The TPRO device mentioned previously can be used to provide -IRIG-synchronized time with a precision of 1 us. A driver for this -device tprotime.c and header file tpro.h are included in the -kernel.tar.Z distribution mentioned previously. Using this device, the -system clock is read directly from the interface; however, the device -does not record the year, so special provisions have been made to obtain -the year from the kernel time variable and initialize the driver -accordingly. Support for this feature is conditionally compiled in the -kernel only if the EXT_CLOCK and TPRO options are used in the kernel -configuration file. - -While the system clock function is provided directly by the microtime() -routine in the driver, the kernel time variable must be disciplined as -well, since not all system timing functions use the microtime() routine. -This is done by measuring the time difference between the microtime() -clock and kernel time variable and using it to adjust the kernel PLL as -if the adjustment were provided by an external peer and NTP. - -A good deal of error checking is done in the TPRO driver, since the -system clock is vulnerable to a misbehaving radio clock, IRIG signal -source, interface cables and TPRO device itself. Unfortunately, there is -no practical way to utilize the extensive diversity and redundancy -capabilities available in the NTP synchronization daemon. In order to -avoid disruptions that might occur if the TPRO time is far different -from the kernel time variable, the latter is used instead of the former -if the difference between the two exceeds 1000 s; presumably in that -case operator intervention is required. - -2.4.2. External Oscillators - -Even if a source of PPS or IRIG signals is not available, it is still -possible to improve the stability of the system clock through the use of -a specialized bus peripheral. In order to explore the benefits of such -an approach, a special SBus peripheral called HIGHBALL has been -constructed. The device includes a pair of 32-bit hardware counters in -Unix timeval format, together with a precision, oven-controlled quartz -oscillator with a stability of a few parts in 10^9. A driver for this -device hightime.c and header file high.h are included in the -kernel.tar.Z distribution mentioned previously. Support for this feature -is conditionally compiled in the kernel only if the EXT_CLOCK and -HIGHBALL options are used in the kernel configuration file. - -Unlike the external clock case, where the system clock function is -provided directly by the microtime() routine in the driver, the HIGHBALL -counter offsets with respect to UTC must be provided first. This is done -using the ordinary kernel PLL, but controlling the counter offsets -directly, rather than the kernel time variable. At first, this might -seem to defeat the purpose of the design, since the jitter and wander of -the synchronization source will affect the counter offsets and thus the -accuracy of the time. However, the jitter is much reduced by the PLL and -the wander is small, especially if using a radio clock or another -primary server disciplined in the same way. In practice, the scheme -works to reduce the incidental wander to a few parts in 10^8, or about -the same as using the PPS signal. - -As in the previous case, the kernel time variable must be disciplined as -well, since not all system timing functions use the microtime() routine. -However, the kernel PLL cannot be used for this, since it is already in -use providing offsets for the HIGHBALL counters. Therefore, a special -correction is calculated from the difference between the microtime() -clock and the kernel time variable and used to adjust the kernel time -variable at the next timer interrupt. This somewhat roundabout approach -is necessary in order that the adjustment does not cause the kernel time -variable to jump backwards and possibly lose or duplicate a timer event. - -2.5 Other Features - -It is a design feature of the NTP architecture that the system clocks in -a synchronization subnet are to read the same or nearly the same values -before during and after a leap-second event, as declared by national -standards bodies. The new model is designed to implement the leap event -upon command by an ntp_adjtime() argument. The intricate and sometimes -arcane details of the model and implementation are discussed in [MIL92b] -and [MIL93]. Further details are given in the technical summary later in -this memorandum. -3. Technical Summary - -In order to more fully understand the workings of the model, a stand- -alone simulator kern.c and header file timex.h are included in the -kernel.tar.Z distribution mentioned previously. In addition, an example -kernel module kern_ntptime.c which implements the ntp_gettime() and -ntp_adjtime() system calls is included. Neither of these programs -incorporate licensed code. Since the distribution is somewhat large, due -to copious comments and ornamentation, it is impractical to include a -listing of these programs in this memorandum. In any case, implementors -may choose to snip portions of the simulator for use in new kernel -designs; but, due to formatting conventions, this would be difficult if -included in this memorandum. - -The kern.c program 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 main() routine in the program. The -algorithms include code fragments almost identical to those in the -machine-specific kernel implementations 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 fragments -themselves are not derived from any licensed code. The following -discussion assumes that the simulator code is available for inspection. - -3.1. PLL Simulation - -The simulator operates in conformance with the analytical model -described in [MIL92b]. The main() program operates as a driver for the -fragments hardupdate(), hardclock(), second_overflow(), hardpps() and -microtime(), although not all functions implemented in these fragments -are simulated. The program simulates the PLL at each timer interrupt and -prints a summary of critical program variables at each time update. - -There are three defined options in the kernel configuration file -specific to each implementation. The PPS_SYNC option provides support -for a pulse-per-second (PPS) signal, which is used to discipline the -frequency of the CPU clock oscillator. The EXT_CLOCK option provides -support for an external kernel-readable clock, such as the KSI/Odetics -TPRO IRIG interface or HIGHBALL precision oscillator, both for the SBus. -The TPRO option provides support for the former, while the HIGHBALL -option provides support for the latter. External clocks are implemented -as the microtime() clock driver, with the specific source code selected -by the kernel configuration file. - -The PPS signal is carefully monitored for error conditions which can -affect accuracy, stability and reliability. The time_status kernel -variable contains bits that both control the use of the PPS signal and -reveal its operational status. The function of each bit is described in -a later section of this memo. - -3.1.1. The hardupdate() Fragment - -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 -divided by the time constant, but clamped to a maximum (for robustness). -Then, the time since the last update is computed and clamped to a -maximum and to zero if initializing. The offset is multiplied (sorry -about the ugly multiply) by the result and divided by the square of the -time constant and then added to the frequency variable. Note that all -shifts are assumed to be positive and that a shift of a signed quantity -to the right requires a little dance. - -The STA_PLL and STA_PPSTIME status bits, which are set by the -ntp_adjtime() system call, serve to enable or inhibit the kernel PLL and -PPS time-discipline functions. The STA_PPSSIGNAL status bit is set by -the hardpps() code fragment when the PPS signal is present and operating -within nominal bounds. Time discipline from the PPS signal operates only -if both the STA_PPSTIME and STA_PPSSIGNAL bits are set; otherwise, the -discipline operates from the offset given in the ntp_adjtime() system -call. In the intended mode of operation, the synchronization daemon sets -STA_PLL to enable the PLL when first initialized, then sets STA_PPSTIME -when reliable synchronization to within +-128 ms has been achieved with -either a radio clock or external peer. The daemon can detect and -indicate this condition for monitoring purposes by noting that both -STA_PPSTIME and STA_PPSSIGNAL are set. - -With the defines given in the program and header files, the maximum time -offset is determined by the size in bits of the long type (32 or 64) -less the SHIFT_UPDATE scale factor (12) or at least 20 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 SHIFT_UPDATE bits. -This results in a time adjustment range over +-512 ms. Since -time_constant must be greater than or equal to zero, the maximum -frequency offset is determined by the SHIFT_USEC scale factor (16) or at -least 16 bits (signed). This results in a frequency adjustment range -over +-31,500 ppm. - -In the addition step, the value of offset * mtemp is not greater than -MAXPHASE * MAXSEC = 31 bits (signed), which will not overflow a long add -on a 32-bit machine. There could be a loss of precision due to the right -shift of up to 12 bits, since time_constant is bounded at 6. This -results in a net worst-case frequency resolution of about .063 ppm, -which is not significant for most quartz oscillators. The worst case -could be realized only if the NTP peer misbehaves according to the -protocol specification. - -The time_offset value is clamped upon 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 stabilized, -as well as to satisfy the correctness assertions if the time -synchronization protocol or implementation misbehaves. - -3.1.2. The hardclock() Fragment - -The hardclock() fragment is inserted in the hardware timer interrupt -routine at the point the system clock is to be incremented by the value -of tick. Previous to this fragment the time_update variable has been -initialized to the tick increment plus the value computed by the -adjtime() system call in the stock Unix kernel, normally plus/minus the -tickadj value, which is usually in the order of 5 us. The time_phase -variable, which represents the instantaneous phase of the system clock, -is advanced by time_adj, which is calculated in the second_overflow() -fragment described below. If the value of time_phase exceeds 1 us in -scaled units, time_update is increased by the (signed) excess and -time_phase retains the residue. - -In those cases where a PPS signal is connected by a serial port -operating at an interrupt priority level greater than the timer -interrupt, special consideration should be given the location of the -hardclock() fragment in the timer interrupt routine. The system clock -should be advanced as early in the routine as possible, preferably -before the hardware timer interrupt flag is cleared. This reduces or -eliminates the possibility that the microtime() routine may latch the -time after the flag is cleared, but before the system clock is advanced, -which results in a returned time late by one tick. - -Except in the case of an external oscillator such as the HIGHBALL -interface, the hardclock() fragment advances the system clock by the -value of tick plus time_update. However, in the case of an external -oscillator, the system clock is obtained directly from the interface and -time_update used to discipline that interface instead. However, the -system clock must still be disciplined as explained previously, so the -value of clock_cpu computed by the second_overflow() fragment is used -instead. - -3.1.3. The second_overflow() Fragment - -The second_overflow() fragment is inserted at the point where the -microseconds field of the system time variable is being checked for -overflow. Upon overflow the maximum error time_maxerror is increased by -time_tolerance to reflect the maximum time offset due to oscillator -frequency error. Then, the increment time_adj to advance the kernel time -variable is calculated from the (scaled) time_offset and time_freq -variables updated at the last call to the hardclock() fragment. - -The phase adjustment is calculated as a (signed) fraction of the -time_offset remaining, where the fraction is added to time_adj, then -subtracted from time_offset. This technique provides a rapid convergence -when offsets are high, together with good resolution when offsets are -low. The frequency adjustment is the sum of the (scaled) time_freq -variable, an adjustment necessary when the tick interval does not evenly -divide one second fixtick and PPS frequency adjustment pps_freq (if -configured). - -The scheme of approximating exact multiply/divide operations with shifts -produces good results, except when an exact calculation is required, -such as when the PPS signal is being used to discipline the CPU clock -oscillator frequency as described below. As long as the actual -oscillator frequency is a power of two in Hz, no correction is required. -However, in the SunOS kernel the clock frequency is 100 Hz, which -results in an error factor of 0.78. In this case the code increases -time_adj by a factor of 1.25, which results in an overall error less -than three percent. - -On rollover of the day, the leap-second state machine described below -determines whether a second is to be inserted or deleted in the -timescale. The microtime() routine insures that the reported time is -always monotonically increasing. - -3.1.4. The hardpps() Fragment - -The hardpps() fragment is operative only if the PPS_SYNC option is -specified in the kernel configuration file. It is called from the serial -port driver or equivalent interface at the on-time transition of the PPS -signal. The code operates as a first-order, type-I, frequency-lock loop -(FLL) controlled by the difference between the frequency represented by -the pps_freq variable and the frequency of the hardware clock -oscillator. It also provides offsets to the hardupdate() fragment in -order to discipline the system clock time. - -In order to avoid calling the microtime() routine more than once for -each PPS transition, the interface requires the calling program to -capture the system time and hardware counter contents at the on-time -transition of the PPS signal and provide a pointer to the timestamp -(Unix timeval) and counter contents as arguments to the hardpps() call. -The hardware counter contents are determined by saving the microseconds -field of the system time, calling the microtime() routine, and -subtracting the saved value. If a microseconds overflow has occurred -during the process, the resulting microseconds value will be negative, -in which case the caller adds 1000000 to normalize the microseconds -field. - -In order to avoid large jitter when the PPS interrupt occurs during the -timer interrupt routine before the system clock is advanced, a glitch -detector is used. The detector latches when an offset exceeds a -threshold tick/2 and stays latched until either a subsequent offset is -less than the threshold or a specified interval MAXGLITCH (30 s) has -elapsed. As long as the detector remains latched, it outputs the offset -immediately preceding the latch, rather than the one received. - -A three-stage median filter is used to suppress jitter less than the -glitch threshold. The median sample drives the PLL, while the difference -between the other two samples represents the time dispersion. Time -dispersion samples are averaged and used as a jitter estimate. If this -estimate exceeds a threshold MAXTIME/2 (100 us), an error bit -STA_PPSJITTER is raised in the status word. - -The frequency of the hardware oscillator is determined from the -difference in hardware counter readings at the beginning and end of the -calibration interval divided by the duration of the interval. However, -the oscillator frequency tolerance, as much as 100 ppm, may cause the -difference to exceed the tick value, creating an ambiguity. In order to -avoid this ambiguity, the hardware counter value at the beginning of the -interval is increased by the current pps_freq value once each second, -but computed modulo the tick value. At the end of the interval, the -difference between this value and the value computed from the hardware -counter is the control signal for the FLL. - -Control signal samples which exceed the frequency tolerance MAXFREQ (100 -ppm) are discarded, as well as samples resulting from excessive interval -duration jitter. In these cases an error bit STA_PPSERROR is raised in -the status word. Surviving samples are then processed by a three-stage -median filter. The median sample drives the FLL, while the difference -between the other two samples represents the frequency dispersion. -Frequency dispersion samples are averaged and used as a stabiity -estimate. If this estimate is below a threshold MAXFREQ/4 (25 ppm), the -median sample is used to correct the oscillator frequency pps_freq with -a weight expressed as a shift PPS_AVG (2). - -Initially, an approximate value for the oscillator frequency is not -known, so the duration of the calibration interval must be kept small to -avoid overflowing the tick. The time difference at the end of the -calibration interval is measured. If greater than tick/4, the interval -is reduced by half. If less than this fraction for four successive -calibration intervals, the interval is doubled. This design -automatically adapts to nominal jitter in the PPS signal, as well as the -value of tick. The duration of the calibration interval is set by the -pps_shift variable as a shift in powers of two. The minimum value -PPS_SHIFT (2) is chosen so that with the highest CPU oscillator -frequency 1024 Hz and frequency tolerance 100 ppm the tick will not -overflow. The maximum value PPS_SHIFTMAX (8) is chosen such that the -maximum averaging time is about 1000 s as determined by measurements of -Allan variance [MIL93]. - -Should the PPS signal fail, the current frequency estimate pps_freq -continues to be used, so the nominal frequency remains correct subject -only to the instability of the undisciplined oscillator. The procedure -to save and restore the frequency estimate works as follows. When -setting the frequency from a file, the time_freq value is set as the -file value minus the pps_freq value; when retrieving the frequency, the -two values are added before saving in the file. This scheme provides a -seamless interface should the PPS signal fail or the kernel -configuration change. Note that the frequency discipline is active -whether or not the synchronization daemon is active. Since all Unix -systems take some time after reboot to build a running system, usually -by that time the discipline process has already settled down and the -initial transients due to frequency discipline have damped out. -3.1.4. External Clock Interface - -The external clock driver interface is implemented with two routines, -microtime(), which returns the current clock time, and clock_set(), -which furnishes the apparent system time derived from the kernel time -variable. The latter routine is called only when the clock is set using -the settimeofday() system call, but can be called from within the -driver, such as when the year rolls over, for example. - -In the stock SunOS kernel and modified Ultrix and OSF/1 kernels, the -microtime() routine returns the kernel time variable plus an -interpolation between timer interrupts based on the contents of a -hardware counter. In the case of an external clock, such as described -above, the system clock is read directly from the hardware clock -registers. Examples of external clock drivers are in the tprotime.c and -hightime.c routines included in the kernel.tar.Z distribution. - -The external clock routines return a status code which indicates whether -the clock is operating correctly and the nature of the problem, if not. -The return code is interpreted by the ntp_gettime() system call, which -transitions the status state machine to the TIME_ERR state if an error -code is returned. This is the only error checking implemented for the -external clock in the present version of the code. - -The simulator has been used to check the PLL operation over the design -envelope of +-512 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 a few percent and a final -convergence time of several hours, depending on the initial time and -frequency error. - -3.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. 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 -synchronization 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 status bit of either STA_DEL, if a second is to be deleted, or -STA_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, nor is there likely to be one in future. If the bit is -STA_DEL, the kernel adds one second to the system time immediately -following second 23:59:58 and resets the clock state to TIME_WAIT. If -the bit is STA_INS, the kernel subtracts one second from the system time -immediately following second 23:59:59 and resets the clock stateto -TIME_OOP, in effect causing system time to repeat second 59. Immediately -following the repeated second, the kernel resets the clock status to -TIME_WAIT. - -Following the leap operations, the clock remains in the TIME_WAIT state -until both the STA_DEL and STA_INS status bits are reset. This provides -both an unambiguous indication that a leap recently occured, as well as -time for the daemon or operator to clear the warning condition. - -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), 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. - -3.3. Clock Status State Machine - -The various options possible with the system clock model described in -this memorandum require a careful examination of the state transitions, -status indications and recovery procedures should a crucial signal or -interface fail. In this section is presented a prototype state machine -designed to support leap second insertion and deletion, as well as -reveal various kinds of errors in the synchronization process. The -states of this machine are decoded as follows: - - TIME_OK If a PPS signal or external clock is present, it is - working properly and the system clock is derived - from it. If not, the synchronization daemon is - working properly and the system clock is - synchronized to a radio clock or one or more peers. - - TIME_INS An insertion of one second in the system clock has - been declared following the last second of the - current day, but has not yet been executed. - - TIME_DEL A deletion of the last second of the current day has - been declared, but not yet executed. - - TIME_OOP An insertion of one second in the system clock has - been declared following the last second of the - current day. The second is in progress, but not yet - completed. Library conversion routines should - interpret this second as 23:59:60. - - TIME_WAIT The scheduled leap event has occurred, but the - STA_DEL and STA_INS status bits have not yet been - cleared. - - TIME_ERROR Either (a) the synchronization daemon has declared - the protocol is not working properly, (b) all - sources of outside synchronization have been lost or - (c) a PPS signal or external clock is present, but - not working properly. - -In all states the system clock is derived from either a PPS signal or -external clock, if present, or the kernel time variable, if not. If a -PPS error condition is recognized, the PPS signal is disabled and -ntp_adjtime() updates are used instead. If an external clock error -condition is recognized, the external clock is disabled and the kernel -time variable is used instead. - -The state machine makes a transition once each second at an instant -where the microseconds field of the kernel time variable overflows and -one second is added to the seconds field. However, this condition is -checked when the timer overflows, which may not coincide with the actual -seconds increment. This may lead to some interesting anomalies, such as -a status indication of a leap second in progress (TIME_OOP) when the -leap second has already expired. This ambiguity is unavoidable, unless -the timer interrupt is made synchronous with the system clock. - -The following state transitions are executed automatically by the kernel -at rollover of the microseconds field: - - any state -> TIME_ERROR This transition occurs when an error - condition is recognized and continues as long - as the condition persists. The error indication - overrides the normal state indication, but does - not affect the actual clock state. Therefore, - when the condition is cleared, the normal state - indication resumes. - - TIME_OK->TIME_DEL This transition occurs if the STA_DEL bit is - set in the status word. - - TIME_OK->TIME_INS This transition occurs if the STA_INS bit is - set in the status word. - - TIME_INS->TIME_OOP This transition occurs immediately following - second 86,400 of the current day when an - insert-second event has been declared. - - TIME_OOP->TIME_WAIT This transition occurs immediately following - second 86,401 of the current day; that is, one - second after entry to the TIME_OOP state. - - TIME_DEL->TIME_WAIT This transition occurs immediately following - second 86,399 of the current day when a delete- - second event has been declared. - - TIME_WAIT->TIME_OK This transition occurs when the STA_DEL and - STA_INS bits are cleared by an ntp_adjtime() - call. - -The following table summarizes the actions just before, during and just -after a leap-second event. Each line in the table shows the UTC and NTP -times at the beginning of the second. The left column shows the behavior -when no leap event is to occur. In the middle column the state machine -is in TIME_INS at the end of UTC second 23:59:59 and the NTP time has -just reached 400. The NTP time is set back one second to 399 and the -machine enters TIME_OOP. At the end of the repeated second the machine -enters TIME_OK and the UTC and NTP times are again in correspondence. In -the right column the state machine is in TIME_DEL at the end of UTC -second 23:59:58 and the NTP time has just reached 399. The NTP time is -incremented, the machine enters TIME_OK and both UTC and NTP times are -again in correspondence. - - No Leap Leap Insert Leap Delete - UTC NTP UTC NTP UTC NTP - --------------------------------------------- - 23:59:58|398 23:59:58|398 23:59:58|398 - | | | - 23:59:59|399 23:59:59|399 00:00:00|400 - | | | - 00:00:00|400 23:59:60|399 00:00:01|401 - | | | - 00:00:01|401 00:00:00|400 00:00:02|402 - | | | - 00:00:02|402 00:00:01|401 00:00:03|403 - | | | -To determine local midnight without fuss, the kernel code simply finds -the residue of the time.tv_sec (or time.tv_sec + 1) 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. Programming Model and Interfaces - -This section describes the programming model for the synchronization -daemon and user application programs. 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 new features 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 synchronization -daemon other than NTP, for example. - -The kernel routines use the clock state variable time_state, 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. It is set implicitly -by the STA_DEL and STA_INS status bits, as described previously. Values -presently defined in the timex.h header file are as follows: - - TIME_OK 0 no leap second warning - TIME_INS 1 insert leap second warning - TIME_DEL 2 delete leap second warning - TIME_OOP 3 leap second in progress - TIME_WAIT 4 leap second has occured - TIME_ERROR 5 clock not synchronized - -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.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, -except for the SHIFT_HZ define, in the SunOS, Ultrix and OSF/1 kernel -distributions. (The SHIFT_HZ define represents the logarithm to the base -2 of the clock oscillator frequency specific to each system type.) 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 (ro) */ - long maxerror; /* maximum error (us) (ro) */ - long esterror; /* estimated error (us) (ro) */ - }; - -The ntp_gettime() system call returns three read-only (ro) 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. In the NTP Version 3 -specification, if the protocol computes either of these values in excess -of 16 seconds, they are clamped to that value and the system clock -declared unsynchronized. - -Following is a detailed description of the ntptimeval structure members. - -struct timeval time (ro) - - This member is the current system time expressed as a Unix timeval - structure. The timeval structure consists of two 32-bit words; the - first is the number of seconds past 1 January 1970 assuming no - intervening leap-second insertions or deletions, while the second - is the number of microseconds within the second. - -long maxerror (ro) - - This member is the value of the time_maxerror kernel variable, - which represents the maximum error of the indicated time relative - to the primary synchronization source, in microseconds. For NTP, - the value is initialized by a ntp_adjtime() call to 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 maximum clock frequency - error. This variable is provided bu a ntp-adjtime() system call and - modified by the kernel, but is otherwise not used by the kernel. - -long esterror (ro) - - This member is the value of the time_esterror kernel variable, - which represents the expected error of the indicated time relative - to the primary synchronization 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 provided bu a ntp-adjtime() - system call, but is otherwise not used by the kernel. - -4.2. The ntp_adjtime() System Call - -The syntax and semantics of the ntp_adjtime() call are given in the -following fragment of the timex.h header file. Note that, as in the -ntp_gettime() system call, the syscall.h system header file must be -modified to define the SYS_ntp_adjtime system call specific to each -system type. In the fragment, rw = read/write, ro = read-only, wo = -write-only. - - /* - * 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 { - unsigned int mode; /* mode selector (wo) */ - long offset; /* time offset (us) (rw) */ - long frequency; /* frequency offset (scaled ppm) (rw) - */ - long maxerror; /* maximum error (us) (rw) */ - long esterror; /* estimated error (us) (rw) */ - int status; /* clock status bits (rw) */ - long constant; /* pll time constant (rw) */ - long precision; /* clock precision (us) (ro) */ - long tolerance; /* clock frequency tolerance (scaled - * ppm) (ro) */ - /* - * The following read-only structure members are implemented - * only if the PPS signal discipline is configured in the - * kernel. - */ - long ppsfreq; /* pps frequency (scaled ppm) (ro) */ - long jitter; /* pps jitter (us) (ro) */ - int shift; /* interval duration (s) (shift) (ro) - */ - long stabil; /* pps stability (scaled ppm) (ro) */ - long jitcnt; /* jitter limit exceeded (ro) */ - long calcnt; /* calibration intervals (ro) */ - long errcnt; /* calibration errors (ro) */ - long stbcnt; /* stability limit exceeded (ro) */ - }; - -The ntp_adjtime() system call is used to read and write certain time- -related kernel variables summarized below. 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. - -mode (wo) - - 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, with the variable name - indicated in parens. Note that the precision, tolerance and PPS - variables are determined by the kernel and cannot be changed by - ntp_adjtime(). - - MOD_OFFSET 0x0001 time offset (offset) - MOD_FREQUENCY 0x0002 frequency offset (frequency) - MOD_MAXERROR 0x0004 maximum time error (maxerror) - MOD_ESTERROR 0x0008 estimated time error (esterror) - MOD_STATUS 0x0010 clock status (status) - MOD_TIMECONST 0x0020 pll time constant (constant) - MOD_CLKB 0x4000 set clock B - MOD_CLKA 0x8000 set clock A - - Note that the MOD_CLK0 and MOD_CLK1 bits are intended for those - systems where more than one hardware clock is available for backup, - such as in Tandem Non-Stop computers. Presumably, in such cases - each clock would have its own oscillator and require a separate PLL - for each. Refinements to this model are for further study. The - interpretation of these bits is as follows: - -offset (rw) - - If selected, this member specifies the time adjustment, in - microseconds. The absolute value must be less than MAXPHASE - (128000) microseconds defined in the timex.h header file. On - return, this member contains the residual offset remaining between - a previously specified offset and the current system time, in - microseconds. - -frequency (rw) - - If selected, this member replaces the value of the time_frequency - kernel variable. The value is in ppm, with the integer part in the - high order 16 bits and fraction in the low order 16 bits. The - absolute value must be in the range less than MAXFREQ (100) ppm - defined in the timex.h header file. - - The time_freq variable represents the frequency offset of the CPU - clock oscillator. It is recalculated as each update to the system - clock is determined by the offset member of the timex structure. It - is usually set from a value stored in a file when the - synchronization daemon is first started. The current value is - usually retrieved via this member and written to the file about - once per hour. - -maxerror (rw) - - If selected, this member replaces the value of the time_maxerror - kernel variable, in microseconds. This is the same variable as in - the ntp_getime() system call. - -esterror (rw) - - If selected, this member replaces the value of the time_esterror - kernel variable, in microseconds. This is the same variable as in - the ntp_getime() system call. - -int status (rw) - - If selected, this member replaces the value of the time_status - kernel variable. This variable controls the state machine used to - insert or delete leap seconds and shows the status of the - timekeeping system, PPS signal and external oscillator, if - configured. - - STA_PLL 0x0001 enable PLL updates (r/w) - STA_PPSFREQ 0x0002 enable PPS freq discipline (r/w) - STA_PPSTIME 0x0004 enable PPS time discipline (r/w) - STA_INS 0x0010 insert leap (r/w) - STA_DEL 0x0020 delete leap (r/w) - STA_UNSYNC 0x0040 clock unsynchronized (r/w) - STA_PPSSIGNAL 0x0100 PPS signal present (r) - STA_PPSJITTER 0x0200 PPS signal jitter exceeded (r) - STA_PPSWANDER 0x0400 PPS signal wander exceeded (r) - STA_PPSERROR 0x0800 PPS signal calibration error (r) - STA_CLOCKERR 0x1000 clock hardware fault (r) - - The interpretation of these bits is as follows: - - STA_PLL set/cleared by the caller to enable PLL updates - - STA_PPSFREQ set/cleared by the caller to enable PPS frequency - discipline - - STA_PPSTIME set/cleared by the caller to enable PPS time - discipline - - STA_INS set by the caller to insert a leap second at the end - of the current day; cleared by the caller after the - event - - STA_DEL set by the caller to delete a leap second at the end - of the current day; cleared by the caller after the - event - - STA_UNSYNC set/cleared by the caller to indicate clock - unsynchronized (e.g., when no peers are reachable) - - STA_PPSSIGNAL set/cleared by the hardpps() fragment to indicate - PPS signal present - - STA_PPSJITTER set/cleared by the hardpps() fragment to indicates - PPS signal jitter exceeded - - STA_PPSWANDER set/cleared by the hardpps() fragment to indicates - PPS signal wander exceeded - - STA_PPSERROR set/cleared by the hardpps() fragment to indicates - PPS signal calibration error - - STA_CLOCKERR set/cleared by the external hardware clock driver to - indicate hardware fault - - An error condition is raised when (a) either STA_UNSYNC or - STA_CLOCKERR is set (loss of synchronization), (b) STA_PPSFREQ or - STA_PPSTIME is set and STA_PPSSIGNAL is clear (loss of PPS signal), - (c) STA_PPSTIME and STA_PPSJITTER are both set (jitter exceeded), - (d) STA_PPSFREQ is set and either STA_PPSWANDER or STA_PPSERROR is - set (wander exceeded). An error condition results in a system call - return code of TIME_ERROR. - -constant (rw) - - If selected, this member replaces the value of the time_constant - kernel variable. The value must be between zero and MAXTC (6) - defined in the timex.h header file. - - The time_constant variable determines the bandwidth or "stiffness" - of the PLL. The value is used as a shift between zero and MAXTC - (6), with the effective PLL time constant equal to a multiple of (1 - << time_constant), in seconds. For room-temperature quartz - oscillators, the recommended default value is 2, which corresponds - to a PLL time constant of about 900 s and a maximum update interval - of about 64 s. The maximum update interval scales directly with the - time constant, so that at the maximum time constant of 6, the - update interval can be as large as 1024 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 an precision external oscillator is - present. - -precision (ro) - - This is the current value of the time_precision kernel variable in - microseconds. - - The time_precision variable represents the maximum error in reading - the system clock, in microseconds. It is usually based on the - number of microseconds between timer interrupts (tick), 10000 us - for the SunOS kernel, 3906 us for the Ultrix kernel, 976 us for the - OSF/1 kernel. However, in cases where the time can be interpolated - between timer interrupts with microsecond resolution, such as in - the stock SunOS kernel and modified Ultrix and OSF/1 kernels, the - precision is specified as 1 us. In cases where a PPS signal or - external oscillator is available, the precision can depend on the - operating condition of the signal or oscillator. This variable is - determined by the kernel for use by the synchronization daemon, but - is otherwise not used by the kernel. - -tolerance (ro) - - This is the current value of the time_tolerance kernel variable. - The value is in ppm, with the integer part in the high order 16 - bits and fraction in the low order 16 bits. - - The time_tolerance variable represents the maximum frequency error - in ppm of the particular CPU clock oscillator and is a property of - the hardware; however, in principle it could change as result of - the presence of external discipline signals, for instance. - - The recommended value for time_tolerance MAXFREQ (200) ppm is - appropriate for room-temperature quartz oscillators used in typical - workstations. However, it can change due to the operating condition - of the PPS signal and/or external oscillator. With either the PPS - signal or external oscillator, the recommended value for MAXFREQ is - 100 ppm. - -The following members are defined only if the PPS_SYNC option is -specified in the kernel configuration file. These members are useful -primarily as a monitoring and evalutation tool. These variables can be -written only by the kernel. - -ppsfreq (ro) - - This is the current value of the pps_freq kernel variable, which is - the CPU clock oscillator frequency offset relative to the PPS - discipline signal. The value is in ppm, with the integer part in - the high order 16 bits and fraction in the low order 16 bits. - -jitter (ro) - - This is the current value of the pps_jitter kernel variable, which - is the average PPS time dispersion measured by the time-offset - median filter, in microseconds. - -shift (ro) - - This is the current value of the pps_shift kernel variable, which - determines the duration of the calibration interval as the value of - 1 << pps_shift, in seconds. -stabil (ro) - - This is the current value of the pps_stabil kernel variable, which - is the average PPS frequency dispersion measured by the frequency- - offset median filter. The value is in ppm, with the integer part in - the high order 16 bits and fraction in the low order 16 bits. - -jitcnt (ro) - - This is the current value of the pps_jitcnt kernel variable, counts - the number of PPS signals where the average jitter exceeds the - threshold MAXTIME (200 us). - -calcnt (ro) - - This is the current value of the pps_calcnt kernel variable, which - counts the number of frequency calibration intervals. The duration - of these intervals can range from 4 to 256 seconds, as determined - by the pps_shift kernel variable. - -errcnt (ro) - - This is the current value of the pps_errcnt kernel variable, which - counts the number of frequency calibration cycles where (a) the - apparent frequency offset is greater than MAXFREQ (100 ppm) or (b) - the interval jitter exceeds tick * 2. - -stbcnt (ro) - - This is the current value of the pps_discnt kernel variable, which - counts the number of calibration intervals where the average - stability exceeds the threshold MAXFREQ / 4 (25 ppm). - -7. References - -[MIL91] Mills, D.L. Internet time synchronization: the Network Time -Protocol, IEEE Trans. Communications COM-39, 10 (October 1991), -1482-1493. Also in: Yang, Z., and T.A. Marsland (Eds.). Global -States and Time in Distributed Systems, IEEE Press, Los Alamitos, -CA, 91-102. - -[MIL92a] Mills, D.L. Network Time Protocol (Version 3) specification, -implementation and analysis, RFC 1305, University of Delaware, March -1992, 113 pp. - -[MIL92b] Mills, D.L. Modelling and analysis of computer network clocks, -Electrical Engineering Department Report 92-5-2, University of Delaware, -May 1992, 29 pp. - -[MIL92c] Mills, D.L. Simple Network Time Protocol (SNTP), RFC 1361, -University of Delaware, August 1992, 10 pp. - -[MIL93] Mills, D.L. Precision synchronizatin of computer network clocks, -Electrical Engineering Department Report 93-11-1, University of -Delaware, November 1993, 66 pp. - -[LEV89] Levine, J., M. Weiss, D. Davis, D. Allan, and D. Sullivan. The -NIST automated computer time service. J. Research National Institute of -Standards and Technology 94, 5 (September-October 1989), 311-321. - -David L. Mills <mills@udel.edu> -Electrical Engineering Department -University of Delaware -Newark, DE 19716 -302 831 8247 fax 302 831 4316 -3 April 1994 diff --git a/usr.sbin/xntpd/doc/README.magic b/usr.sbin/xntpd/doc/README.magic deleted file mode 100644 index f473a92..0000000 --- a/usr.sbin/xntpd/doc/README.magic +++ /dev/null @@ -1,346 +0,0 @@ - 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/README.refclock b/usr.sbin/xntpd/doc/README.refclock deleted file mode 100644 index 8c6c228..0000000 --- a/usr.sbin/xntpd/doc/README.refclock +++ /dev/null @@ -1,1421 +0,0 @@ - Information on Reference Clock Drivers - - Revised 5 August 1994 - -Support for most of the commonly available radio clocks is included in -the default configuration of xntpd. Individual clocks can be activated -by configuration file commands, specifically the server and fudge -commands described in the xntpd.8 man page. This file contains -information useful in configuring and operating these clocks. Note that -the man pages and documentation files mentioned in this note can be -found in the ./doc directory of the xntp3 distribution. - -Radio clocks by convention have addresses in the form 127.127.t.u, where -"t" is the clock type and "u" is a unit number in the range 0-3 used to -distinguish multiple instances of clocks of the same type. Most of these -clocks require support in the form of a serial port or special bus -peripheral. The particular device is normally specified by adding a soft -link /dev/device%d to the particular hardware device involved. The name -"device" is compiled in the driver according to the table below. The -table shows the type number, device name, short description used in some -displays, and long description used in other displays. - -Type Device Name Description -------------------------------------------------------- -1 (none) LOCAL Undisciplined Local Clock -2 trak GPS_TRAK TRAK 8820 GPS Receiver -3 pst WWV_PST PSTI/Traconex WWV/WWVH Receiver -4 wwvb WWVB_SPEC Spectracom WWVB Receiver -5 goes GPS_GOES_TRUE TrueTime GPS/GOES Receivers -6 irig IRIG_AUDIO IRIG Audio Decoder -7 chu CHU Scratchbuilt CHU Receiver -8 refclock- GENERIC Generic Reference Clock Driver -9 gps GPS_MX4200 Magnavox MX4200 GPS Receiver -10 gps GPS_AS2201 Austron 2201A GPS Receiver -11 omega OMEGA_TRUE TrueTime OM-DC OMEGA Receiver -12 tpro IRIG_TPRO KSI/Odetics TPRO/S IRIG Interface -13 leitch ATOM_LEITCH Leitch CSD 5300 Master Clock Controller -14 ees MSF_EES EES M201 MSF Receiver -15 gpstm GPS_TRUE TrueTime GPS/TM-TMD Receiver -16 * GPS_BANC Bancomm GPS/IRIG Receiver -17 datum GPS_DATUM Datum Precision Time System -18 acts NIST_ACTS NIST Automated Computer Time Service -19 heath WWV_HEATH Heath WWV/WWVH Receiver -20 nmea GPS_NMEA Generic NMEA GPS Receiver -21 * GPS_MOTO Motorola Six Gun GPS Receiver -22 pps ATOM_PPS PPS Clock Discipline - -* Not yet available. - -A radio clock is specified in the configuration using the server command - - server 127.127.t.u [ prefer ] [ mode m ] - -where t is the type number above and u can be in the range 0-3, -conventionally 1. Ordinarily, this is the only command necessary to -configure a radio clock. The optional prefer keyword can be used to -modify the clock selection algorithm as described in Appendix B. For -those clock drivers that support multiple modes of operation, the -optional mode parameter selects which one. This parameter affects the -operation of each driver as described in Appendix A. - -In rare cases a fudge command is necessary to specify additional -details. This command has the following syntax - -fudge 127.127.t.u [stratum s] [refid r] [time1 t1] [time2 t2] [flags] -and must follow the corresponding server command in the configuration -file. The optional fields following the clock address are interpreted as -follows: - -stratum s The s, a decimal number in the range 0-15, overrides the - default stratum assigned by the driver. - -refid r The r, a 4-character, null-terminated ASCII string, overrides - the reference identifier assigned by the driver. - -time1 t1 The t1, a fixed-point decimal number in seconds, specifies a - constant to be added to the time offset produced by the - driver. This provides a way to correct a systematic error or - bias on the part of the particular clock. - -time2 t2 The t2, a fixed-point decimal number, is interpreted in a - driver-dependent way. See the descriptions of specific clock - drivers in Appendix A. - -There are four optional flags named flag1, flag2, flag3 and flag4. A -flag is specified in the form <keyword> <value>, where <keyword> is one -of the flag names and <value> is either 0 or 1, as appropriate. Two of -the flags are generic and are interpreted by all applicable drivers, and -two are driver dependent. The generic ones are as follows: - -flag4 This flag is used to enable detailed status monitoring and - event recording. The data collected are written to the - clockstats file maintained by the filegen utility (See the - xntpd.8 man page). This file is normally processed by a cron - job run once per day to produce summary statistics and - performance data. The ./scripts/stats directory contains a - number of shell and awk scripts for this, as well as S- - language programs that produce PostScript plots of performance - data. - -flag3 This flag is used with Sun SPARCstation baseboard serial ports - to assign the ppsclock streams driver for a 1-pps signal - produced by some radio clocks and timekeeping devices. See the - dscription of the PPS Clock Discipline Driver (type 22) in - Appendix A for further information. - -Note that the fudge factors above can be changed at run time using the -xntpdc program (see the xntpdc.8 man page). This program does not have -to be run on the server machine itself, since it communicates with the -xntpd daemon using cryptographically authenticated messages. - -The PPS Signal - -Some radio clocks and related timekeeping gear have a pulse-per-second -(PPS) signal that can be used to discipline the local clock oscillator -to a high degree of precision, typically to the order less than 50 us in -time and 0.1 ppm in frequency. The PPS signal can be connected in either -of two ways, either via the data leads of a serial port or via the modem -control leads. Either way requires conversion of the PPS signal, usually -at TTL levels, to RS232 levels, which can be done using a circuit such -as described in the ./gadget directory of the xntp3 distribution. - -The data leads interface requires regenerating the PPS pulse and -converting to RS232 signal levels, so that the pulse looks like a -legitimate ASCII character. The tty_clk module in the ./kernel directory -inserts a timestamp following this character in the input data stream. -The driver uses this timestamp to determine the time of arrival of the -PPS pulse to within 26 us at 38.4 kbps while eliminating error due to -operating system queues and service times. In order to use the tty_clk -module, the xntp3 distribution must be compiled with CLK defined. -The modem control leads interface requires converting to RS232 levels -and connecting to the carrier detect (CD) lead of a serial port. The -ppsclock streams module in the ./ppsclock directory is used to capture a -timestamp upon transition of the PPS signal. The driver reads the latest -timestamp with a designated ioctl() system call to determine the time of -arrival of the PPS pulse to within a few tens of microseconds. In order -to use the ppsclock module, the xntp3 distribution must be compiled with -PPS defined. - -Both of these mechanisms are supported by the ATOM_PPS reference clock -driver described in Appendix A. This driver is ordinarily used in -conjunction with another clock driver that supports the radio clock that -produces the PPS pulse. This driver furnishes the coarse timecode used -to disambiguate the seconds numbering of the PPS pulse itself. The NTP -daemon mitigates between the radio clock driver and ATOM_PPS driver as -described in Appendix B in order to provide the most accurate time, -while respecting the various types of equipment failures that could -happen. - -For the utmost time quality, a number of Unix system kernel -modifications can be made as described in the README.magic and -README.kernel files. Specifically, the ppsclock module can be used to -interface the PPS signal directly to the kernel for use as discipline -sources for both time and frequency. These sources can be separately -enabled and monitored using the ntp_adjtime() system call described in -README.kernel and the ./include/sys/timex.h header file in the xntp3 -distribution. In order to use the kernel PPS signal, the xntp3 -distribution must be compiled with KERNEL_PLL defined. - -In some configurations may have multiple radio clocks, each with PPS -outputs, as well as a kernel modified to use the PPS signal. In order to -provide the highest degree of redundancy and survivability, the kernel -PPS discipline, tty_clk module and ppsclock module may all be in use at -the same time, each backing up the other. The sometimes complicated -mitigation rules are described in Appendix B. - -Debugging Hints - -The ntpq and xntpdc utility programs can be used to debug reference -clocks, either on the server itself or from another machine elsewhere in -the network. The server is compiled, installed and started using the -command-line switches described in the xntpd.8 man page. The first thing -to look for are error messages on the system log. If none occur, the -daemon has started, opened the devices specified and waiting for peers -and radios to come up. - -The next step is to be sure the RS232 messages, if used, are getting to -and from the clock. The most reliable way to do this is with an RS232 -tester and to look for data flashes as the driver polls the clock and/or -as data arrive from the clock. Our experience is that the overwhelming -fraction of problems occurring during installation are due to problems -such as miswired connectors or improperly configured radio clocks at -this stage. - -If RS232 messages are getting to and from the clock, the variables of -interest can be inspected using the ntpq program and various commands -described in the ntpq.8 man page. First, use the pe and as commands to -display a pair of billboards showing the peer configuration and -association IDs for all peers, including the radio clock peers. The -assigned clock address should appear in the pe billboard and the -association ID for it at the same relative line position in the as -billboard. If things are operating correctly, after a minute or two -samples should show up in the pe display line for the clock. - -Additional information is available with the rv and clockvar commands, -which take as argument the association ID shown in the as billboard. The -rv command with no argument shows the system variables, while the rv -command with argument shows the peer variables for the clock, as well as -any other peers of interest. The clockvar command with argument shows -the peer variables specific to reference clock peers, including the -clock status, device name, last received timecode (if relevant), and -various event counters. In addition, a subset of the fudge parameters is -included. - -The xntpdc utility program can be used for detailed inspection of the -clock driver status. The most useful are the clockstat and clkbug -commands described in the xntpdc.8 man page. While these commands permit -getting quite personal with the particular driver involved, their use is -seldom necessary, unless an implementation bug shows up. - -Most drivers write a message to the clockstats file as each timecode or -surrogate is received from the radio clock. By convention, this is the -last ASCII timecode (or ASCII gloss of a binary-coded one) received from -the radio. This file is managed by the filegen facility described in the -xntpd.8 man page and requires specific commands in the configuration -file. This forms a highly useful record to discover anomalies during -regular operation of the clock. The scripts included in the -./scripts/stats directory can be run from a cron job to collect and -summarize these data on a daily or weekly basis. The summary files have -proven invaluable to detect infrequent misbehavior due to clock -implementation bugs in some radios. - -Appendix A. Individual Driver Descriptions - -Following are detailed descriptions of the clock drivers, together with -configuration data useful for special circumstances. - -Type 1: Undisciplined Local Clock - - This is a hack to allow a machine to use its own system clock as a - reference clock, i.e., to free-run using no outside clock - discipline source. This is useful if you want to use NTP in an - isolated environment with no radio clock or NIST modem available. - Pick a machine that you figure has a good clock oscillator and - configure it with this driver. Set the clock using the best means - available, like eyeball-and-wristwatch. Then, point all the other - machines at this one or use broadcast (not multicast) mode to - distribute time. - - Another application for this driver is if you want to use a - particular server's clock as the clock of last resort when all - other normal synchronization sources have gone away. This is - especially useful if that server has an ovenized oscillator. For - this you would configure this driver at a higher stratum (say 3 or - 4) to prevent the server's stratum from falling below that. - - A third application for this driver is when an external discipline - source is available, such as the NIST "lockclock" program, which - synchronizes the local clock via a telephone modem and the NIST - Automated Computer Time Service (ACTS), or the Digital Time - Synchronization Service (DTSS), which runs on DCE machines. In this - case the stratum should be set at zero, indicating a bona fide - stratum-1 source. Exercise some caution with this, since there is - no easy way to telegraph via NTP that something might be wrong in - the discipline source itself. In the case of DTSS, the local clock - can have a rather large jitter, depending on the interval between - corrections and the intrinsic frequency error of the clock - oscillator. In extreme cases, this can cause clients to exceed the - 128-ms slew window and drop off the NTP subnet. - - In the default mode the behavior of the clock selection algorithm - is modified when this driver is in use. The algorithm is designed - so that this driver will never be selected unless no other - discipline source is available. This can be overridden with the - prefer keyword of the server configuration command, in which case - only this driver will be selected for synchronization and all other - discipline sources will be ignored. This behavior is intended for - use when an external discipline source controls the system clock. - - Fudge Factors - - The stratum for this driver LCLSTRATUM is set at 3 by default, but - can be changed by the fudge command and/or the xntpdc utility. The - reference ID is "LCL" by default, but can be changed using the same - mechanisms. *NEVER* configure this driver to operate at a stratum - which might possibly disrupt a client with access to a bona fide - primary server, unless the local clock oscillator is reliably - disciplined by another source. *NEVER NEVER* configure a server - which might devolve to an undisciplined local clock to use - multicast mode. - - This driver provides a mechanism to trim the local clock in both - time and frequency, as well as a way to manipulate the leap bits. - The fudge time1 parameter adjusts the time, in seconds, and the - fudge time2 parameter adjusts the frequency, in ppm. Both - parameters are additive; that is, they add increments in time or - frequency to the present values. (Note: The frequency cannot be - changed when the kernel modifications are in use - see the - README.kern file). The fudge flag1 and fudge flag2 bits set the - corresponding leap bits; for example, setting flag1 causes a leap - second to be added at the end of the UTC day. These bits are not - reset automatically when the leap takes place; they must be turned - off manually after the leap event. - -Type 2: TRAK 8820 GPS Receiver - - This driver supports the TRAK 8820 GPS Station Clock. The claimed - accuracy at the 1-pps output is 200-300 ns relative to the - broadcast signal; however, in most cases the actual accuracy is - limited by the precision of the timecode and the latencies of the - serial interface and operating system. - - For best accuracy, this radio requires the LDISC_ACTS line - discipline, which captures a timestamp at the '*' on-time character - of the timecode. Using this discipline the jitter is in the order - of 1 ms and systematic error about 0.5 ms. If unavailable, the - buffer timestamp is used, which is captured at the \r ending the - timecode message. This introduces a systematic error of 23 - character times, or about 24 ms at 9600 bps, together with a jitter - well over 8 ms on Sun IPC-class machines. - - Using the menus, the radio should be set for 9600 bps, one stop bit - and no parity. It should be set to operate in computer (no echo) - mode. The timecode format includes neither the year nor leap-second - warning. No provisions are included in this preliminary version of - the driver to read and record detailed internal radio status. - - In operation, this driver sends a RQTS\r request to the radio at - initialization in order to put it in continuous time output mode. - The radio then sends the following message once each second: - - *RQTS U,ddd:hh:mm:ss.0,q<cr><lf> - - on-time = '*' - ddd = day of year - hh:mm:ss = hours, minutes, seconds - q = quality indicator (phase error), 0-6: - 0 > 20 us - 6 > 10 us - 5 > 1 us - 4 > 100 ns - 3 > 10 ns - 2 < 10 ns - - The alarm condition is indicated by '0' at Q, which means the radio - has a phase error than 20 usec relative to the broadcast time. The - absence of year, DST and leap-second warning in this format is also - alarming. - - The continuous time mode is disabled using the RQTX<cr> request, - following which the radio sends a RQTX DONE<cr><lf> response. In - the normal mode, other control and status requests are effective, - including the leap-second status request RQLS<cr>. The radio - responds with RQLS yy,mm,dd<cr><lf>, where yy,mm,dd are the year, - month and day. Presumably, this gives the epoch of the next leap - second, RQLS 00,00,00 if none is specified in the GPS message. - Specified in this form, the information is generally useless and is - ignored by the driver. - - Fudge Factors - - There are no special fudge factors other than the generic. - -Type 3: PSTI/Traconex WWV/WWVH Receiver - - This driver supports the PSTI 1010 and Traconex 1020 WWV/WWVH - Receivers. No specific claim of accuracy is made for these - receiver, but actual experience suggests that 10 ms would be a - conservative assumption. - - The DIPswitches should be set for 9600 bps line speed, 24-hour day- - of-year format and UTC time zone. Automatic correction for DST - should be disabled. It is very important that the year be set - correctly in the DIPswitches; otherwise, the day of year will be - incorrect after 28 April of a normal or leap year. The propagation - delay DIPswitches should be set according to the distance from the - transmitter for both WWV and WWVH, as described in the - instructions. While the delay can be set only to within 11 ms, the - fudge time1 parameter can be used for vernier corrections. - - Using the poll sequence QTQDQM, the response timecode is in three - sections totalling 50 ASCII printing characters, as concatenated by - the driver, in the following format: - - ahh:mm:ss.fffs<cr> yy/dd/mm/ddd<cr> frdzycchhSSFTttttuuxx<cr> - - on-time = first <cr> - hh:mm:ss.fff = hours, minutes, seconds, milliseconds - a = AM/PM indicator (' ' for 24-hour mode) - yy = year (from DIPswitches) - dd/mm/ddd = day of month, month, day of year - s = daylight-saving indicator (' ' for 24-hour mode) - f = frequency enable (O = all frequencies enabled) - r = baud rate (3 = 1200, 6 = 9600) - d = features indicator (@ = month/day display enabled) - z = time zone (0 = UTC) - y = year (5 = 91) - cc = WWV propagation delay (52 = 22 ms) - hh = WWVH propagation delay (81 = 33 ms) - SS = status (80 or 82 = operating correctly) - F = current receive frequency (4 = 15 MHz) - T = transmitter (C = WWV, H = WWVH) - tttt = time since last update (0000 = minutes) - uu = flush character (03 = ^c) - xx = 94 (unknown) - - The alarm condition is indicated by other than '8' at A, which - occurs during initial synchronization and when received signal is - lost for an extended period; unlock condition is indicated by other - than "0000" in the tttt subfield at Q. - - Fudge Factors - - There are no special fudge factors other than the generic. - -Type 4: Spectracom WWVB Receiver - - This driver supports the Spectracom Model 8170 and Netclock/2 WWVB - Synchronized Clock. This clock has proven a reliable source of - time, except in some cases of high ambient conductive RF - interference. The claimed accuracy of the clock is 100 usec - relative to the broadcast signal; however, in most cases the actual - accuracy is limited by the precision of the timecode and the - latencies of the serial interface and operating system. - - The DIPswitches on this clock should be set to 24-hour display, - AUTO DST off, time zone 0 (UTC), data format 0 or 2 (see below) and - baud rate 9600. If this clock is to used as the source for the IRIG - Audio Decoder (refclock_irig.c in this distribution), set the - DIPswitches for AM IRIG output and IRIG format 1 (IRIG B with - signature control). - - There are two timecode formats used by these clocks. Format 0, - which is available with both the Netclock/2 and 8170, and format 2, - which is available only with the Netclock/2 and specially modified - 8170. - - Format 0 (22 ASCII printing characters): - - <cr><lf>i ddd hh:mm:ss TZ=zz<cr><lf> - - on-time = first <cr> - hh:mm:ss = hours, minutes, seconds - i = synchronization flag (' ' = in synch, '?' = out synch) - - The alarm condition is indicated by other than ' ' at A, which - occurs during initial synchronization and when received signal is - lost for about ten hours. - - Format 2 (24 ASCII printing characters): - - <cr><lf>iqyy ddd hh:mm:ss.fff ld - - on-time = <cr> - i = synchronization flag (' ' = in synch, '?' = out synch) - q = quality indicator (' ' = locked, 'A'...'D' = unlocked) - yy = year (as broadcast) - ddd = day of year - hh:mm:ss.fff = hours, minutes, seconds, milliseconds - - The alarm condition is indicated by other than ' ' at A, which - occurs during initial synchronization and when received signal is - lost for about ten hours. The unlock condition is indicated by - other than ' ' at Q. - - The Q is normally ' ' when the time error is less than 1 ms and a - character in the set 'A'...'D' when the time error is less than 10, - 100, 500 and greater than 500 ms respectively. The L is normally ' - ', but is set to 'L' early in the month of an upcoming UTC leap - second and reset to ' ' on the first day of the following month. - The D is set to 'S' for standard time 'I' on the day preceding a - switch to daylight time, 'D' for daylight time and 'O' on the day - preceding a switch to standard time. The start bit of the first - <cr> is synchronized to the indicated time as returned. - - This driver does not need to be told which format is in use - it - figures out which one from the length of the message. A three-stage - median filter is used to reduce jitter and provide a dispersion - measure. The driver makes no attempt to correct for the intrinsic - jitter of the radio itself, which is a known problem with the older - radios. - - Fudge Factors - - This driver can retrieve a table of quality data maintained - internally by the Netclock/2 receiver. If flag4 of the fudge - configuration command is set to 1, the driver will retrieve this - table and write it to the clockstats file on when the first - timecode message of a new day is received. - -Type 5: TrueTime GPS/GOES Receivers - - This driver supports 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. - -Type 6: IRIG Audio Decoder - - This driver supports the Inter-Range Instrumentation Group standard - time-distribution signal IRIG-B using the audio codec native to the - Sun SPARCstation. 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 README.irig file. - - Timing jitter using the decoder and a Sun IPC is in the order of a - few microseconds, although the overall 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 discipline as describe elsewhere in - this note. - - Fudge Factors - - There are no special fudge factors other than the generic. The - flag3 and flag4 flags are not applicable to this driver. - -Type 7: Scratchbuilt CHU Receiver - - This driver supports 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. - 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 known 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 in - general not useful. - - Fudge Factors - - The time1 option can be used to set the CHU propagation delay, - compensate for inherent latencies in the serial port hardware and - operating system. The default value is 0.0025 seconds, which is - about right for Toronto. Values for other locations can be - calculated using the propdelay program in the util directory of the - xntp3 distribution or equivalent means. - - The time2 option 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 propagation delay provided - by the time1 option. The default value is 0.0002 seconds, which is - about right for typical telephone modem chips. - - The flag1 option can be used to modify 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. - -Type 8: Generic Reference Clock Driver - - The timecode of these receivers is 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 adapted to be able to convert different time code - formats. If the daemon is - - compiled without the STREAM definition synchronization will work - without the Sun streams module, though accuracy is significantly - degraded. - - The actual receiver status is mapped into various synchronization - 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). - - 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 - synchronization. - - 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 synchronized to the reference clock, - while the hardware PPS signal controls the way time offsets are - determined. - - The use of the PPS option requires receivers with an accuracy of - better than 1ms. - Fudge factors - - Only two fudge factors are utilized. The time1 fudge factor defines - the phase offset of the synchronization character to the actual - time. On the availability of PPS information the time2 fudge factor - defines the skew between the PPS time stamp and the receiver - timestamp of the PPS signal. This parameter is usually zero, as - usually the PPS signal is believed in time and OS delays should be - corrected in the machine specific section of the kernel driver. - time2 needs only be set when the actual PPS signal is delayed for - some reason. The flag0 enables input filtering. This a median - filter with continuous sampling. The flag1 selects averaging of the - samples remaining after the filtering. Leap secondhandling is - controlled with the 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). - - ntpq (8) - - timecode variable - - The ntpq program can read clock variables command list several - variables. These hold the following information: refclock_time is - the local time with the offset to UTC (format HHMM). The currently - active receiver flags are listed in refclock_status. Additional - feature flags of the receiver are optionally listed in parentheses. - The actual time code is listed in timecode. A qualification of the - decoded time code format is following in refclock_format. The last - piece of information is the overall running time and the - accumulated times for the clock event states in refclock_states. - When PPS information is present additional variable are available. - refclock_ppstime lists then the PPS timestamp and refclock_ppsskew - lists the difference between RS232 derived timestamp and the PPS - timestamp. - - Unit encoding - - The unit field <u> encodes the device, clock type and the PPS - generation option. There are 4 possible units, which are encoded in - the lower two bits of the <u> field. The devices are named - /dev/refclock-0 through /dev/refclock-3. Bits 2 thru 6 encode the - clock type. The fudge factors of the clock type are taken from a - table clockinfo in refclock_parse.c. The generation of PPS - information for disciplining the local NTP clock is encoded in bit - 7 of <u>. - - Currently, nine clock types (devices /dev/refclock-0 - - /dev/refclock-3) are supported. - - 127.127.8.0-3 16 - - Meinberg PZF535 receiver (FM demodulation/TCXO / 50us) - - 127.127.8.4-7 16 - - Meinberg PZF535 receiver (FM demodulation/OCXO / 50us) - - 127.127.8.8-11 16 - - Meinberg DCF U/A 31 receiver (AM demodulation / 4ms) - - 127.127.8.12-15 16 - - ELV DCF7000 (sloppy AM demodulation / 50ms) - - 127.127.8.16-19 16 - - Walter Schmid DCF receiver Kit (AM demodulation / 1ms) - - 127.127.8.20-23 16 - - RAW DCF77 100/200ms pulses (Conrad DCF77 receiver module / 5ms) - - 127.127.8.24-27 16 - - RAW DCF77 100/200ms pulses (TimeBrick DCF77 receiver module / 5ms) - - 127.127.8.28-31 16 - - Meinberg GPS166 receiver (GPS / <<1us) - - 127.127.8.32-35 16 - - Trimble SV6 GPS receiver (GPS / <<1us) - - 127.127.8.40-43 16 - - RAW DCF77 100/200ms pulses (Boeder DCF77 receiver / 5ms) - - 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 - syslog facility. Every hour a summary of the accumulated times for - the clock states is listed via syslog. - - PPS support is only available when the receiver is completely - synchronized. The receiver is believed to deliver correct time for - an additional period of time after losing synchronizations, 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 - clockinfo field of the reference clock implementation. This - parameter cannot be configured by xntpdc. - - 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. - - 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 firmware release - available (Uni-Erlangen). This release must be used for proper - operation. - - 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 - synchronization. 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 - synchronizations 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. - -Type 9: Magnavox MX4200 GPS Receiver - - This driver supports the 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. - - Fudge Factors - - There are no special fudge factors other than the generic. - -Type 10: Austron 2201A GPS Receiver - - This driver supports the 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 Buffer - Module, Output Buffer Module, IRIG-B Interface Module and LORAN - Assist Module. It requires the RS232 Serial Interface module for - communication with the driver. - - 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 - xntp3 distribution. - - To achieve the high accuracy this device provides, it is necessary - to use the ppsclock feature of the xntp3 program distribution or, - alternatively, to install the kernel modifications described in the - README.kern. The clock can be wired to provide time to a single CPU - or bussed in parallel to several CPUs, with one CPU controlling the - receiver and the others just listening. Fair accuracy can be - achieved in the single-CPU configuration without use of the 1-pps - signal, but in multiple CPU configurations accuracy is severely - degraded without it. - - Fudge Factors - - There are no special fudge factors other than the generic. - -Type 11: TrueTime OM-DC OMEGA Receiver - - This driver supports the Kinemetrics/TrueTime OMEGA-DC OMEGA - Synchronized Clock connected via a serial port. This clock is - sufficiently different from other Kinemetrics/TrueTime models that - a separate driver is required. 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. - - Fudge Factors - - There are no special fudge factors other than the generic. - -Type 12: KSI/Odetics TPRO/S IRIG Interface - - This driver supports the KSI/Odetics TPRO and 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. - - Using the TPRO interface as a NTP reference clock provides - precision time only to xntpd and its clients. With suitable kernel - modifications, it is possible to use the TPRO as the CPU system - clock, avoiding errors introduced by the CPU clock oscillator - wander. See the README.kernel and kern.c files for further details. - -Type 13: Leitch CSD 5300 Master Clock Controller - - Information not available. - -Type 14: EES M201 MSF Receiver - - This driver supports the EES M201 MSF receiver connected to a Sun - SPARCstation running SunOS 4.x with the "ppsclock" STREAMS module. - - Fudge Factors - - 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. - -Type 15: TrueTime GPS/TM-TMD Receiver - - Information not available. - -Type 16: Bancomm GPS/IRIG Receiver - - Information not available. - -Type 17: Datum Precision Time System - - Information not available. - -Type 18: NIST Automated Computer Time Service - - This driver supports the NIST Automated Computer Time Service - (ACTS). It periodically dials a prespecified telephone number, - receives the NIST timecode data and calculates the local clock - correction. It designed primarily for use when neither a radio - clock nor connectivity to Internet time servers is available. For - the best accuracy, the individual telephone line/modem delay needs - to be calibrated using outside sources. - - The ACTS is located at NIST Boulder, CO, telephone 303 494 4774. A - toll call from Newark, DE, costs between three and four cents, - although it is not clear what carrier and time of day discounts - apply. The modem dial string will differ depending on local - telephone configuration, etc., and is specified by the phone - command in the configuration file. The argument to this command is - an AT command for a Hayes compatible modem. - - The accuracy produced by this driver should be in the range of a - millisecond or two, but may need correction due to the delay - characteristics of the individual modem involved. For undetermined - reasons, some modems work with the ACTS echo-delay measurement - scheme and some don't. This driver tries to do the best it can with - what it gets. Initial experiments with a Practical Peripherals - 9600SA modem here in Delaware suggest an accuracy of a millisecond - or two can be achieved without the scheme by using a fudge time1 - value of 65.0 ms. In either case, the dispersion for a single call - involving ten samples is about 1.3 ms. - - The driver can operate in either of three modes, as determined by - the mode parameter in the server configuration command. In mode 0 - (automatic) the driver operates continuously at intervals depending - on the prediction error, as measured by the driver, usually in the - order of several hours. In mode 1 (backup) the driver is enabled in - automatic mode only when no other source of synchronization is - available and when more than MAXOUTAGE (3600 s) have elapsed since - last synchronized by other sources. In mode 2 (manual) the driver - operates only when enabled using a fudge flags switch, as described - below. - - For reliable call management, this driver requires a 1200-bps modem - with a Hayes-compatible command set and control over the modem data - terminal ready (DTR) control line. Present restrictions require the - use of a POSIX-compatible programming interface, although other - interfaces may work as well. The ACTS telephone number and modem - setup string are hard-coded in the driver and may require changes - for nonstandard modems or special circumstances. - - Fudge Factors - - Ordinarily, the propagation time correction is computed - automatically by ACTS and the driver. When this is not possible or - erratic due to individual modem characteristics, the fudge flag2 - switch should be set to disable the ACTS echo-delay scheme. In any - case, the fudge time1 parameter can be used to adjust the - propagation delay as required. - - The ACTS call interval is determined in one of three ways. In - manual mode a call is initiated by setting fudge flag1 using - xntpdc, either manually or via a cron job. In automatic mode this - flag is set by the peer timer, which is controlled by the sys_poll - variable in response to measured errors. In backup mode the driver - is ordinarily asleep, but awakes (in automatic mode) if all other - synchronization sources are lost. In either automatic or backup - modes, the call interval increases as long as the measured errors - do not exceed the value of the fudge time2 parameter. - - When the fudge flag1 is set, the ACTS calling program is activated. - This program dials each number listed in the phones command of the - configuration file in turn. If a call attempt fails, the next - number in the list is dialed. The fudge flag1 and counter are reset - and the calling program terminated if (a) a valid clock update has - been determined, (b) no more numbers remain in the list, (c) a - device fault or timeout occurs, or (d) fudge flag1 is reset - manually using xntpdc. - - The NIST timecode message is transmitted at 1200 bps in the - following format (see the driver source for more information): - - jjjjj yy-mm-dd hh:mm:ss tt l uuu mmmmm UTC(NIST) * - - jjjjj = modified Julian day - yy-mm-dd = year, month, day - hh:mm:ss = hours, minutes, seconds - tt = DST indicator (see driver listing) - l = leap-second warning (see driver listing) - uuu = DUT1 correction (see driver listing) - mmmmm = modem calibration (see driver listing) - on-time = '*' - - The timecode message is transmitted continuously after a signon - banner, which this driver ignores. The driver also ignores all but - the yy-mm-dd, hh:mm:ss and on-time character '*' fields, although - it checks the format of all fields of the message. A timestamp is - captured at the '*' character, as required by the ACTS - specification, and used as the reference time of the timecode. If a - message with an on-time character of '#' is received, the driver - updates the propagation delay. The driver disconnects when (a) ten - valid messages have been received, (b) no message has been received - for 15 s, (c) an on-time character of '#' is received. These - messages are processed by a trimmed-mean filter to reduce timing - noise and then by the usual NTP algorithms to develop the clock - correction. - - The behavior of the clock selection algorithm is modified when this - driver is in use. The algorithm is designed so that this driver - will never be selected unless no other discipline source is - available. This can be overridden with the prefer keyword of the - server configuration command, in which case only this driver will - be selected for synchronization and all other discipline sources - will be ignored. Ordinarily, the prefer keyword would be used only - in automatic mode ehen primary time is to be obtained via ACTS and - backup NTP peers used only when ACTS fails. - - Call Management - - Since ACTS will be a toll call in most areas of the country, it is - necessary to carefully manage the calling interval. The ACTS call - program is initiated by setting fudge flag1. This flag can be set - manually using xntpdc, by a cron job that calls xntpdc, or - automatically by the driver itself. The fudge flag1 is reset when - the program terminates after a time determination is comlete or - when no more numbers remain in the alternate path list, a device - fault or timeout has occured, or the fudge flag1 has been reset - using xntpdc. - - In automatic and backup modes, the driver determines the call - interval using a procedure depending on the measured prediction - error and the fudge time2 parameter. If the error exceeds time2 for - a number of times depending on the current interval, the interval - is decreased, but not less than about 1000 s. If the error is less - than time2 for some number of times, the interval is increased, but - not more than about 18 h. With the default value of zero for fudge - time2, the interval will increase from 1000 s to the 4000-8000-s - range, in which the expected accuracy should be in the 1-2-ms - range. Setting fudge time2 to a large value, like 0.1 s, may result - in errors of that order, but increase the call interval to the - maximum. The exact value for each configuration will depend on the - modem and operating system involved, so some experimentation may be - necessary. - - Manual call attempts can be made at any time by setting fudge flag1 - using xntpdc. For example, the xntpdc command - - fudge 127.127.18.1 flags 1 - - will ask for a key identifier and password and, if authenticated by - the server, will set flag1. There may be a short delay until the - expiration of the current poll timeout. - - The flag1 can be set from a cron job in the following way. - Construct a file with contents - - keyid 11 - passwd dialup - fudge 127.127.18.1 flags 1 - quit - - Then, run the following program at specified times as required. - - /usr/local/bin/xntpdc <file - -Type 19: Heath WWV/WWVH Receiver - - This driver supports the Heath GC-1000 Most Accurate Clock, with - RS232C Output Accessory. This is a WWV/WWVH receiver somewhat less - robust than other supported receivers. Its claimed accuracy is 100 - ms when actually synchronized to the broadcast signal, but this - doesn't happen even most of the time, due to propagation - conditions, ambient noise sources, etc. When not synchronized, the - accuracy is at the whim of the internal clock oscillator, which can - wander into the sunset without warning. Since the indicated - precision is 100 ms, expect a host synchronized only to this thing - to wander to and fro, occasionally being rudely stepped when the - offset exceeds the default CLOCK_MAX of 128 ms. - - The internal DIPswitches should be set to operate at 1200 baud in - MANUAL mode and the current year. The external DIPswitches should - be set to GMT and 24-hour format. It is very important that the - year be set correctly in the DIPswitches. Otherwise, the day of - year will be incorrect after 28 April of a normal or leap year. - - In MANUAL mode the clock responds to a rising edge of the request - to send (RTS) modem control line by sending the timecode. - Therefore, it is necessary that the operating system implement the - TIOCMBIC and TIOCMBIS ioctl system calls and TIOCM_RTS control bit. - Present restrictions require the use of a POSIX-compatible - programming interface, although other interfaces may work as well. - - The clock message consists of 23 ASCII printing characters in the - following format: - - hh:mm:ss.f dd/mm/yr<cr> - - hh:mm:ss.f = hours, minutes, seconds - f = deciseconds ('?' when out of spec) - dd/mm/yr = day, month, year - - The alarm condition is indicated by '?', rather than a digit, at A. - Note that 0?:??:??.? is displayed before synchronization is first - established and hh:mm:ss.? once synchronization is established and - then lost again for about a day. - - Fudge Factors - - There are no special fudge factors other than the generic. A fudge - time1 value of .07 s appears to center the clock offset residuals. - -Type 20: Generic NMEA GPS Receiver - - Information not available. - -Type 21: Motorola Six Gun GPS Receiver - - Information not available. - -Type 22: PPS Clock Discipline - - This driver furnishes an interface for pulse-per-second (PPS) - signals produced by a cesium clock, timing receiver or related - equipment. It can be used to remove accumulated jitter and retime a - secondary server when synchronized to a primary server over a - congested, wide-area network and before redistributing the time to - local clients. Note that this driver does not control the system - clock if the kernel modifications described in the README.kernel - file have been installed, but it can be useful as a monitoring - tool. - - In order for this driver to work, the local clock must be set to - within +-500 ms by another means, such as a radio clock or NTP - itself. The 1-pps signal is connected via a serial port and gadget - box consisting of a one-shot and RS232 level converter. When - operated at 38.4 kbps with a SPARCstation IPC, this arrangement has - a worst-case jitter less than 26 us. - - There are three ways in which this driver can be used. The first - way uses the LDISC_PPS line discipline and works only for the - baseboard serial ports of the Sun SPARCstation. The PPS signal is - connected via a gadget box to the carrier detect (CD) line of a - serial port and flag3 of the driver configured for that port is - set. This causes the ppsclock streams module to be configured for - that port and capture a timestamp at the on-time transition of the - PPS signal. This driver then reads the timestamp directly by a - designated ioctl() system call. This provides the most accurate - time and least jitter of any other scheme. There is no need to - configure a dedicated device for this purpose, which ordinarily is - the device used for the associated radio clock. - - The second way uses the LDISC_CLKPPS line discipline and works for - any architecture supporting a serial port. If after a few seconds - this driver finds no ppsclock module configured, it attempts to - open a serial port device /dev/pps%d, where %d is the unit number, - and assign the LDISC_CLKPPS line discipline to it. If the line - discipline fails, no harm is done except the accuracy is reduced - somewhat. The pulse generator in the gadget box is adjusted to - produce a start bit of length 26 us at 38400 bps (or 104 us at 9600 - bps). Used with the LDISC_CLKPPS line discipline, this produces an - ASCII DEL character ('\377') followed by a timestamp at each - seconds epoch. - - The third way involves an auxiliary radio clock driver which calls - the PPS driver with a timestamp captured by that driver. This use - is documented in the source code for the driver(s) involved. - - Fudge Factors - - There are no special fudge factors other than the generic and those - explicitly defined above. The fudge time1 parameter can be used to - compensate for miscellaneous UART and OS delays. Allow about 247 us - for uart delays at 38400 bps and about 1 ms for SunOS streams - nonsense. - -Appendix B. Mitigation Rules - -In order to provide robust backup sources, stratum-1 peers are usually -operated in a diversity configuration, in which the local server -operates with a number of remote peers in addition with one or more -radio clocks operating also as local peers. In these configurations the -suite of algorithms used in NTP to refine the data from each peer -separately and to select and weight the data from a number of peers can -be used with the entire ensemble of remote peers and local radios. -However, Because of small but significant systematic time offsets -between the peers, it is in general not possible to achieve the lowest -jitter and highest stability in these configurations. In addition, there -are a number of special configurations involving auxiliary radio clock -outputs, telephone backup services and other special cases, so that a -set of mitigation rules becomes necessary. - -The mitigation rules are based on a set of special characteristics of -the various reference clock drivers configured on the server. For -instance, it is possible to designate a peer as "preferred," in which -case, all other things being equal, this peer will be selected for -synchronization over all other eligible candidates in the clock -selection procedures. The precise characterization of the prefer peer is -described below. In addition, when a pulse-per-second (PPS) signal is -connected via the PPS Clock Discipline Driver (type 22), the -corresponding peer is called the PPS peer. The manner in which this peer -operates is described below. When the Undisciplined Local Clock Driver -(type 1) is configured in the server, this becomes the local-clock peer. -When the Automated Computer Time Service Driver (type 18) is configured -in the server, this becomes the ACTS peer. Both the local-clock and ACTS -peers operates in the manner described in Appendix A. Finally, where -support is available, the PPS signal may be processed directly by the -kernel. In the following this will be called the kernel discipline. - -The mitigation rules apply in the clock selection procedures following -the sanity checks, intersection algorithm and clustering algorithm. The -survivors at this point represent the subset of all peers which can -provide the most accurate, stable time. In the general case, with no -designated prefer peer, PPS peer or local-clock peer, the mitigation -rules require all survivors be averaged according to a weight depending -on the reciprocal of the dispersion, as provided in the NTP -specification. - -The mitigation rules establish the choice of system peer, which -determine the stratum, reference identifier and several other system -variables which are visible to clients of the local server. In addition, -they establish which source or combination of sources control the local -clock. In detail, these rules operate as follows: - -1. If there is a prefer peer and it is the local-clock peer or the - ACTS peer; or, if there is a prefer peer and the kernel discipline - is active, choose the prefer peer as the system peer. - -2. If the above is not the case and there is a PPS peer, then choose - it as the system peer and its offset as the system clock offset. - -3. If the above is not the case and there is a prefer peer (not the - local-clock or ACTS peer in this case), then choose it as the - system peer and its offset as the system clock offset. - -4. If the above is not the case and the peer previously chosen as the - system peer is in the surviving population, then choose it as the - system peer and average its offset along with the other survivors - to determine the system clock offset. This behavior is designed to - avoid excess jitter due to "clockhopping," when switching the - system peer would not materially improve the time accuracy. - -5. If the above is not the case, then choose the first candidate in - the list of survivors ranked in order of synchronization distance - and average its offset along with the other survivors to determine - the system clock offset. This is the default case and the only case - considered in the current NTP specification. - -The specific interpretation of the prefer peer and PPS peer require some -explanation, which is given in following sections. - -B.1. Using the prefer Keyword - -For the reasons stated previously, a scheme has been implemented in NTP -to provide an intelligent mitigation between various classes of peers, -one designed to provide the best quality time without compromising the -normal operation of the NTP algorithms. This scheme in its present form -is not an integral component of the NTP specification. but is likely to -be included in future versions of the specification. The scheme is based -on the "preferred peer," which is specified by including the prefer -keyword with the associated server or peer command in the configuration -file. This keyword can be used with any peer or server, but is most -commonly used with a radio clock server. - -The prefer scheme works on the set of peers that have survived the -sanity and intersection algorithms of the clock select procedures. -Ordinarily, the members of this set can be considered truechimers and -any one of them could in principle provide correct time; however, due to -various error contributions, not all can provide the most stable time. -The job of the clustering algorithm, which is invoked at this point, is -to select the best subset of the survivors providing the least variance -in the combined ensemble compared to the variance in each member of the -subset. The detailed operation of the clustering algorithm, which are -given in the specification, are not important here, other than to point -out it operates in rounds, where a survivor, presumably the worst of the -lot, is discarded in each round until one of several termination -conditions is met. - -In the prefer scheme the clustering algorithm is modified so that the -prefer peer is never discarded; on the contrary, its potential removal -becomes a termination condition. If the original algorithm were about to -toss out the prefer peer, the algorithm terminates right there. The -prefer peer can still be discarded by the sanity and intersection -algorithms, of course, but it will always survive the clustering -algorithm. A preferred peer retains that designation as long as it -survives the intersection algorithm. If for some reason the prefer peer -fails to survive the intersection algorithm, either because it was -declared a falseticker or became unreachable, it loses that designation -and the clock selection remitigates as described above. - -Along with this behavior, the clock select procedures are modified so -that the combining algorithm is not used when a prefer (or PPS) peer is -present. Instead, the offset of the prefer (or PPS) peer is used -exclusively as the synchronization source. In the usual case involving a -radio clock and a flock of remote stratum-1 peers, and with the radio -clock designated a prefer peer, the result is that the high quality -radio time disciplines the server clock as long as the radio itself -remains operational and with valid time, as determined from the remote -peers, sanity algorithm and intersection algorithm. - -While the model does not forbid it, it does not seem useful to designate -more than one peer as preferred, since the additional complexities to -mitigate among them do not seem justified from on the air experience. -Note that the prefer peer interacts with the PPS peer discussed in -Appendix C. It also interacts with the Undisciplined Local Clock Driver -(type 1), as described in Appendix A. See the main text for the -mitigation rules applying to the general case. - -B.2. Using the Pulse-per-Second (PPS) Signal - -Most radio clocks are connected using a serial port operating at speeds -of 9600 bps or lower. The accuracy using typical timecode formats, where -the on-time epoch is indicated by a designated ASCII character, like -carriage-return <cr>, is limited to a millisecond at best and a few -milliseconds in typical cases. However, some radios produce a precision -pulse-per-second (PPS) signal which can be used to improve the accuracy -in typical workstation servers to the order of a few tens of -microseconds. The details of how this can be accomplished are discussed -in the README.magic file; the following discusses how this signal is -implemented and configured in a typical working server. - -First, it should be pointed out that the PPS signal is inherently -ambiguous, in that it provides a precise seconds epoch, but does not -provide a way to number the seconds. In principle and most commonly, -another source of synchronization, either the timecode from an -associated radio clock, or even a set of remote peers, is available to -perform that function. In all cases a specific, configured peer or -server must be designated as associated with the PPS signal. This is -done by including the prefer keyword with the associated server or peer -command in the configuration file. This PPS signal can be associated in -this way any peer or server, but is most commonly used with the radio -clock generating the PPS signal. - -The PPS signal is processed by a special PPS Clock Discipline Driver -(type 22) described in Appendix A. That description specifies the -hardware configurations in which this signal can be connected to the -server. This driver replaces the former scheme based on conditional -compilation and the PPS, CLK and PPSCLK compile-time switches. -Regardless of method, the driver, like all other drivers, is mitigated -in the manner described for the prefer peer in Appendix B. However, in -the case of the PPS peer, the behavior is slightly more complex. - -First, in order for the PPS peer to be considered at all, its associated -prefer peer must have survived the sanity and intersection algorithms -and have been designated the prefer peer. This insures that the radio -clock hardware is operating correctly and that, presumably, the PPS -signal is operating correctly as well. Second, the absolute time offset -from that peer must be less than CLOCK_MAX, the gradual-adjustment -range, which is ordinarily set at 128 ms, or well within the +-0.5-s -unambiguous range of the PPS signal itself. Finally, the time offsets -generated by the PPS peer are propagated via the clock filter to the -clock selection procedures just like any other peer. Should these pass -the sanity and intersection algorithms, they will show up along with the -offsets of the prefer peer itself. Note that, unlike the prefer peer, -the PPS peer samples are not protected from discard by the clustering -algorithm. These complicated procedures insure that the PPS offsets -developed in this way are the most accurate, reliable available for -synchronization. - -A PPS peer retains that designation as long as it survives the -intersection algorithm; however, like any other clock driver, it runs a -reachability algortihm on the PPS signal itself. If for some reason the -signal fails or displays gross errors, the PPS peer will either become -unreachable or stray out of the survivor population. In this case the -clock selection remitigates as described above. - -Finally, the mitigation procedures described above for the prefer peer -are modified so that, if the PPS peer survives the clustering algorithm, -its offset is mitigated over the prefer peer offset; in other words in -case of ties, the PPS offset wins. See the main text for the mitigation -rules applying to the general case. - -B.3. Using the Kernel Discipline - -Code to implement the kernel discipline is a special feature that can be -incorporated in the kernel of some workstations as described in the -README.kernel file. The discipline provides for the control of the local -clock oscillator time and/or frequency by means of an external PPS -signal interfaced via a modem control lead. As the PPS signal is derived -from external equipment, cables, etc., which sometimes fail, a good deal -of error checking is done in the kernel to detect signal failure and -excessive noise. - -In order to operate, the kernel discipline must be enabled and the -signal must be present and within nominal jitter and wander error -tolerances. In the NTP daemon the kernel is enabled only when the prefer -peer is among the survivors of the clustering algorithm, as described -above. Then, the PPS peer is designated the prefer peer as long as the -PPS signal is present and operating within tolerances. Under these -conditions the kernel disregards updates produced by the NTP daemon and -uses its internal PPS source instead. The kernel maintains a watchdog -timer for the PPS signal; if the signal has not been heard or is out of -tolerance for more than some interval, currently two minutes, the kernel -discipline is declared inoperable and operation continues as if it were -not present. -Appendix C. NTP Local Clock Discipline - -Implementation of the ACTS driver caused somewhat of a shakeup in the -NTP local clock model and implementation. The model described in the -specification RFC-1305 is based on a phase-lock loop (PLL) design, which -is optimum or near optimum for the update intervals used for NTP peers -and radio clocks, ordinarily in the range 64-1024 s. However, the ACTS -driver must operate with update intervals in the range well above 1024 -s, where the performance of the PLL model deteriorates. As suggested by -Judah Levine of NIST and used in his "lockclock" algorithm, a hybrid -frequency-lock loop (FLL) gives better performance at the longer update -intervals up to a maximum depending on the acceptable error bound. - -In a series of experiments and simulations, it was verified that the PLL -model provides better performance in the regime less than about 1000 s, -while the FLL model provides better performance above that. The -parameters of each model were optimized by simulation for the lowest -time and frequency error using data collected on an undisciplined -computer clock oscillator over a period of about two weeks. The PLL/FLL -hybrid loop has been implemented in NTP, along with certain other -refinements described below. While it was designed primarily with ACTS -in mind, it can be used with any NTP peer or radio clock, should that -prove useful. - -To take advantage of this feature for other than the ACTS driver, where -it is automatic, note that the default minimum poll interval is 64 s and -default maximum poll interval 1024 s (for the ACTS driver the default -minimum is 1024 s and default maximum 16384 s). However, using the -minpoll and/or maxpoll parameters of the server or peer commands in the -configuration file, it is possible to set the minimum poll interval as -low as 16 s and the maximum poll interval as high as 16384 s. Poll -intervals less than 64 s are useful if an exceptionally quick lock is -required, like in real-time or portable systems. Poll intervals above -1024 s, other than ACTS, may be useful to reduce traffic in some -situations, such as when charges are made on a per-packet basis. - -Another modification to the stock NTP local clock discipline is to avoid -errors due to old data. From a study of the stability characteristics of -typical computer clock oscillators using both experiment and simulation, -it was determined that data used to discipline the PLL are not generally -useful if older than about 1000 s. This corresponds roughly to the knee -in the Allan variance characteristic measured for a typical workstation -oscillator. The NTP clock filter algorithm was modified to adjust the -effective length of the shift register so that samples older than about -1000 s are not used to determine the filtered offset, delay and -dispersion values. This design has the useful byproduct that the time to -acquire lock when first coming up and to declare unreachability is -independent of the poll interval. - -A problem which has recurred on every occasion a leap second has been -inserted in the UTC timescale is that not all radio clocks detect and -implement the leap event. As a result, some radios sail right through -the leap, become confused for periods up to 15 minutes, then reacquire -lock. In order to cope with this, as well as other occasions where -atypically large offsets occur, the NTP clock discipline has been -modified to disregard offsets over 128 ms, unless (a) first coming up, -(b) first returning to service after a period when unsynchronized, or -(c) an interval of about 15 minutes has elapsed since the last update -less than 128 ms was received. In addition, the discipline has been -modified so that, if the first offset received after coming up is less -than 128 ms, the local clock is immediately reset to that offset without -affecting the PLL variables. - -It has been the experience of some users that, when first installed in a -system, the NTP clock discipline fails to reliably lock to other peers -and servers as configured. The indications are that the daemon locks for -some period of time, but is unable to stabilize the frequency estimate. -As the result, the time offsets eventually climb above 128 ms and the -discipline unlocks again. After the 15-minute timeout, the daemon locks -again and the cycle repeats. The problem here is that the intrinsic -frequency error of the local clock exceeds the design capture range of -the PLL, 100 ppm. This particular limit was selected as a compromise -between useful maximum error indications and the tolerances found in -typical computer clock oscillators. - -In spite of the tolerance assumed in the NTP specification of 100 ppm, -the NTP daemon for Unix can operate with an intrinsic frequency error of -over 380 ppm, depending on the values of tick and tickadj selected by -the tickadj program. However, with errors that large, the PLL will not -reliably lock, and the behavior noted above can occur. Formerly, the -only remedial in cases where this happens waas a somewhat painful manual -process where the nominal oscillator frequency is measured by some other -means, such as eyeball-and-wristwatch, and a specific drift file -(ntp.drift) crafted. - -In order to avoid the above problem, the NTP clock discipline has been -modified to measure the frequency during periods when not locked to -another server or radio clock. Such periods occur when the time offset -wanders through and beyond the 128-ms window as described above. When -synchronization is reestablished, the working frequency used by NTP is -initialized with the measured value. Since a precise frequency -determination is not always possible under these chaotic conditions, it -may take more than one cycle of this type to get the residual error -below 100 ppm and reliable lock established. - -David L. Mills <mills@udel.edu> -Electrical Engineering Department -University of Delaware -Newark, DE 19716 -302 831 8247 fax 302 831 4316 - -3 July 1994 diff --git a/usr.sbin/xntpd/doc/UofT b/usr.sbin/xntpd/doc/UofT deleted file mode 100644 index 54420d5..0000000 --- a/usr.sbin/xntpd/doc/UofT +++ /dev/null @@ -1,146 +0,0 @@ -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/acts.c b/usr.sbin/xntpd/doc/acts.c deleted file mode 100644 index 7d3733b..0000000 --- a/usr.sbin/xntpd/doc/acts.c +++ /dev/null @@ -1,878 +0,0 @@ -/*
- * refclock_acts - clock driver for the NIST Automated Computer Time
- * Service aka Amalgamated Containerized Trash Service (ACTS)
- */
-#if defined(REFCLOCK) && defined(ACTS)
-
-#include <stdio.h>
-#include <ctype.h>
-#include <sys/time.h>
-
-#include "ntpd.h"
-#include "ntp_io.h"
-#include "ntp_unixtime.h"
-#include "ntp_refclock.h"
-#include "ntp_stdlib.h"
-
-/*
- * This driver supports the NIST Automated Computer Time Service (ACTS).
- * It periodically dials a prespecified telephone number, receives the
- * NIST timecode data and calculates the local clock correction. It is
- * designed primarily for use as a backup when neither a radio clock nor
- * connectivity to Internet time servers is available. For the best
- * accuracy, the individual telephone line/modem delay needs to be
- * calibrated using outside sources.
- *
- * The ACTS is located at NIST Boulder, CO, telephone 303 494 4774. A
- * toll call from a residence telephone in Newark, DE, costs between 14
- * and 27 cents, depending on time of day, and from a campus telephone
- * between 3 and 4 cents, although it is not clear what carrier and time
- * of day discounts apply in this case. The modem dial string will
- * differ depending on local telephone configuration, etc., and is
- * specified by the phone command in the configuration file. The
- * argument to this command is an AT command for a Hayes compatible
- * modem.
- *
- * The accuracy produced by this driver should be in the range of a
- * millisecond or two, but may need correction due to the delay
- * characteristics of the individual modem involved. For undetermined
- * reasons, some modems work with the ACTS echo-delay measurement scheme
- * and some don't. This driver tries to do the best it can with what it
- * gets. Initial experiments with a Practical Peripherals 9600SA modem
- * here in Delaware suggest an accuracy of a millisecond or two can be
- * achieved without the scheme by using a fudge time1 value of 65.0 ms.
- * In either case, the dispersion for a single call involving ten
- * samples is about 1.3 ms.
- *
- * The driver can operate in either of two modes, as determined by the
- * mode parameter in the server configuration command. In mode 0 the
- * driver operates continuously at intervals determined by the fudge
- * time1 parameter, as described above. In mode 1 the driver is enabled
- * only when no other sources of synchronization are available and when
- * we have gone more than MAXOUTAGE (3600 s) since last synchronized by
- * other sources of synchronization.
- *
- * For reliable call management, this driver requires a 1200-bps modem
- * with a Hayes-compatible command set and control over the modem data
- * terminal ready (DTR) control line. Present restrictions require the
- * use of a POSIX-compatible programming interface, although other
- * interfaces may work as well. The modem setup string is hard-coded in
- * the driver and may require changes for nonstandard modems or special
- * circumstances.
- *
- * Further information can be found in the README.refclock file in the
- * xntp3 distribution.
- *
- * Fudge Factors
- *
- * Ordinarily, the propagation time correction is computed automatically
- * by ACTS and the driver. When this is not possible or erratic due to
- * individual modem characteristics, the fudge flag2 switch should be
- * set to disable the ACTS echo-delay scheme. In any case, the fudge
- * time1 parameter can be used to adjust the propagation delay as
- * required.
- *
- * The ACTS call interval is determined in one of three ways. In MANUAL
- * mode a call is initiated by setting fudge flag1 using xntpdc, either
- * manually or via a cron job. In AUTO mode this flag is set by the peer
- * timer, which is controlled by the sys_poll variable in response to
- * measured errors. In BACKUP mode the driver is ordinarily asleep, but
- * awakes (in AUTO mode) if all other synchronization sources are lost.
- * In either AUTO or BACKUP modes, the call interval increases as long
- * as the measured errors do not exceed the value of the fudge time2
- * parameter.
- *
- * When the fudge flag1 is set, the ACTS calling program is activated.
- * This program dials each number listed in the phones command of the
- * configuration file in turn. If a call attempt fails, the next number
- * in the list is dialed. The fudge flag1 and counter are reset and the
- * calling program terminated if (a) a valid clock update has been
- * determined, (b) no more numbers remain in the list, (c) a device
- * fault or timeout occurs or (d) fudge flag1 is reset manually using
- * xntpdc.
- */
-
-/*
- * DESCRIPTION OF THE AUTOMATED COMPUTER TELEPHONE SERVICE (ACTS)
- * (reformatted from ACTS on-line computer help information)
- *
- * The following is transmitted (at 1200 baud) following completion of
- * the telephone connection.
- *
- * National Institute of Standards and Technology
- * Telephone Time Service, Generator 3B
- * Enter question mark "?" for HELP
- * D L D
- * MJD YR MO DA H M S ST S UT1 msADV <OTM>
- * 47999 90-04-18 21:39:15 50 0 +.1 045.0 UTC(NIST) *
- * 47999 90-04-18 21:39:16 50 0 +.1 045.0 UTC(NIST) *
- * 47999 90-04-18 21:39:17 50 0 +.1 045.0 UTC(NIST) *
- * 47999 90-04-18 21:39:18 50 0 +.1 045.0 UTC(NIST) *
- * 47999 90-04-18 21:39:19 50 0 +.1 037.6 UTC(NIST) #
- * 47999 90-04-18 21:39:20 50 0 +.1 037.6 UTC(NIST) #
- * etc..etc...etc.......
- *
- * UTC = Universal Time Coordinated, the official world time referred to
- * the zero meridian.
- *
- * DST Daylight savings time characters, valid for the continental
- * U.S., are set as follows:
- *
- * 00 We are on standard time (ST).
- * 01-49 Now on DST, go to ST when your local time is 2:00 am and
- * the count is 01. The count is decremented daily at 00
- * (UTC).
- * 50 We are on DST.
- * 51-99 Now on ST, go to DST when your local time is 2:00 am and
- * the count is 51. The count is decremented daily at 00
- * (UTC).
- *
- * The two DST characters provide up to 48 days advance notice of a
- * change in time. The count remains at 00 or 50 at other times.
- *
- * LS Leap second flag is set to "1" to indicate that a leap second is
- * to be added as 23:59:60 (UTC) on the last day of the current UTC
- * month. The LS flag will be reset to "0" starting with 23:59:60
- * (UTC). The flag will remain on for the entire month before the
- * second is added. Leap seconds are added as needed at the end of
- * any month. Usually June and/or December are chosen.
- *
- * The leap second flag will be set to a "2" to indicate that a
- * leap second is to be deleted at 23:59:58--00:00:00 on the last
- * day of the current month. (This latter provision is included per
- * international recommendation, however it is not likely to be
- * required in the near future.)
- *
- * DUT1 Approximate difference between earth rotation time (UT1) and
- * UTC, in steps of 0.1 second: DUT1 = UT1 - UTC.
- *
- * MJD Modified Julian Date, often used to tag certain scientific data.
- *
- * The full time format is sent at 1200 baud, 8 bit, 1 stop, no parity.
- * The format at 300 Baud is also 8 bit, 1 stop, no parity. At 300 Baud
- * the MJD and DUT1 values are deleted and the time is transmitted only
- * on even seconds.
- *
- * Maximum on line time will be 56 seconds. If all lines are busy at any
- * time, the oldest call will be terminated if it has been on line more
- * than 28 seconds, otherwise, the call that first reaches 28 seconds
- * will be terminated.
- *
- * Current time is valid at the "on-time" marker (OTM), either "*" or
- * "#". The nominal on-time marker (*) will be transmitted 45 ms early
- * to account for the 8 ms required to send 1 character at 1200 Baud,
- * plus an additional 7 ms for delay from NIST to the user, and
- * approximately 30 ms "scrambler" delay inherent in 1200 Baud modems.
- * If the caller echoes all characters, NIST will measure the round trip
- * delay and advance the on-time marker so that the midpoint of the stop
- * bit arrives at the user on time. The amount of msADV will reflect the
- * actual required advance in milliseconds and the OTM will be a "#".
- *
- * (The NIST system requires 4 or 5 consecutive delay measurements which
- * are consistent before switching from "*" to "#". If the user has a
- * 1200 Baud modem with the same internal delay as that used by NIST,
- * then the "#" OTM should arrive at the user within +-2 ms of the
- * correct time.
- *
- * However, NIST has studied different brands of 1200 Baud modems and
- * found internal delays from 24 ms to 40 ms and offsets of the "#" OTM
- * of +-10 ms. For many computer users, +-10 ms accuracy should be more
- * than adequate since many computer internal clocks can only be set
- * with granularity of 20 to 50 ms. In any case, the repeatability of
- * the offset for the "#" OTM should be within +-2 ms, if the dial-up
- * path is reciprocal and the user doesn't change the brand or model of
- * modem used.
- *
- * This should be true even if the dial-up path on one day is a land-
- * line of less than 40 ms (one way) and on the next day is a satellite
- * link of 260 to 300 ms. In the rare event that the path is one way by
- * satellite and the other way by land line with a round trip
- * measurement in the range of 90 to 260 ms, the OTM will remain a "*"
- * indicating 45 ms advance.
- *
- * For user comments write:
- * NIST-ACTS
- * Time and Frequency Division
- * Mail Stop 847
- * 325 Broadway
- * Boulder, CO 80303
- *
- * Software for setting (PC)DOS compatable machines is available on a
- * 360-kbyte diskette for $35.00 from: NIST Office of Standard Reference
- * Materials B311-Chemistry Bldg, NIST, Gaithersburg, MD, 20899, (301)
- * 975-6776
- */
-
-/*
- * Interface definitions
- */
-#define DEVICE "/dev/acts%d" /* device name and unit */
-#define SPEED232 B1200 /* uart speed (1200 cowardly baud) */
-#define PRECISION (-10) /* precision assumed (about 1 ms) */
-#define REFID "ACTS" /* reference ID */
-#define DESCRIPTION "NIST Automated Computer Time Service" /* WRU */
-
-#define MODE_AUTO 0 /* automatic mode */
-#define MODE_BACKUP 1 /* backup mode */
-#define MODE_MANUAL 2 /* manual mode */
-
-#define NSAMPLES 3 /* stages of median filter */
-#define MSGCNT 10 /* we need this many ACTS messages */
-#define SMAX 80 /* max token string length */
-#define LENCODE 50 /* length of valid timecode string */
-#define ACTS_MINPOLL 10 /* log2 min poll interval (1024 s) */
-#define ACTS_MAXPOLL 14 /* log2 max poll interval (16384 s) */
-#define MAXOUTAGE 3600 /* max outage before ACTS kicks in (s) */
-
-/*
- * Modem control strings. These may have to be changed for some modems.
- *
- * AT command prefix
- * B1 initiate call negotiation using Bell 212A
- * &C1 enable carrier detect
- * &D2 hang up and return to command mode on DTR transition
- * E0 modem command echo disabled
- * l1 set modem speaker volume to low level
- * M1 speaker enabled untill carrier detect
- * Q0 return result codes
- * V1 return result codes as English words
- */
-#define MODEM_SETUP "ATB1&C1&D2E0L1M1Q0V1" /* modem setup */
-#define MODEM_HANGUP "ATH" /* modem disconnect */
-
-/*
- * Timeouts
- */
-#define IDLE 60 /* idle timeout (s) */
-#define WAIT 2 /* wait timeout (s) */
-#define ANSWER 30 /* answer timeout (s) */
-#define CONNECT 10 /* connect timeout (s) */
-#define TIMECODE 15 /* timecode timeout (s) */
-
-/*
- * Imported from ntp_timer module
- */
-extern u_long current_time; /* current time (s) */
-extern u_long last_time; /* last clock update time (s) */
-extern struct event timerqueue[]; /* inner space */
-
-/*
- * Imported from ntpd module
- */
-extern int debug; /* global debug flag */
-
-/*
- * Imported from ntp_config module
- */
-extern char sys_phone[][MAXDIAL]; /* modem dial strings */
-
-/*
- * Imported from ntp_proto module
- */
-extern struct peer *sys_peer; /* who is running the show */
-extern u_char sys_poll; /* log2 of system poll interval */
-extern struct peer *sys_peer; /* system peer structure pointer */
-
-/*
- * Tables to compute the ddd of year form icky dd/mm timecode. Viva la
- * leap.
- */
-static day1tab[] = {31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31};
-static day2tab[] = {31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31};
-
-/*
- * Unit control structure
- */
-struct actsunit {
- struct event timer; /* timeout timer */
- int pollcnt; /* poll message counter */
-
- int state; /* the first one was Delaware */
- int run; /* call program run switch */
- int msgcnt; /* count of ACTS messages received */
- long redial; /* interval to next automatic call */
- double msADV; /* millisecond advance of last message */
-};
-
-/*
- * Function prototypes
- */
-static int acts_start P((int, struct peer *));
-static void acts_shutdown P((int, struct peer *));
-static void acts_receive P((struct recvbuf *));
-static void acts_poll P((int, struct peer *));
-static void acts_timeout P((struct peer *));
-static void acts_disc P((struct peer *));
-static int acts_write P((struct peer *, char *));
-
-/*
- * Transfer vector
- */
-struct refclock refclock_acts = {
- acts_start, /* start up driver */
- acts_shutdown, /* shut down driver */
- acts_poll, /* transmit poll message */
- noentry, /* not used (old acts_control) */
- noentry, /* not used (old acts_init) */
- noentry, /* not used (old acts_buginfo) */
- NOFLAGS /* not used */
-};
-
-
-/*
- * acts_start - open the devices and initialize data for processing
- */
-static int
-acts_start(unit, peer)
- int unit;
- struct peer *peer;
-{
- register struct actsunit *up;
- struct refclockproc *pp;
- int fd;
- char device[20];
- int dtr = TIOCM_DTR;
-
- /*
- * Open serial port. Use ACTS line discipline, if available. It
- * pumps a timestamp into the data stream at every on-time
- * character '*' found. Note: the port must have modem control
- * or deep pockets for the phone bill. HP-UX 9.03 users should
- * have very deep pockets.
- */
- (void)sprintf(device, DEVICE, unit);
- if (!(fd = refclock_open(device, SPEED232, LDISC_ACTS)))
- return (0);
- if (ioctl(fd, TIOCMBIC, (char *)&dtr) < 0) {
- syslog(LOG_ERR, "clock %s ACTS no modem control",
- ntoa(&peer->srcadr));
- return (0);
- }
-
- /*
- * Allocate and initialize unit structure
- */
- if (!(up = (struct actsunit *)
- emalloc(sizeof(struct actsunit)))) {
- (void) close(fd);
- return (0);
- }
- memset((char *)up, 0, sizeof(struct actsunit));
- pp = peer->procptr;
- pp->io.clock_recv = acts_receive;
- pp->io.srcclock = (caddr_t)peer;
- pp->io.datalen = 0;
- pp->io.fd = fd;
- if (!io_addclock(&pp->io)) {
- (void) close(fd);
- free(up);
- return (0);
- }
- pp->unitptr = (caddr_t)up;
-
- /*
- * Initialize miscellaneous variables
- */
- peer->precision = PRECISION;
- pp->clockdesc = DESCRIPTION;
- memcpy((char *)&pp->refid, REFID, 4);
- peer->minpoll = ACTS_MINPOLL;
- peer->maxpoll = ACTS_MAXPOLL;
-
- /*
- * Initialize modem and kill DTR. We skedaddle if this comes
- * bum.
- */
- if (!acts_write(peer, MODEM_SETUP)) {
- (void) close(fd);
- free(up);
- return (0);
- }
-
- /*
- * Set up the driver timeout
- */
- up->timer.peer = (struct peer *)peer;
- up->timer.event_handler = acts_timeout;
- up->timer.event_time = current_time + WAIT;
- TIMER_INSERT(timerqueue, &up->timer);
- return (1);
-}
-
-
-/*
- * acts_shutdown - shut down the clock
- */
-static void
-acts_shutdown(unit, peer)
- int unit;
- struct peer *peer;
-{
- register struct actsunit *up;
- struct refclockproc *pp;
-
- pp = peer->procptr;
- up = (struct actsunit *)pp->unitptr;
- TIMER_DEQUEUE(&up->timer);
- io_closeclock(&pp->io);
- free(up);
-}
-
-
-/*
- * acts_receive - receive data from the serial interface
- */
-static void
-acts_receive(rbufp)
- struct recvbuf *rbufp;
-{
- register struct actsunit *up;
- struct refclockproc *pp;
- struct peer *peer;
- char str[SMAX];
- int i;
- l_fp tstmp;
- u_fp disp;
- char hangup = '%'; /* ACTS hangup */
- int day; /* day of the month */
- int month; /* month of the year */
- u_long mjd; /* Modified Julian Day */
- u_int dst; /* daylight/standard time indicator */
- u_int leap; /* leap-second indicator */
- double dut1; /* DUT adjustment */
- double msADV; /* ACTS transmit advance (ms) */
- char utc[10]; /* this is NIST and you're not */
- char flag; /* calibration flag */
-
- /*
- * Initialize pointers and read the timecode and timestamp. If
- * the OK modem status code, leave it where folks can find it.
- */
- peer = (struct peer *)rbufp->recv_srcclock;
- pp = peer->procptr;
- up = (struct actsunit *)pp->unitptr;
- pp->lencode = refclock_gtlin(rbufp, pp->lastcode, BMAX,
- &pp->lastrec);
- if (pp->lencode == 0) {
- if (strcmp(pp->lastcode, "OK") == 0)
- pp->lencode = 2;
- return;
- }
-#ifdef DEBUG
- if (debug)
- printf("acts: timecode %d %s\n", pp->lencode,
- pp->lastcode);
-#endif
-
- switch (up->state) {
-
- case 0:
-
- /*
- * State 0. We are not expecting anything. Probably
- * modem disconnect noise. Go back to sleep.
- */
- return;
-
- case 1:
-
- /*
- * State 1. We are waiting for the call to be answered.
- * All we care about here is CONNECT as the first token
- * in the string. If the modem signals BUSY, ERROR, NO
- * ANSWER, NO CARRIER or NO DIALTONE, we immediately
- * hang up the phone. If CONNECT doesn't happen after
- * ANSWER seconds, hang up the phone. If everything is
- * okay, start the connect timeout and slide into state
- * 2.
- */
- (void)strncpy(str, strtok(pp->lastcode, " "), SMAX);
- if (strcmp(str, "BUSY") == 0 || strcmp(str, "ERROR") ==
- 0 || strcmp(str, "NO") == 0) {
- TIMER_DEQUEUE(&up->timer);
- syslog(LOG_NOTICE,
- "clock %s ACTS modem status %s",
- ntoa(&peer->srcadr), pp->lastcode);
- acts_disc(peer);
- } else if (strcmp(str, "CONNECT") == 0) {
- TIMER_DEQUEUE(&up->timer);
- up->timer.event_time = current_time + CONNECT;
- TIMER_INSERT(timerqueue, &up->timer);
- up->msgcnt = 0;
- up->state++;
- }
- return;
-
- case 2:
-
- /*
- * State 2. The call has been answered and we are
- * waiting for the first ACTS message. If this doesn't
- * happen within the timecode timeout, hang up the
- * phone. We probably got a wrong number or ACTS is
- * down.
- */
- TIMER_DEQUEUE(&up->timer);
- up->timer.event_time = current_time + TIMECODE;
- TIMER_INSERT(timerqueue, &up->timer);
- up->state++;
- }
-
- /*
- * Real yucky things here. Ignore everything except timecode
- * messages, as determined by the message length. We told the
- * terminal routines to end the line with '*' and the line
- * discipline to strike a timestamp on that character. However,
- * when the ACTS echo-delay scheme works, the '*' eventually
- * becomes a '#'. In this case the message is ended by the <CR>
- * that comes about 200 ms after the '#' and the '#' cannot be
- * echoed at the proper time. But, this may not be a lose, since
- * we already have good data from prior messages and only need
- * the millisecond advance calculated by ACTS. So, if the
- * message is long enough and has an on-time character at the
- * right place, we consider the message (but not neccesarily the
- * timestmap) to be valid.
- */
- if (pp->lencode != LENCODE)
- return;
-
- /*
- * We apparently have a valid timecode message, so dismember it
- * with sscan(). This routine does a good job in spotting syntax
- * errors without becoming overly pedantic.
- *
- * D L D
- * MJD YR MO DA H M S ST S UT1 msADV OTM
- * 47222 88-03-02 21:39:15 83 0 +.3 045.0 UTC(NBS) *
- */
- if (sscanf(pp->lastcode,
- "%5ld %2d-%2d-%2d %2d:%2d:%2d %2d %1d %3lf %5lf %s %c",
- &mjd, &pp->year, &month, &day, &pp->hour, &pp->minute,
- &pp->second, &dst, &leap, &dut1, &msADV, utc, &flag) != 13) {
- refclock_report(peer, CEVNT_BADREPLY);
- return;
- }
-
- /*
- * Some modems can't be trusted (the Practical Peripherals
- * 9600SA comes to mind) and, even if they manage to unstick
- * ACTS, the millisecond advance is wrong, so we use CLK_FLAG2
- * to disable echoes, if neccessary.
- */
- if ((flag == '*' || flag == '#') && !(pp->sloppyclockflag &
- CLK_FLAG2))
- (void)write(pp->io.fd, &flag, 1);
-
- /*
- * Yes, I know this code incorrectly thinks that 2000 is a leap
- * year. The ACTS timecode format croaks then anyway. Life is
- * short. Would only the timecode mavens resist the urge to
- * express months of the year and days of the month in favor of
- * days of the year.
- */
- if (month < 1 || month > 12 || day < 1) {
- refclock_report(peer, CEVNT_BADTIME);
- return;
- }
- if (pp->year % 4) {
- if (day > day1tab[month - 1]) {
- refclock_report(peer, CEVNT_BADTIME);
- return;
- }
- for (i = 0; i < month - 1; i++)
- day += day1tab[i];
- } else {
- if (day > day2tab[month - 1]) {
- refclock_report(peer, CEVNT_BADTIME);
- return;
- }
- for (i = 0; i < month - 1; i++)
- day += day2tab[i];
- }
- pp->day = day;
- if (leap == 1)
- pp->leap = LEAP_ADDSECOND;
- else if (pp->leap == 2)
- pp->leap = LEAP_DELSECOND;
- else
- pp->leap = 0;
- pp->lasttime = current_time;
-
- /*
- * Colossal hack here. We process each sample in a trimmed-mean
- * filter and determine the reference clock offset and
- * dispersion. The fudge time1 value is added to each sample as
- * received. If we collect MSGCNT samples before the '#' on-time
- * character, we use the results of the filter as is. If the '#'
- * is found before that, the adjusted msADV is used to correct
- * the propagation delay.
- */
- up->msgcnt++;
- if (flag == '#') {
- L_CLR(&tstmp);
- TVUTOTSF((long)((msADV - up->msADV) * 1000.),
- tstmp.l_uf);
- L_ADD(&pp->offset, &tstmp);
- } else {
- up->msADV = msADV;
- if (!refclock_process(pp, up->msgcnt, up->msgcnt -
- up->msgcnt / 3)) {
- refclock_report(peer, CEVNT_BADTIME);
- return;
- } else if (up->msgcnt < MSGCNT)
- return;
- }
-
- /*
- * We have a filtered sample offset ready for peer processing.
- * We use lastrec as both the reference time and receive time in
- * order to avoid being cute, like setting the reference time
- * later than the receive time, which may cause a paranoid
- * protocol module to chuck out the data. Finaly, we unhook the
- * timeout, arm for the next call, fold the tent and go home.
- * The little dance with the '%' character is an undocumented
- * ACTS feature that hangs up the phone real quick without
- * waiting for carrier loss or long-space disconnect, but we do
- * these clumsy things anyway.
- */
- disp = LFPTOFP(&pp->fudgetime2);
- record_clock_stats(&peer->srcadr, pp->lastcode);
- refclock_receive(peer, &pp->offset, 0, pp->dispersion +
- (u_fp)disp, &pp->lastrec, &pp->lastrec, pp->leap);
- pp->sloppyclockflag &= ~CLK_FLAG1;
- up->pollcnt = 0;
- TIMER_DEQUEUE(&up->timer);
- (void)write(pp->io.fd, &hangup, 1);
- up->state = 0;
- acts_disc(peer);
-}
-
-
-/*
- * acts_poll - called by the transmit routine
- */
-static void
-acts_poll(unit, peer)
- int unit;
- struct peer *peer;
-{
- register struct actsunit *up;
- struct refclockproc *pp;
-
- /*
- * If the driver is running, we set the enable flag (fudge
- * flag1), which causes the driver timeout routine to initiate a
- * call to ACTS. If not, the enable flag can be set using
- * xntpdc. If this is the sustem peer, then follow the system
- * poll interval.
- */
- pp = peer->procptr;
- up = (struct actsunit *)pp->unitptr;
- if (up->run) {
- pp->sloppyclockflag |= CLK_FLAG1;
- if (peer == sys_peer)
- peer->hpoll = sys_poll;
- else
- peer->hpoll = peer->minpoll;
- }
-}
-
-
-/*
- * acts_timeout - called by the timer interrupt
- */
-static void
-acts_timeout(peer)
- struct peer *peer;
-{
- register struct actsunit *up;
- struct refclockproc *pp;
- int dtr = TIOCM_DTR;
-
- /*
- * If a timeout occurs in other than state 0, the call has
- * failed. If in state 0, we just see if there is other work to
- * do.
- */
- pp = peer->procptr;
- up = (struct actsunit *)pp->unitptr;
- if (up->state) {
- acts_disc(peer);
- return;
- }
- switch (peer->ttl) {
-
- /*
- * In manual mode the ACTS calling program is activated
- * by the xntpdc program using the enable flag (fudge
- * flag1), either manually or by a cron job.
- */
- case MODE_MANUAL:
- up->run = 0;
- break;
-
- /*
- * In automatic mode the ACTS calling program runs
- * continuously at intervals determined by the sys_poll
- * variable.
- */
- case MODE_AUTO:
- if (!up->run)
- pp->sloppyclockflag |= CLK_FLAG1;
- up->run = 1;
- break;
-
- /*
- * In backup mode the ACTS calling program is disabled,
- * unless no system peer has been selected for MAXOUTAGE
- * (3600 s). Once enabled, it runs until some other NTP
- * peer shows up.
- */
- case MODE_BACKUP:
- if (!up->run && sys_peer == 0) {
- if (current_time - last_time > MAXOUTAGE) {
- up->run = 1;
- peer->hpoll = peer->minpoll;
- syslog(LOG_NOTICE,
- "clock %s ACTS backup started ",
- ntoa(&peer->srcadr));
- }
- } else if (up->run && sys_peer->refclktype !=
- REFCLK_NIST_ACTS) {
- peer->hpoll = peer->minpoll;
- up->run = 0;
- syslog(LOG_NOTICE,
- "clock %s ACTS backup stopped",
- ntoa(&peer->srcadr));
- }
- break;
-
- default:
- syslog(LOG_NOTICE,
- "clock %s ACTS invalid mode", ntoa(&peer->srcadr));
-
- }
-
- /*
- * The fudge flag1 is used as an enable/disable; if set either
- * by the code or via xntpdc, the ACTS calling program is
- * started; if reset, the phones stop ringing.
- */
- if (!(pp->sloppyclockflag & CLK_FLAG1)) {
- up->pollcnt = 0;
- up->timer.event_time = current_time + IDLE;
- TIMER_INSERT(timerqueue, &up->timer);
- return;
- }
-
- /*
- * Initiate a call to the ACTS service. If we wind up here in
- * other than state 0, a successful call could not be completed
- * within minpoll seconds. We advance to the next modem dial
- * string. If none are left, we log a notice and clear the
- * enable flag. For future enhancement: call the site RP and
- * leave an obscene message in his voicemail.
- */
- if (sys_phone[up->pollcnt][0] == '\0') {
- refclock_report(peer, CEVNT_TIMEOUT);
- syslog(LOG_NOTICE,
- "clock %s ACTS calling program terminated",
- ntoa(&peer->srcadr));
- pp->sloppyclockflag &= ~CLK_FLAG1;
-#ifdef DEBUG
- if (debug)
- printf("acts: calling program terminated\n");
-#endif
- up->pollcnt = 0;
- up->timer.event_time = current_time + IDLE;
- TIMER_INSERT(timerqueue, &up->timer);
- return;
- }
-
- /*
- * Raise DTR, call ACTS and start the answer timeout. We think
- * it strange if the OK status has not been received from the
- * modem, but plow ahead anyway.
- */
- if (strcmp(pp->lastcode, "OK") != 0)
- syslog(LOG_NOTICE, "clock %s ACTS no modem status",
- ntoa(&peer->srcadr));
- (void)ioctl(pp->io.fd, TIOCMBIS, (char *)&dtr);
- (void)acts_write(peer, sys_phone[up->pollcnt]);
- syslog(LOG_NOTICE, "clock %s ACTS calling %s\n",
- ntoa(&peer->srcadr), sys_phone[up->pollcnt]);
- up->state = 1;
- up->pollcnt++;
- pp->polls++;
- up->timer.event_time = current_time + ANSWER;
- TIMER_INSERT(timerqueue, &up->timer);
-}
-
-
-/*
- * acts_disc - disconnect the call and wait for the ruckus to cool
- */
-static void
-acts_disc(peer)
- struct peer *peer;
-{
- register struct actsunit *up;
- struct refclockproc *pp;
- int dtr = TIOCM_DTR;
-
- /*
- * We should never get here other than in state 0, unless a call
- * has timed out. We drop DTR, which will reliably get the modem
- * off the air, even while ACTS is hammering away full tilt.
- */
- pp = peer->procptr;
- up = (struct actsunit *)pp->unitptr;
- (void)ioctl(pp->io.fd, TIOCMBIC, (char *)&dtr);
- if (up->state > 0) {
- up->state = 0;
- syslog(LOG_NOTICE, "clock %s ACTS call failed %d",
- ntoa(&peer->srcadr), up->state);
-#ifdef DEBUG
- if (debug)
- printf("acts: call failed %d\n", up->state);
-#endif
- }
- up->timer.event_time = current_time + WAIT;
- TIMER_INSERT(timerqueue, &up->timer);
-}
-
-
-/*
- * acts_write - write a message to the serial port
- */
-int
-acts_write(peer, str)
- struct peer *peer;
- char *str;
-{
- register struct actsunit *up;
- struct refclockproc *pp;
- int len;
- int code;
- char cr = '\r';
-
- /*
- * Not much to do here, other than send the message, handle
- * debug and report faults.
- */
- pp = peer->procptr;
- up = (struct actsunit *)pp->unitptr;
- len = strlen(str);
-#ifdef DEBUG
- if (debug)
- printf("acts: state %d send %d %s\n", up->state, len,
- str);
-#endif
- code = write(pp->io.fd, str, len) == len;
- code |= write(pp->io.fd, &cr, 1) == 1;
- if (!code)
- refclock_report(peer, CEVNT_FAULT);
- return (code);
-}
-
-#endif
diff --git a/usr.sbin/xntpd/doc/notes.txt b/usr.sbin/xntpd/doc/notes.txt deleted file mode 100644 index 1dd59f2..0000000 --- a/usr.sbin/xntpd/doc/notes.txt +++ /dev/null @@ -1,1258 +0,0 @@ - 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 slightly 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 deleted file mode 100644 index c927c0d..0000000 --- a/usr.sbin/xntpd/doc/ntpdate.8 +++ /dev/null @@ -1,147 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd December 21, 1993 -.Dt NTPDATE 8 -.Os -.Sh NAME -.Nm ntpdate -.Nd set the date and time via NTP -.Sh SYNOPSIS -.Nm -.Op Fl bdqsv -.Op Fl o Ar version -.Op Fl a Ar key# -.Op Fl e Ar authdelay -.Op Fl k Ar keyfile -.Op Fl p Ar samples -.Op Fl t Ar timeout -.Ar server ... -.Sh DESCRIPTION -.Nm 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, -.Nm -can be inserted in the -.Pa /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 -.Xr cron 8 . -Note that -.Nm Ns '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 -.Nm -in one of two ways. If -.Nm -determines your clock is off by more than 0.5 seconds it will simply -step the time by calling -.Xr 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 -.Xr adjtime 2 -with the offset. The latter technique is less disruptive and more -accurate when the offset is small, and works quite well when -.Nm -is run by -.Xr 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 -.Fl b -switch on the command line. The -.Fl s -switch tells -.Nm -to log its actions via the -.Xr syslog 3 -facility rather than to the standard output, a useful option when -running the program from -.Xr cron 8 . -.Pp -The -.Fl d -flag may be used to determine what -.Nm -will do without it actually doing it. Information useful for general -debugging will also be printed. The -.Fl q -flag is used to perform a simple query without binding a priviledged -UPD port. The -.Fl v -enables a few diagnostic messages. By default -.Nm -claims to be an NTP version 3 implementation in its outgoing packets. As -some older software will decline to respond to version 3 queries, the -.Fl o Ar version -switch can be used to force the program to poll as a version 2 or 1 -implementation instead. -.Pp -The number of samples -.Nm -acquires from each server can be set to between 1 and 8 inclusive -using the -.Fl p -switch. The default is 4. The time it will spend waiting for a -response can be set using the -.Fl 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 -.Nm Ntpdate -will authenticate its transactions if need be. The -.Fl a -switch specifies that all packets should be authenticated using the -key number indicated. The -.Fl k -switch allows the name of the file from which the keys may be read -to be modified from the default of -.Pa /etc/ntp.keys . -This file should be in the format described in -.Xr xntpd 8 . -The -.Fl e -option allows the specification of an authentication processing delay, -in seconds (see -.Xr xntpd 8 -for details). This number is usually small enough to be negligible for -.Nm Ns 's -purposes, though specifying a value may improve timekeeping on very slow -CPU's. -.Pp -.Nm Ntpdate -will decline to set the date if an NTP server daemon (e.g. -.Xr xntpd 8 ) -is running on the same host. When running -.Nm -on a regular basis from -.Xr 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 -.Bl -tag -width /etc/ntp.keys -compact -.It Pa /etc/ntp.keys -contains the encryption keys used by -.Nm Ns . -.El -.Sh SEE ALSO -.Xr xntpd 8 -.Sh HISTORY -Written by -.An 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 deleted file mode 100644 index 7d62428..0000000 --- a/usr.sbin/xntpd/doc/ntpq.8 +++ /dev/null @@ -1,480 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd December 21, 1993 -.Dt NTPQ 8 -.Os -.Sh NAME -.Nm ntpq -.Nd standard Network Time Protocol query program -.Sh SYNOPSIS -.Nm -.Op Fl inp -.Op Fl c Ar command -.Op Ar host ... -.Sh DESCRIPTION -.Nm 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. -.Nm 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 -.Nm -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 -.Ar localhost -by default. If no request options are given, -.Nm -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 -.Ar localhost -when no other host is specified. -.Nm Ntpq -will prompt for commands if the standard input is a terminal device. -.Pp -.Nm Ntpq -uses NTP mode 6 packets to communicate with the NTP server, and hence -can be used to query any compatible 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. -.Nm 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 -.Fl i -or -.Fl n -will cause the specified query (queries) to be sent to the indicated -host(s) immediately. Otherwise, -.Nm -will attempt to read interactive format commands from the standard -input. -The following options are available: -.Bl -tag -width indent -.It Fl c Ar command -The following argument is interpreted as an interactive format -.Ar command -and is added to the list of commands to be executed on the specified -host(s). Multiple -.Fl c -options may be given. -.It Fl i -Force -.Nm -to operate in interactive mode. Prompts will be written to the standard -output and commands read from the standard input. -.It Fl n -Output all host addresses in dotted\-quad numeric format rather than -converting to the canonical host names. -.It Fl p -Print a list of the peers known to the server as well as a summary of -their state. This is equivalent to the -.Em peers -interactive command. -.El -.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 -.Qq > , -followed by a file name, to the command line. -.Pp -A number of interactive format commands are executed entirely within the -.Nm -program itself and do not result in NTP mode 6 requests being sent to a -server. These are described following. -.Pp -.Bl -tag -width indent -.It ? Op Ar command_keyword -A -.Qq ? -by itself will print a list of all the command keywords -known to this incarnation of -.Nm Ns . -A -.Qq ? -followed by a command keyword will print function and -usage information about the command. This command is probably a better -source of information about -.Nm -than this manual page. -.It timeout Ar milliseconds -Specify a time out period for responses to server queries. The default -is about 5000 milliseconds. Note that since -.Nm -retries each query once after a time out the total waiting time for a -time out will be twice the time out value set. -.It delay Ar milliseconds -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. -.It host Ar hostname -Set the host to which future queries will be sent. -.Ar Hostname -may be either a host name or a numeric -address. -.It Xo poll -.Op Ar # -.Op Ar verbose -.Xc -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. -.It keyid Ar # -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. -.It passwd -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. -.It hostnames Ar yes | Ar no -If -.Ar yes -is specified, host names are printed in information -displays. If -.Ar no -is given, numeric addresses are printed -instead. The default is -.Ar yes -unless modified using the command line -.Fl n -switch. -.It raw -Cause all output from query commands is printed as received from the -remote server. The only formating/intepretation done on the data is to -transform non-ASCII data into a printable (but barely understandable) -form. -.It cooked -Cause output from query commands to be -.Qq cooked Ns . -Variables -which are recognized by the server will have their values reformatted -for human consumption. Variables which -.Nm -thinks should have a decodeable value but didn't are marked with a -trailing -.Qq ? Ns . -.It ntpversion Ar 1 | Ar 2 | Ar 3 -Set the NTP version number which -.Nm -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. -.It authenticate Ar yes | Ar no -Normally -.Nm -does not authenticate requests unless they are write requests. The -command -.Em authenticate yes -causes -.Nm -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. -.It Xo addvars -.Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,... -.Xc -.It Xo rmvars -.Aq variable_name Ns -.Op ,... -.Xc -.It clearvars -The data carried by NTP mode 6 messages consists of a list of items of -the form -.Xo Aq variable_name Ns -.Pf = Aq value -.Xc -where the -.Qq = Ns Aq value -is ignored, and can be omitted, in requests -to the server to read variables. -.Nm Ntpq -maintains an internal list in which data to be included in control -messages can be assembled, and sent using the -.Em readlist -and -.Em writelist -commands described below. The -.Em 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 -.Em rmvars -command can be used to remove individual variables from the list, while -the -.Em clearlist -command removes all variables from the list. -.It debug Ar more | Ar less | Ar off -Turn internal query program debugging on and off. -.It quit -Exit -.Nm Ns . -.El -.Sh CONTROL MESSAGE COMMANDS -Each peer known to an NTP server has a 16 bit integer -.Em association 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 -.Em peers -command, which will send a preprogrammed series of messages to obtain -the data it needs, and the -.Em mreadlist -and -.Em mreadvar -commands, which will iterate over a range of associations. -.Bl -tag -width indent -.It associations -Obtain and print 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 -.Nm Ns . -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 -.Em &index -may be used as an alternative. -.It lassocations -Obtain and print a list of association identifiers and peer statuses -for all associations for which the server is maintaining state. This -command differs from the -.Em associations -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 -.Em associations -command is used, but are included in the -output of -.Em lassociations Ns . -.It passociations -Print association data concerning in\-spec peers from the internally -cached list of associations. This command performs identically to the -.Em associations -except that it displays the internally stored -data rather than making a new query. -.It lpassociations -Print data for all associations, including out\-of\-spec client -associations, from the internally cached list of associations. This -command differs from -.Em passociations -only when dealing with fuzzballs. -.It pstatus Ar assocID -Send 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 hexadecimal and in pidgin English. -.It Xo readvar -.Op Ar assocID Ns -.Pf [ Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] -.Xc -Request 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. -.It Xo rv -.Op Ar assocID Ns -.Pf [ Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] -.Xc -An easy\-to\-type short form for the -.Em readvar -command. -.It Xo writevar -.Ar assocID -.Aq variable_name Ns -.Pf = Ns Aq value Ns -.Op ,... -.Xc -Like the -.Em readvar -request, except the specified variables are written instead of read. -.It readlist Op Ar assocID -Request 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. -.It rl Op Ar assocID -An easy\-to\-type short form of the -.Em readlist -command. -.It writelist Op Ar assocID -Like the -.Em readlist -request, except the internal list variables are written instead of read. -.It Xo mreadvar -.Ar assocID assocID [ -.Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] -.Xc -Like the -.Em 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 -.Em associations -command. -.It Xo mrv -.Ar assocID assocID [ -.Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] -.Xc -An easy\-to\-type short form of the -.Em mreadvar -command. -.It mreadlist Ar assocID assocID -Like the -.Em 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 -.Em associations -command. -.It mrl Ar assocID assocID -An easy\-to\-type short form of the -.Em mreadlist -command. -.It Xo clockvar -.Op Ar assocID Ns -.Pf [ Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] -.Xc -Request 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 -.Qq system clock -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. -.It Xo cv -.Op Ar assocID Ns -.Pf [ Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] -.Xc -An easy\-to\-type short form of the -.Em clockvar -command. -.It peers -Obtain 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 type of the peer (local, unicast, -multicast or broadcast), when the last packet was received, 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; -.Qq x -designated falsticker -by the intersection algorithm; -.Qq \&. -culled from the end of the -candidate list; -.Qq - -discarded by the clustering algorithm; -.Qq + -included in the final selection set; -.Qq # -selected -for synchronization but distance exceeds maximum; -.Qq * -selected -for synchronization; and -.Qq o -selected for synchronization, pps -signal in use. -.Pp -Note that since the -.Em 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 -.Qq REFCLK(<implementation number>, <parameter>) . -On -.Qq hostnames no -only IP\-addresses will be displayed. -.It lpeers -Like -.Em 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. -.It opeers -An old form of the -.Em peers -command with the reference ID -replaced by the local interface address. -.El -.Sh HISTORY -Written by -.An Dennis Ferguson -at the University of Toronto. -.Sh BUGS -The -.Em peers -command is non\-atomic and may occasionally result in spurious error -messages about invalid associations occurring 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 deleted file mode 100644 index 1ef3595..0000000 --- a/usr.sbin/xntpd/doc/ntptrace.8 +++ /dev/null @@ -1,65 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd December 21, 1993 -.Dt NTPTRACE 8 -.Os -.Sh NAME -.Nm ntptrace -.Nd "trace a chain of NTP hosts back to their master time source" -.Sh SYNOPSIS -.Nm ntptrace -.Op Fl vdn -.Op Fl r Ar retries -.Op Fl t Ar timeout -.Op Ar server -.Sh DESCRIPTION -.Nm 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 -.Dq localhost . -.Pp -Here is an example of the output from -.Nm Ns : -.Bd -literal -% ntptrace -localhost: stratum 4, offset 0.0019529, synch distance 0.144135 -server2.bozo.com: stratum 2, offset 0.0124263, synch distance 0.115784 -h.edu: stratum 1, offset 0.0019298, synch distance 0.011993, refid 'WWVB' -.Ed -.Pp -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 -.Nm Ns ; -this is why it is not always zero for -.Dq localhost ) , -the host's -.Dq 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 -The following options are available: -.Bl -tag -width indent -.It Fl d -Turn on some debugging output. -.It Fl n -Turn off the printing of host names; instead, host IP addresses -are given. This may be necessary if a nameserver is down. -.It Fl r Ar retries -Set the number of retransmission attempts for each host; the default is 5. -.It Fl t Ar timeout -Set the retransmission timeout (in seconds); the default is 2. -.It Fl v -Print verbose information about the NTP servers. -.El -.Sh SEE ALSO -.Xr xntpd 8 , -.Xr 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 deleted file mode 100644 index 4ba5a09..0000000 --- a/usr.sbin/xntpd/doc/tickadj.8 +++ /dev/null @@ -1,124 +0,0 @@ -.\" $FreeBSD$ -.\" -.Dd December 21, 1993 -.Dt TICKADJ 8 -.Os -.Sh NAME -.Nm tickadj -.Nd fiddle time\-related variables in the kernel -.Sh SYNOPSIS -.Nm tickadj -.Op Fl Adkpqs -.Op Fl a Ar new_tickadj -.Op Fl t Ar new_tick -.Sh DESCRIPTION -The -.Nm -program reads, and optionally modifies, several time\-keeping\-related -variables in the running kernel, via -.Pa /dev/kmem . -The particular variables it is concerned with are -.Em tick , -which is the number of microseconds added to the system time during a -clock interrupt, -.Em tickadj , -which sets the slew rate and resolution used by the -.Xr adjtime 2 -system call, and -.Em dosynctodr , -which indicates to the kernels on some machines whether they should internally -adjust the system clock to keep it in line with time\-of\-day clock -or not. -.Pp -By default, with no arguments, -.Nm -reads the variables of interest in the kernel and prints them. At the -same time it determines an -.Qq optimal -value for the value of the -.Em tickadj -variable if the intent is to run the -.Xr xntpd 8 -Network Time Protocol daemon, and prints this as well. Since the operation -of -.Nm -when reading the kernel mimics the operation of similar parts of the -.Xr xntpd 8 -program fairly closely, this is useful for doing debugging of problems -with -.Xr xntpd 8 Ns . -.Pp -Various flags may be specified to change the variables of interest in -the running kernel: -.Bl -tag -width indent -.It Fl a Ar new_tickadj -Allow one to set the variable -.Em tickadj -to the value specified as an argument. -.It Fl A -Cause -.Em tickadj -to be modified, but instead will set it to the internally computed -.Qq optimal -value. -.It Fl d -Add debugging information. -.It Fl k -Use -.Pa /dev/kmem -instead of -.Pa /kernel . -This is the default. -.It Fl p -Tell -.Nm -to set the value of the variable -.Em noprintf -to one. -.It Fl q -Tell -.Nm -to shut up about everything except errors. Normally -.Nm -is quite verbose about what it is doing. -.It Fl s -Tell -.Nm -to set the value of the variable -.Em dosynctodr -to zero, a prerequisite for running the -.Xr xntpd 8 -daemon under SunOS 4.0. -.It Fl t Ar new_tick -May be used to reset the kernel's value of -.Em tick , -a capability which is useful on machines with very broken clocks. -.El -.Pp -Note that -.Nm -should be run with some caution when being used for the first time on -different types of machines. The operations which -.Nm -trys to perform are not guaranteed to work on all Unix machines. -.Sh FILES -.Bl -tag -width /dev/kmem -compact -.It Pa /kernel -.It Pa /dev/kmem -.El -.Sh SEE ALSO -.Xr xntpd 8 -.Sh HISTORY -Written by -.An 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 -.Xr adjtime 2 -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 -.Nm -program went away. diff --git a/usr.sbin/xntpd/doc/xntpd.8 b/usr.sbin/xntpd/doc/xntpd.8 deleted file mode 100644 index a4a290c..0000000 --- a/usr.sbin/xntpd/doc/xntpd.8 +++ /dev/null @@ -1,1075 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd December 21, 1993 -.Dt XNTPD 8 -.Os -.Sh NAME -.Nm xntpd -.Nd Network Time Protocol daemon -.Sh SYNOPSIS -.Nm xntpd -.Op Fl abdm -.Op Fl c Ar conffile -.Op Fl e Ar authdelay -.Op Fl f Ar driftfile -.Op Fl k Ar keyfile -.Op Fl p Ar pidfile -.Op Fl r Ar broadcastdelay -.Op Fl s Ar statsdir -.Op Fl t Ar trustedkey -.Op Fl v Ar variable -.Op Fl V Ar variable -.Sh DESCRIPTION -.Nm Xntpd -is a daemon which sets and maintains a Unix system time\-of\-day in -agreement with Internet standard time servers. -.Nm Xntpd -is a complete implementation of the Network Time Protocol (NTP) version -3 standard, as defined by RFC 1305, but also retains compatibility with -version 1 and 2 servers as defined by RFC 1059 and RFC 1119, -respectively. -.Nm Xntpd -does all computations in fixed point arithmetic and requires no 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 computations, to -try to maintain an accuracy suitable for synchronizing with even the -most precise external time source. -.Pp -Ordinarily, -.Nm -reads its configuration from a configuration file at startup time. The -default configuration file name is -.Pa /etc/ntp.conf , -although this may be overridden from the command line. It is also -possible to specify a working, although limited, -.Nm -configuration entirely on the command line, obviating the need for a -configuration file. This may be particularly appropriate when -.Nm -is to be configured as a broadcast or multicast client, with all peers -being determined by listening to broadcasts at run time. Various -internal -.Nm -variables can be displayed and configuration options altered while the -daemon is running through use of the -.Xr ntpq 8 -and -.Xr xntpdc 8 -programs. -.Pp -The daemon can operate in any of several modes, including symmetric -active/passive, client/server and broadcast/multicast. A -broadcast/multicast client can automatically discover remote servers, -compute one-way delay correction factors and configure itself -automatically. This makes it possible to deploy a fleet of workstations -without specifying a configuration file or configuration details -specific to its environment. -.Pp -The following command line arguments are understood by -.Nm -(see the configuration file description for a more complete functional -description): -.Bl -tag -width indent -.It Fl a -Run in -.Qq "authenticate" -mode. -.It Fl b -Listen for broadcast NTP and sync to this if available. -.It Fl c -Specify an alternate configuration file. -.It Fl d -Specify debugging mode. This flag may occur multiple times, with each -occurance indicating greater detail of display. -.It Fl e -Specify the time (in seconds) it takes to compute the NTP encryption -field on this computer. -.It Fl f Ar driftfile -Specify the location of the drift file. -.It Fl k -Specify the location of the file which contains the NTP authentication -keys. -.It Fl m -Listen for multicast messages and synchronize to them if available -(requires multicast kernel). -.It Fl p -Specify the name of the file to record the daemon's process id. -.It Fl r -Ordinarily, the daemon automatically compensates for the network delay -between the broadcast/multicast server and the client; if the -calibration procedure fails, use the specified the default delay (in -seconds). -.It Fl s -Specify the directory to be used for creating statistics files. -.It Fl t Ar trustedkey -Add a key number to the trusted key list. -.It Fl v -Add a system variable. -.It Fl V -Add a system variable listed by default. -.El -.Sh "CONFIGURATION OPTIONS" -.Nm Xntpd Ns 's -configuration file format is similar to other Unix configuration files. -Comments begin with a -.Qq # -character and extend to the end of the -line. Blank lines are ignored. Configuration commands consist of an -initial keyword followed by a list of arguments, some of which may be -optional, separated by whitespace. These commands may not be continued -over multiple lines. Arguments may be host names, host addresses written -in numeric, dotted\-quad form, integers, floating point numbers (when -specifying times in seconds) and text strings. Optional arguments are -delimited by -.Qq [] -in the following descriptions, while -alternatives are separated by -.Qq \&| . -.Pp -.Bl -tag -width indent -.It Xo peer -.Ar host_address -.Op key Ar # -.Op version Ar # -.Op prefer -.Xc -.It Xo server -.Ar host_address -.Op key Ar # -.Op version Ar # -.Op prefer -.Xc -.It Xo broadcast -.Ar host_address -.Op key Ar # -.Op version Ar # -.Op ttl Ar # -.Xc -.Pp -These three commands specify various time servers to be used and/or time -services to be provided. The -.Em peer -command specifies that the local server is to operate in -.Qq symmetric active -mode with the remote server -.Ar host_address -named in the command. In this mode the local server can be synchronized -to the remote server and, in addition, the remote server can be -synchronized by the local server. This is useful in a network of servers -where, depending on various failure scenarios, either the local or -remote server host may be the better source of time. The -.Em server -command specifies that the local server is to operate in -.Qq client -mode with the remote server named in the command. In -this mode the local server can be synchronized to the remote server, but -the remote server can never be synchronized to the local server. The -.Em broadcast -command specifies that the local server is to operate in -.Qq broadcast -mode where the local server sends periodic broadcast -messages to a client population at the broadcast/multicast address named -in the command. Ordinarily, this specification applies only to the local -server operating as a transmitter; for operation as a broadcast client, -see the -.Em broadcastclient -or -.Em multicastclient -commands elsewhere in this document. In this mode the -.Ar host_address -is usually the broadcast address on [one of] the local network[s] or a -multicast address assigned to NTP. The Numbers Czar has assigned the -address 224.0.1.1 to NTP; this is presently the only number that should -be used. Note that the use of multicast features requires a multicast -kernel, which is not yet ubiquitous in vendor products. -.Pp -The -.Ar 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 -.Ar 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 -.Ar 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. The -.Ar ttl -option is used only with the broadcast mode. It specifies the time-to-live -(TTL) to use on multicast packets. Selection of the proper value, -which defaults to 127, is something of a black art and must be -coordinated with the network admistrator(s). -.It broadcastclient -This directs the local server to listen for broadcast messages on the -local network, in order to discover other servers on the same subnet. -Upon hearing a broadcast message for the first time, the local server -measures the nominal network delay using a brief client/server exchange -with the remote server, then enters the -.Qq broadcastclient -mode, -in which it listens for and synchronizes to succeeding broadcast -messages. Note that, in order to avoid accidental or malicious -disruption in this mode, both the local and remote servers must operate -using authentication with the same trusted key and key identifier. -.It multicastclient Op Ar IP address ... -This command is used in the same way as the -.Em broadcastclient -command, but operates using IP multicasting. Support for this function -requires a multicast kernel and the use of authentication. If one or -more IP addresses are given, the server joins the respective multicast -group(s). If none are given, the IP address assigned to NTP (224.0.1.1) -is assumed. -.It driftfile Ar filename -This command specifies the name of the file used to record the frequency -offset of the local clock oscillator. If the file exists, it is read at -startup in order to set the initial frequency offset and then updated -once per hour with the current offset computed by the daemon. If the -file does not exist or this command is not given, the initial frequency -offset is assumed zero. In this case, it may take some hours for the -frequency to stabilize and the residual timing errors to subside. The -file contains a single floating point value equal to the offset in -parts-per-million (ppm). Note that the file is updated by first writing -the current drift value into a temporary file and then using -.Xr rename 2 -to replace the old version. This implies that -.Nm -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. -.It enable Ar auth|bclient|pll|monitor|stats Op Ar ... -Provide a way to enable various server options. Flags not mentioned are -unaffected. The -.Ar auth -flag causes the server to synchronize -with unconfigured peers only if the peer has been correctly -authenticated using a trusted key and key identifier. The default for -this flag is disable (off). The -.Ar bclient -flag causes the server -to listen for a message from a broadcast or multicast server, following -which an association is automatically instantiated for that server. The -default for this flag is disable (off). The -.Ar pll -flag enables -the server to adjust its local clock, with default enable (on). If not -set, the local clock free-runs at its intrinsic time and frequency -offset. This flag is useful in case the local clock is controlled by -some other device or protocol and NTP is used only to provide -synchronization to other clients. The -.Ar monitor -flag enables the -monitoring facility (see elsewhere), with default enable (on). The -.Ar stats -flag enables statistics facility filegen (see -description elsewhere.), with default enable (on). -.It disable Ar auth|bclient|pll|monitor|stats Op Ar ... -Provide a way to disable various server options. Flags not mentioned -are unaffected. The flags presently available are described under the -enable command. -.El -.Sh "AUTHENTICATION OPTIONS" -.Bl -tag -width indent -.It keys Ar filename -This command specifies the name of a file which contains the encryption -keys and key identifiers used by -.Nm -when operating in authenticated mode. The format of this file is -described later in this document. -.It trustedkey Ar # Op Ar # ... -This command is used to specify the encryption key identifiers which are -trusted for the purposes of authenticating peers suitable for -sychonization. The authentication procedures require that both the local -and remote servers share the same key and key identifier for this -purpose, although different keys can be used with different servers. 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. -.It requestkey Ar # -This command specifies the key identifier to use with the -.Xr xntpdc 8 -program, which is useful to diagnose and repair problems that affect -.Nm -operation. The operation of the -.Nm xntpdc -program are specific to this particular implementation of -.Nm -and can -be expected to work only with this and previous versions of the daemon. -Requests from a remote -.Nm xntpdc -program which affect the state of the -local server must be authenticated, which requires bot the remote -program and local server share a common key and key identifier. The -argument to this command is a 32 bit unsigned integer. If no -.Em controlkey -command is included in the configuration file, or if the keys don't -match, such requests will be ignored. -.It controlkey Ar # -This command specifies the key identifier to use with the -.Xr ntpq 8 -program, which is useful to diagnose and repair problems that affect -.Nm -operation. The operation of the -.Nm ntpq -program and -.Nm -conform to those specified in RFC 1305. Requests from a remote -.Nm ntpq -program which affect the state of the local server must be -authenticated, which requires bot the remote program and local server -share a common key and key identifier. The argument to this command is a -32 bit unsigned integer. If no -.Em requestkey -command is included in the configuration file, or if the keys don't -match, such requests will be ignored. -.It authdelay Ar seconds -Indicate 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 -.Em authspeed -program included with the distribution. -.El -.Sh "ACCESS CONTROL OPTIONS" -.Bl -tag -width indent -.It Xo restrict -.Ar address -.Op mask Ar numeric_mask -.Op Ar flag -.Op Ar ... -.Xc -.Nm 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 -.Em mask -argument defaults -to 255.255.255.255, meaning that the -.Em address -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 -.Em address -is normally -given in dotted\-quad format, the text string -.Em default , -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: -.Bl -tag -width indent -.It ignore -Ignore all packets from hosts which match this entry. If this flag is -specified neither queries nor time server polls will be responded to. -.It noquery -Ignore all NTP mode 6 and 7 packets (i.e. information queries and -configuration requests) from the source. Time service is not affected. -.It nomodify -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. -.It notrap -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. -.It lowpriotrap -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. -.It noserve -Ignore NTP packets whose mode is other than 6 or 7. In effect, time -service is denied, though queries may still be permitted. -.It nopeer -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. -.It notrust -Treat these hosts normally in other respects, but never use them as -synchronization sources. -.It limited -These hosts are subject to limitation of number of clients from the same -net. Net in this context refers to the IP notion of net (class A, class -B, class C, etc.). Only the first -.Qq client_limit -hosts that have -shown up at the server and that have been active during the last -.Qq client_limit_period -seconds are accepted. Requests from other -clients from the same net are rejected. Only time request packets are -taken into account. -.Qq Private , -.Qq control , -and -.Qq broadcast -packets are not subject to client limitation and -therefore are not contributing to client count. History of clients is -kept using the monitoring capability of -.Nm Ns . -Thus, monitoring is active as long as there is a restriction entry with -the -.Qq limited -flag. The default value for -.Qq client_limit -is 3. The default value for -.Qq client_limit_period -is 3600 seconds. -.It ntpport -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 -.Qq ntpport -and -.Pf non\- Qq ntpport -may be specified. The -.Qq ntpport -is considered more specific and is sorted later in the -list. -.El -.Pp -Default restriction list entries, with the flags -.Qq ignore , -.Qq ntpport , -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 -.Nm -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. -.It clientlimit Ar limit -Set -.Qq client_limit -to -.Ar limit , -allow configuration of -client limitation policy. This variable defines the number of clients -from the same network that are allowed to use the server. -.It clientperiod Ar period -Set -.Qq client_limit_period , -allow configuration of client -limitation policy. This variable specifies the number of seconds after -which a client is considered inactive and thus no longer is counted for -client limit restriction. -.El -.Sh "MONITORING OPTIONS" -.Bl -tag -width indent -.It statsdir Ar /directory path/ -Indicate 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 -.Em filegen -statement below). -.It statistics Ar name Ns ... -Enable writing of statistics records. Currently, three kinds of -statistics are supported: -.Bl -tag -width indent -.It loopstats -Enable 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 -.Qq loopstats : -.Dl 48773 10847.650 0.0001307 17.3478 2 -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. -.It peerstats -Enable 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 -.Qq peerstats : -.Dl 48773 10847.650 127.127.4.1 9714 -0.001605 0.00000 0.00142 -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. -.It clockstats -Enable 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 -.Qq clockstats : -.Dl 49213 525.624 127.127.4.1 93 226 00:08:29.606 D -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 -.Tn 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. -.El -.Pp -Statistic files are managed using file generation sets (see -.Em filegen -below). The information obtained by enabling statistics recording allows -analysis of temporal properties of a -.Nm -server. It is usually only useful to primary servers or maybe main -campus servers. -.It Xo filegen -.Ar name -.Op file Ar filename -.Op type Ar typename -.Op flag Ar flagval -.Op link | nolink -.Op enable | disable -.Xc -Configure setting of generation file set -.Ar 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 -.Em 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 -.Nm Ns . -(Most important: they can be removed to free space for new data -produced.) Filenames of set members are built from three elements: -.Bl -tag -width indent -.It prefix -This is a constant filename path. It is not subject to modifications via -the -.Em 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 -.Qq loopstats -and -.Qq peerstats -filegens can be configured using the -.Em statsdir -statement explained above. -.It filename -This string is directly concatenated to the -.Em prefix -mentioned above (no intervening -.Sq / -(slash)). This can be -modified using the -.Ar file -argument to the -.Em filegen -statement. No -.Qq .. -elements are allowed in this component to -prevent filenames referring to parts outside the filesystem hierarchy -denoted by -.Em prefix . -.It suffix -This part is reflects individual elements of a file set. It is generated -according to the -.Em type -of a file set as explained below. -.El -.Pp -A file generation set is characterized by its type. The following types -are supported: -.Bl -tag -width indent -.It none -The file set is actually a single plain file. -.It pid -One element of file set is used per incarnation of a -.Nm -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 -.Nm -server incarnations. The set member filename is built by appending a dot -.Pf ( Sq \&. Ns ) -to concatentated -.Em prefix -and -.Em filename -strings, and appending the decimal representation of the process id of -the -.Nm -server process. -.It day -One file generation set element is created per day. The term -.Em day -is based on -.Tn UTC . -A day is defined as the period between 00:00 and 24:00 -.Tn UTC . -The file set -member suffix consists of a dot -.Pf ( Qq \&. Ns ) -and a day specification in -the form -.Aq YYYYMMDD . -.Em YYYY -is a 4 digit year number (e.g. 1992). -.Em MM -is a two digit month number. -.Em DD -is a two digit day number. Thus, all information written at December -10th, 1992 would end up in a file named -.Qq <prefix><filename>.19921210 . -.It week -Any file set member contains data related to a certain week of a year. -The term -.Em week -is definied by computing -.Qq day of year -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 -.Qq W , -and a two digit week number. For example, -information from Jamuary, 10th 1992 would end up in a file with suffix -.Qq .1992W1 . -.It month -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. -.It year -One generation file element is generated per year. The filename suffix -consists of a dot and a 4 digit year number. -.It age -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 -.Qq a , -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. -.El -.Pp -Information is only written to a file generation set when this set is -.Qq enabled . -Output is prevented by specifying -.Qq disabled . -.Pp -It is convenient to be able to access the -.Em current -element of a file generation set by a fixed name. This feature is -enabled by specifying -.Qq link -and disabled using -.Qq nolink . -If -.Qq link -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 -.Qq C , -and the pid -of the -.Nm -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. -.El -.Sh "MISCELLANEOUS OPTIONS" -.Bl -tag -width indent -.It precision Ar # -This command specifies the nominal precision of the local clock. The -value is an integer approximately equal to the base 2 logarithm of the -local timekeeping precision in seconds. Normally, the daemon determines -the precision automatically at startup, so this command is necessary -only in special cases when the precision cannot be determined -automatically. -.It broadcastdelay Ar seconds -The broadcast and multicast modes require a special calibration to -determine the network delay between the local and remote servers. -Ordinarily, this is done automatically by the initial protocol exchanges -between the local and remote servers. In some cases, the calibration -procedure may fail due to network or server access controls, for -example. This command specifies the default delay to be used under these -circumstances. Typically (for Ethernet), a number between 0.003 and -0.007 seconds is appropriate. The default when this command is not used -is 0.004 seconds. -.It Xo trap -.Ar host_address -.Op port Ar port_number -.Op interface Ar interface_addess -.Xc -This command configures a trap receiver at the given host address and -port number for 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. -.It Xo setvar -.Ar variable -.Op Ar default -.Xc -This command adds an additional system variable. These variables can be -used to distribute additional information such as the access policy. If -the variable of the form <name>=<value> is followed by the -.Em default -keyword the variable will be listed as part of the default system -variables -.Pf ( Nm ntpq -rv command). These additional variables serve informational purposes only. -They are not related to the protocol other that they can be listed. The -known protocol variables will always overide any variables defined via -the -.Em setvar -mechanism. -.Pp -There are three special variables that contain the names of all variable -of the same group. The -.Em sys_var_list -holds the names of all system variables. The -.Em peer_var_list -holds the names of all peer variables and the -.Em clock_var_list -hold the names of the reference clock variables. -.It monitor Ar yes|no -.It authenticate Ar yes|no -These commands have been superseded by the -.Em enable -and -.Em disable -commands. They are listed here for historical purposes. -.El -.Sh "AUTHENTICATION KEY FILE FORMAT" -The -.Tn 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 -.Nm -using the DES or MD5 algorithms to compute a digital signature, or -message-digest. The specification allows any one of possibly 4 billion -keys, numbered with 32 bit key identifiers, to be used to authenticate -an association. The servers involved in an association must agree on the -key and key identifier used to authenticate their data, though they must -each learn the key and key identifer independently. In the case of DES, -the keys are 56 bits long with, depending on type, a parity check on -each byte. In the case of MD5, the keys are 64 bits (8 bytes). -.Nm Xntpd -reads its keys from a file specified using the -.Fl k -command line option or the -.Em keys -statement in the configuration file. While key number 0 is fixed by the -.Tn 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: -.Pp -.Dl keyno type key -.Pp -where -.Em keyno -is a positive integer, -.Em type -is a single -character which defines the format the key is given in, and -.Em key -is the key itself. -.Pp -The key may be given in one of three different formats, controlled by -the -.Em type -character. The three key types, and corresponding -formats, are listed following: -.Bl -tag -width indent -.It S -The -.Em key -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 -.Em 0101010101010101 . -.It N -The -.Em key -is a 64 bit hexadecimal number in the format specified -in the -.Tn 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 -.Em 8080808080808080 . -.It A -The -.Em key -is a 1\-to\-8 character -.Tn ASCII -string. A key is formed from this by using the lower order 7 bits of the -.Tn 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. -.It M -The -.Em key -is a 1\-to\-8 character -.Tn 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. -.El -.Pp -One of the keys may be chosen, -by way of the configuration file -.Em requestkey -statement, to authenticate run time configuration requests made using -the -.Xr 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 -.Tn ASCII -format. -.Sh PRIMARY CLOCK SUPPORT -.Nm 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 -Support for the various reference clock drivers is conditionally -compiled using the compiler define codes described elsewhere. An attempt -to configure a reference clock when specific support is not available or -the hardware port has not been appropriately configured results in a -scolding remark to the system log file, but is otherwise non hazardous. -.Pp -For the purposes of configuration, -.Nm -treats reference clocks in a manner analogous to normal -.Tn 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 -.Em 127.127.t.u -where -.Em t -is an integer denoting the clock type and -.Em u -indicates the type\-specific unit number. Reference clocks are -configured using a -.Em server -statement in the configuration file where the -.Em host_address -is the clock address. The -.Em key, -.Em version -and -.Em ttl -options are not used for reference clock support; however, the -.Em prefer -option can be useful to persuade the server to cherish a reference clock -with somewhat more enthusiasm than other reference clocks or peers, if -this is advisable. Clock addresses may generally be used anywhere in the -configuration file a normal IP address can be used, for example, in -.Em restrict -statements, although such use would normally be considered strange. -.Pp -Reference clock support provides the -.Em fudge -command, which can be used to configure reference clocks in special -ways. Following is the generic format that applies to this command: -.Pp -fudge -.Ar 127.127.t.u -.Op time1 Ar secs -.Op time2 Ar secs -.Op stratum Ar int -.Op refid Ar int -.Op flag1 Ar 0|1 -.Op flag2 Ar 0|1 -.Op flag3 Ar 0|1 -.Op flag4 Ar 0|1 -.Pp -The -.Em time1 -and -.Em time2 -options are specified in fixed point seconds and used in some clock -drivers as calibration constants. By convention, and unless indicated -otherwise, -.Em time1 -is used as a calibration constant to adjust the nominal time offset of a -particular clock to agree with an external standard, such as a precision -PPS signal. The specified offset is in addition to the propagation delay -provided by other means, such as internal DIPswitches. The -.Em stratum -option is a number in the range zero to 15 and is used to assign a -nonstandard operating stratum to the clock. The -.Em refid -option is an -.Tn ASCII -string in the range one to four characters and is -used to assign a nonstandard reference identifier to the clock. Finally, -the four binary flags -.Em flag1, -.Em flag2, -.Em flag3 -and -.Em flag4 -are used for customizing the clock driver. The interpretation of these -values, and whether they are used at all, is a function of the needs of -the particular clock driver. However, by convention, and unless -indicated otherwise, -.Em flag3 -is used to attach the ppsclock streams module to the configured driver, -while -.Em flag4 -is used to enable recording verbose monitoring data to the clockstats -file configured with the -.Em filegen -command. Further information on the ppsclock streams module is in the -.Pa README -file in the -.Pa ./kernel -directory in the current xntp3 program -distribution. Further information on this feature is available in the -.Pa ./scripts/stats -directory in the same distribution. -.Pp -Ordinarily, the stratum of a reference clock is by default zero. Since -the -.Nm -daemon adds one to the stratum of each peer, a primary server ordinarily -displays stratum one. In order to provide engineered backups, it is -often useful to specify the reference clock stratum as greater than -zero. The -.Em stratum -option is used for this purpose. Also, in cases involving both a -reference clock and a 1-pps discipline signal, it is useful to specify -the reference clock identifier as other than the default, depending on -the driver. The -.Em refid -option is used for this purpose. Except where noted, these options apply -to all clock drivers. -.Pp -.Nm 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 -.Pa README -file in the -.Pa ./doc -directory of the xntp3 progam distribution. -The clock drivers, and the addresses used to configure them, are -described in the -.Pa README.refclocks -in the -.Pa doc -directory of the current -program distribution. -.Sh VARIABLES -Most variables used by the -.Tn NTP -protocol can be examined with the -.Nm xntpdc -(mode 7 messages) and the -.Nm ntpq -(mode 6 messages). Currently very few variables can be modified via mode -6 messages. These variables are either created with the -.Em setvar -directive or the leap warning variables. The leap warning bits that can -be set in the -.Em leapwarning -variable (up to one month ahead). Both, the -.Em leapwarning -and the -.Em leapindication -variable, have a slightly different encoding than the usual -.Em leap -bits interpretation: -.Bl -tag -width indent -.It 00 -The daemon passes the leap bits of its synchronisation source (usual -mode of operation). -.It 01/10 -A leap second is added/deleted (operator forced leap second). -.It 11 -Leap information from the sychronisation source is ignored (thus -LEAP_NOWARNING is passed on). -.El -.Sh FILES -.Bl -tag -width /etc/ntp.drift -compact -.It /etc/ntp.conf -the default name of the configuration file -.It /etc/ntp.drift -the conventional name of the drift file -.It /etc/ntp.keys -the conventional name of the key file -.El -.Sh SEE ALSO -.Xr ntpdate 8 , -.Xr ntpq 8 , -.Xr xntpdc 8 -.Sh HISTORY -Written by -.An Dennis Ferguson -at the University of Toronto. Text amended by -.An David Mills -at the University of Delaware. -.Sh BUGS -.Nm 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. diff --git a/usr.sbin/xntpd/doc/xntpdc.8 b/usr.sbin/xntpd/doc/xntpdc.8 deleted file mode 100644 index 3e17d5c..0000000 --- a/usr.sbin/xntpd/doc/xntpdc.8 +++ /dev/null @@ -1,674 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd December 21, 1993 -.Dt XNTPDC 8 -.Os -.Sh NAME -.Nm xntpdc -.Nd query/control program for the Network Time Protocol daemon -.Sh SYNOPSIS -.Nm xntpdc -.Op Fl ilnps -.Op Fl c Ar command -.Op Ar host ... -.Sh DESCRIPTION -.Nm Xntpdc -is used to query the -.Xr 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 -.Nm -interface. In addition, nearly all the configuration options which can -be specified at start up using -.Nm xntpd Ns 's -configuration file may also be specified at run time using -.Nm Ns . -.Pp -If one or more request options is included on the command line when -.Nm -is executed, each of the requests will be sent to the -.Tn NTP -servers -running on each of the hosts given as command line arguments, or on -.Ar localhost -by default. If no request options are given, -.Nm -will attempt to read commands from the standard input and execute these -on the -.Tn NTP -server running on the first host given on the command line, -again defaulting to -.Ar localhost -when no other host is specified. -.Nm Xntpdc -will prompt for commands if the standard input is a terminal device. -.Pp -.Nm Xntpdc -uses -.Tn NTP -mode 7 packets to communicate with the -.Tn NTP -server, and hence -can be used to query any compatible server on the network which permits -it. Note that since -.Tn NTP -is a UDP protocol this communication will be -somewhat unreliable, especially over large distances in terms of network -topology. -.Nm 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 -.Fl i -or -.Fl n -will cause the specified query (queries) to be sent to the indicated -host(s) immediately. Otherwise, -.Nm -will attempt to read interactive format commands from the standard -input. -.Bl -tag -width indent -.It Fl c -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 -.Fl c -options may be given. -.It Fl i -Force -.Nm -to operate in interactive mode. Prompts will be written to the standard -output and commands read from the standard input. -.It Fl l -Obtain a list of peers which are known to the server(s). This switch is -equivalent to -.Qq -c listpeers . -.It Fl n -Output all host addresses in dotted\-quad numeric format rather than -converting to the canonical host names. -.It Fl p -Print a list of the peers known to the server as well as a summary of -their state. This is equivalent to -.Qq -c peers . -.It Fl s -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 -.Fl p -switch. This is equivalent to -.Qq -c dmpeers . -.El -.Sh INTERNAL COMMANDS -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 -.Qq > , -followed by a -file name, to the command line. -.Pp -A number of interactive format commands are executed entirely within the -.Nm -program itself and do not result in -.Tn NTP -mode 7 requests being sent to a -server. These are described following: -.Pp -.Bl -tag -width indent -.It Xo ? -.Op Ar command_keyword -.Xc -A -.Em ? -by itself will print a list of all the command keywords -known to this incarnation of -.Nm Ns . -A -.Em ? -followed by a command keyword will print function and -usage information about the command. This command is probably a better -source of information about -.Nm -than this manual page. -.It help Ar command_keyword -A synonym for the -.Em ? -command. -.It timeout Ar millseconds -Specify a time out period for responses to server queries. The default -is about 8000 milliseconds. -.It delay Ar milliseconds -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. -.It host Ar hostname -Set the host to which future queries will be sent. -.Ar Hostname -may be either a host name or a numeric (dotted quad) dmaddress. -.It keyid Ar # -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. -.It passwd -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 -.Tn NTP -server for this purpose if such requests are to be successful. -.It hostnames Ar yes|no -If -.Ar yes -is specified, host names are printed in information -displays. If -.Ar no -is given, numeric addresses are printed -instead. The default is -.Ar yes -unless modified using the command line -.Fl n -switch. -.It quit -Exit -.Nm Ns . -.El -.Sh QUERY COMMANDS -Query commands result in -.Tn NTP -mode 7 packets containing requests for -information being sent to the server. These are -.Qq read\-only -commands in that they make no modification of the server configuration -state. -.Bl -tag -width indent -.It listpeers -Obtain and print 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 synchronization candidates. -.It peers -Obtain 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 -.Qq + -denotes symmetric -active, a -.Qq - -indicates symmetric passive, a -.Qq = -means -the remote server is being polled in client mode, a -.Qq ^ -indicates that the server is broadcasting to this address, a -.Qq ~ -denotes that the remote peer is sending broadcasts and a -.Qq * -marks the peer the server is currently synchronizing 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 -.Qq REFCLK(<implementation number>, <parameter>) . -On -.Qq hostnames no -only IP\-addresses will be displayed. -.It dmpeers -A slightly different peer summary list. Identical to the output of the -.Em 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 -.Qq \&. -indicates that this peer was cast off -in the falseticker detection, while a -.Qq + -indicates that the -peer made it through. A -.Qq * -denotes the peer the server is -currently synchronizing with. -.It Xo showpeer -.Ar peer_address -.Op Ar addr2 -.Op Ar addr3 -.Op Ar addr4 -.Xc -Show a detailed display of the current peer variables for one or more -peers. Most of these values are described in the -.Tn NTP -Version 2 specification. -.It Xo pstats -.Ar peer_address -.Op Ar addr2 -.Op Ar addr3 -.Op Ar addr4 -.Xc -Show per\-peer statistic counters associated with the specified peer(s). -.It Xo clockinfo -.Ar clock_peer_address -.Op Ar addr2 -.Op Ar addr3 -.Op Ar addr4 -.Xc -Obtain and print information concerning a peer clock. The values -obtained provide information on the setting of fudge factors and other -clock performance information. -.It kerninfo -Obtain and print kernel phase-lock loop operating parameters. This -information is available only if the kernel has been specially modified -for a precision timekeeping function. -.It loopinfo Op Ar oneline|multiline -Print the values of selected loop filter variables. The loop filter is -the part of -.Tn NTP -which deals with adjusting the local system clock. The -.Qq offset -is the last offset given to the loop filter by the -packet processing code. The -.Qq frequency -is the frequency error -of the local clock in parts-per-million (ppm). The -.Qq time_const -controls the -.Qq stiffness -of the phase-lock loop and thus the speed at -which it can adapt to oscillator drift. The -.Qq watchdog timer -value is the number of seconds which have elapsed since the last sample -offset was given to the loop filter. The -.Ar oneline -and -.Ar multiline -options specify the format in which this information -is to be printed, with -.Ar multiline -as the default. -.It sysinfo -Print a variety of system state variables, i.e. state related to the -local server. All except the last four lines are described in the -.Tn NTP -Version 3 specification, RFC 1305. The -.Qq system flags -show various system flags, some of which can be set and cleared by the -.Qq enable -and -.Qq disable -configuration commands, -respectively. The -.Qq stability -is the residual frequency error -remaining after the system frequency correction is applied and is -intended for maintenance and debugging. In most architectures, this -value will initially decrease from as high as 500 ppm to a nominal value -in the range .01 to 0.1 ppm. If it remains high for some time after -starting the daemon, something may be wrong with the local clock, or the -value of the kernel variable -.Qq tick -may be incorrect. The -.Qq broadcastdelay -shows the default broadcast delay, as set by -the -.Qq broadcastdelay -configuration command, while the -.Qq authdelay -shows the default authentication delay, as set by -the -.Qq authdelay -configuration command. -.It sysstats -Print statistics counters maintained in the protocol module. -.It memstats -Print statistics counters related to memory allocation -code. -.It iostats -Print statistics counters maintained in the input\-output module. -.It timerstats -Print statistics counters maintained in the timer/event queue support -code. -.It reslist -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. -.It monlist Op Ar version -Obtain and print traffic counts collected and maintained by the monitor -facility. The version number should not normally need to be specified. -.It Xo clkbug -.Ar clock_peer_address -.Op Ar addr2 -.Op Ar addr3 -.Op Ar addr4 -.Xc -Obtain debugging information for a reference clock driver. This -information is provided only by some clock drivers and is mostly -undecodable without a copy of the driver source in hand. -.El -.Sh RUNTIME CONFIGURATION REQUESTS -All requests which cause state changes in the server are authenticated -by the server using a configured -.Tn 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 -.Nm Ns . -This can be done using the -.Em keyid -and -.Em 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: -.Bl -tag -width indent -.It Xo addpeer -.Ar peer_address -.Op Ar keyid -.Op Ar version# -.Op Ar prefer -.Xc -Add a configured peer association at the given address and operating in -symmetric active mode. 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. If the -optional -.Ar keyid -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 -.Ar version# -can be 1, 2 or 3 and defaults to 3. The -.Ar 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. -.It Xo addserver -.Ar peer_address -.Op Ar keyid -.Op Ar version# -.Op Ar prefer -.Xc -Identical to the -.Em addpeer -command, except that the operating mode is client. -.It Xo broadcast -.Ar peer_address -.Op Ar keyid -.Op Ar version# -.Xc -Identical to the -.Em addpeer -command, except that the operating mode is broadcast. In this case a -valid key identifier and key are required. The -.Ar peer_address -parameter can be the broadcast address of the local network or a -multicast group address assigned to -.Tn NTP . -If a multicast address, a -multicast-capable kernel is required. -.It Xo unconfig -.Ar peer_address -.Op Ar addr2 -.Op Ar addr3 -.Op Ar addr4 -.Xc -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. -.It Xo fudge -.Ar peer_address -.Op Ar time1 -.Op Ar time2 -.Op Ar stratum -.Op Ar refid -.Xc -This command provides a way to set certain data for a reference clock. -See the source listing for further information. -.It Xo enable -.Ar auth|bclient|pll|monitor|stats -.Op Ar ... -.Xc -Provide a way to enable various server options. Flags not mentioned are -unaffected. The -.Ar auth -flag causes the server to synchronize -with unconfigured peers only if the peer has been correctly -authenticated using a trusted key and key identifier. The default for -this flag is disable (off). The -.Ar bclient -flag causes the server -to listen for a message from a broadcast or multicast server, following -which an association is automatically instantiated for that server. The -default for this flag is disable (off). The -.Ar pll -flag enables -the server to adjust its local clock, with default enable (on). If not -set, the local clock free-runs at its intrinsic time and frequency -offset. This flag is useful in case the local clock is controlled by -some other device or protocol and -.Tn NTP -is used only to provide -synchronization to other clients. The -.Ar monitor -flag enables the -monitoring facility (see elsewhere), with default disable (off). The -.Ar stats -flag enables statistics facility filegen (see -description elsewhere.), with default enable (on). -.It Xo disable -.Ar auth|bclient|pll|monitor|stats -.Op Ar ... -.Xc -Provide a way to disable various server options. Flags not mentioned -are unaffected. The flags presently available are described under the -enable command. -.It Xo restrict -.Ar address -.Ar mask -.Ar flag -.Op Ar flag -.Xc -Cause 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: -.Bl -tag -width indent -.It ignore -Ignore all packets from hosts which match this entry. If this flag is -specified neither queries nor time server polls will be responded to. -.It noquery -Ignore all -.Tn NTP -mode 7 packets (i.e. information queries and -configuration requests) from the source. Time service is not affected. -.It nomodify -Ignore all -.Tn NTP -mode 7 packets which attempt to modify the state of the -server (i.e. run time reconfiguration). Queries which return information -are permitted. -.It notrap -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. -.It lowpriotrap -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. -.It noserve -Ignore -.Tn NTP -packets whose mode is other than 7. In effect, time service -is denied, though queries may still be permitted. -.It nopeer -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. -.It notrust -Treat these hosts normally in other respects, but never use them as -synchronization sources. -.It limited -These hosts are subject to limitation of number of clients from the same -net. Net in this context refers to the IP notion of net (class A, class -B, class C, etc.). Only the first -.Qq client_limit -hosts that have -shown up at the server and that have been active during the last -.Qq client_limit_period -seconds are accepted. Requests from other -clients from the same net are rejected. Only time request packets are -taken into account. -.Qq Private , -.Qq control , -and -.Qq broadcast -packets are not subject to client limitation and -therefore are not contributing to client count. History of clients is -kept using the monitoring capability of -.Xr xntpd 8 . -Thus, monitoring is active as long as there is a restriction entry with -the -.Ar limited -flag. The default value for -.Qq client_limit -is 3. The default value for -.Qq client_limit_period -is 3600 -seconds. Currently both variables are not runtime configurable. -.It ntpport -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 -.Tn NTP -UDP port (123). Both -.Em ntpport -and -.Pf non\- Em ntpport -may be specified. The -.Em ntpport -is considered more specific and is sorted later in the list. -.El -.It Xo unrestrict -.Ar address -.Ar mask -.Ar flag -.Op Ar flag -.Xc -Remove the specified flag(s) from the restrict list entry indicated -by the -.Ar address -and -.Ar mask -arguments. -.It Xo delrestrict -.Ar address -.Ar mask -.Op Ar ntpport -.Xc -Delete the matching entry from the restrict list. -.It monitor Ar yes|no -Enable or disable the monitoring facility. Note that a -.Em monitor Ar no -command followed by a -.Em monitor Ar yes -command is a good way of resetting the packet counts. -.It readkeys -Cause 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 -.Nm xntpd -configuration file). This allows encryption keys to be changed without -restarting the server. -.It Xo trustkey -.Ar keyid -.Op Ar keyid -.Op Ar keyid -.Op Ar keyid -.Xc -Add 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. -.It Xo untrustkey -.Ar keyid -.Op Ar keyid -.Op Ar keyid -.Op Ar keyid -.Xc -Remove one or more keys from the trusted key list. -.It authinfo -Return information concerning the authentication module, including -known keys and counts of encryptions and decryptions which have been -done. -.It setprecision Ar precision_value -Set the precision which the server advertises to the specified value. -This should be a negative integer in the range -4 through -20. -.It traps -Display the traps set in the server. See the source listing for further -information. -.It Xo addtrap -.Ar address -.Op Ar port -.Op Ar interface -.Xc -Set a trap for asynchronous messages. See the source listing for further -information. -.It Xo clrtrap -.Ar address -.Op Ar port -.Op Ar interface -.Xc -Clear a trap for asynchronous messages. See the source listing for -further information. -.It reset Ar ... -Clear the statistics counters in various modules of the server. See the -source listing for further information. -.El -.Sh SEE ALSO -.Xr xntpd 8 -.Sh HISTORY -Written by -.An Dennis Ferguson -at the University of Toronto. -.Sh BUGS -.Nm 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. |
