*** UNIX MANUAL PAGE BROWSER ***

ntp.conf(4) Kernel Interfaces Manual ntp.conf(4) NAME ntp.conf - Network Time Protocol (NTP) configuration file DESCRIPTION The xntpd configuration file, /etc/ntp.conf, is read by xntpd at startup. The xntpd configuration file is relatively free of formatting. Com- ments, which may be freely inserted, begin with a # character and ex- tend to the end of the line. Blank lines are ignored. Configuration commands consist of an initial keyword followed by a list of arguments, separated by white space. Configuration commands may not be continued over multiple lines. Arguments may be host names, host addresses writ- ten in numeric, dotted-quad form, integers, floating point numbers (when specifying times in seconds) and text strings. Optional argu- ments are delimited by "[]" in the following descriptions, while alter- natives are separated by "|". Configuration Options peer host_address [key #] [version #] [prefer] server host_address [key #] [version #] [prefer] ode #] broadcast host_address [key #] [ver- sion #] [ttl #] The following commands specify various time servers to be used or time services to be provided: This command specifies that the local server is to operate in "symmetric active" mode with the remote server host_address. In this mode, the local server can be synchronized to the remote server and, in addition, the remote server can be synchro- nized by the local server. This is useful in a network of servers where, depending on various failure scenarios, either the local or re- mote server host may be the better source of time. This command speci- fies that the local server is to operate in "client" mode with the re- mote 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. This command specifies that the local server is to operate in broadcast mode where the local server sends periodic broadcast messages to a client population at the broad- cast or multicast address named in the command. Ordinarily, this spec- ification applies only to the local server operating as a transmitter; for operation as a broadcast client, see the broadcastclient or multi- castclient commands. In this mode, the host_address is usually the broadcast address on one of the local networks or a multicast address assigned to NTP. Address 224.0.1.1 is assigned to NTP; this is presently the only number that should be used. The following options can be specified with these commands: 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. Allows you to specify the version number to be used for outgoing NTP packets. Versions 1, 2, and 3 are the choices; ver- sion 3 is the default. Version 1 must be used for hosts running the University of Maryland ntpd daemon. Marks the host as a preferred host. All other things being equal, this host will be chosen for syn- chronization among a set of correctly operating hosts. Specifies the time-to-live (TTL) to use on multicast packets (broadcast mode only). Selection of the proper value, which defaults to 127, must be coordi- nated with the network administrator(s). Additional Configuration Options 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 mea- sures the nominal network delay using a brief client/server exchange with the remote server, then enters the 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 authentica- tion and the same trusted key and key identifier. Provides a way to disable various server options. Flags not mentioned are unaffected. The flags presently available are described under the enable command. Specifies the name of the file used to record the frequency offset of the local clock oscillator. If the file exists on startup, it is read and the value used to set the initial frequency offset and then updated once every hour with the current offset computed by xntpd. If the file does not exist or this command is not given, the initial frequency off- set is assumed zero. In this case, it may take some hours for the fre- quency 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). The file is updated by writing the current drift value into a temporary file and then using rename to replace the old version. Therefore, xntpd must have write permission for the di- rectory the drift file is located in, and file system links, symbolic or otherwise, should be avoided. Provides a way to enable various server options. Flags not mentioned are unaffected. Causes the server to synchronize with unconfigured peers only if the peer has been cor- rectly authenticated using a trusted key and key identifier. The de- fault for this flag is disable (off). Causes the server to listen for a message from a broadcast or multicast server, following which an as- sociation is automatically instantiated for that server. The default for this flag is disable (off). 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. Enables the monitoring facility (see "Monitoring Options"), with default enable (on). Enables statistics facility filegen, with default enable (on). This command is used in the same way as the 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. Authentication Options Indicates the amount of time it takes to encrypt an NTP authentication field on the local computer. This value is used to correct transmit time stamps when the authentication is used on outgoing packets. The value usually in the range of 0.0001 seconds to 0.003 seconds, though it is very dependent on the CPU speed of the host computer. This value is calculated and inserted into the ntp.conf file by the ntpsetup util- ity. Specifies the key identifier to use with the ntpq program, which is useful to diagnose and repair problems that affect xntpd operation. The operation of the ntpq program and xntpd conform to those specified in RFC 1305. Requests from a remote ntpq program that affect the state of the local server must be authenticated, which requires both the re- mote program and local server share a common key and key identifier. The argument to this command is a 32-bit unsigned integer. If no re- questkey command is included in the configuration file, or if the keys do not match, such requests are ignored. Specifies the name of a file that contains the encryption keys and key identifiers used by xntpd when operating in authenticated mode. See ntp.keys(4) for description of the key file format. Specifies the key identifier to use with the xntpdc program, which is useful to diagnose and repair problems that affect xntpd operation. The operation of the xntpdc program are spe- cific to this particular implementation of xntpd and can be expected to work only with this and previous versions of the daemon. Requests from a remote xntpdc program that affect the state of the local server must be authenticated, which requires both 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 requestkey command is in- cluded in the configuration file, or if the keys do not match, such re- quests are ignored. Specifies the encryption key identifiers that are trusted for the purposes of authenticating peers suitable for synchro- nization. The authentication procedures require that both the local and remote servers share the same key and key identifier for this pur- pose, 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. Access Control Options Defines the number of clients from the same network that are allowed to use the server. The default is 3. Specifies the number of seconds af- ter which a client is considered inactive and thus no longer is counted for client limit restriction. The default is 3600 seconds. The xntpd daemon 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 ad- dress 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 mask argument defaults to 255.255.255.255, meaning that the 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 en- try in the list. Note that, while address is normally given in dot- ted-quad format, the text string default, with no mask option, may be used to indicate the default entry. In the current implementation, flags always restrict access: an entry with no flags indicates that free access to the server is to be given. The flags are not orthogonal, in that more re- strictive flags will often make less restrictive ones redundant. The flags can generally be classed into two categories: those that restrict time service and those that restrict informational queries. One or more of the following flags may be specified: Ignores all packets from hosts that match this entry. If this flag is specified, queries and time server polls receive no re- sponse. Ignores all NTP mode 6 and 7 packets (information queries and configuration requests) from the source. Time ser- vice is not affected. Ignores all NTP mode 6 and 7 packets that attempt to modify the state of the server (run time reconfigura- tion). Queries that return information are permitted. Declines 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 log- ging programs. Declares 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 de- nied service. This flag modifies the assignment algorithm by allowing low priority traps to be overridden by later requests for normal priority traps. Ignores NTP packets whose mode is other than 6 or 7. In effect, time service is denied, though queries may still be permitted. Provides stateless time service to polling hosts, but does not allocate peer memory resources to these hosts even if they otherwise might be considered useful as future synchronization partners. Treats these hosts normally in other respects, but never uses them as synchronization sources. Limits the number of clients that can use these hosts 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 clientlimit hosts that have accessed the server and that have been active during the last clientperiod seconds are accepted. Requests from other clients from the same net are rejected. Only time request packets are taken into account. Private, control, and broadcast packets are not subject to client limitation and therefore do not contribute to client count. History of clients is kept using the monitoring capability of xntpd. Thus, moni- toring is active as long as there is a restriction entry with the limited flag. Specifies 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 ntpport and non-ntpport may be specified. The ntpport is considered more specific and is sorted later in the list. Default restriction list entries, with the flags ignore, ntp- port, for each of the local host's interface addresses are in- serted into the table at startup to prevent the server from at- tempting 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 (everything besides your own NTP server is unrestricted). The restriction facility allows the current access policies of the time servers running on the NSFnet backbone to be imple- mented with xntpd as well. While this facility may be otherwise useful for keeping unwanted time servers from affecting your own, it should not be considered an alternative to the standard NTP authentication facility. Source address based restrictions can be circumvented by a determined cracker. Monitoring Options filegen name [file filename] [type typename] [flag flagval] [link | no- link] [enable | disable] Configures setting of generation file set name. Generation file sets provide a means for handling files that are continuously growing during the lifetime of a server. Server statis- tics are a typical example for such files. Generation file sets pro- vide access to a set of files used to store the actual data. At any time, only one element of the set is being written to. The 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 risk of disturbing the operation of xntpd. (The elements can be removed to free space for new data produced.) File names of set members are built from three elements: This is a constant filename path. It is not subject to modifications by the filegen statement. It is defined by the server, usually specified as a compile time constant. It may, however, be configurable for individual file generation sets via other commands. For example, the prefix used with loopstats and peerstats filegens can be configured using the statsdir statement explained pre- viously. This string is directly concatenated to the prefix with no intervening slash character (/). This can be modified using the file argument to the filegen statement. No .. elements are allowed in this component to prevent filenames referring to parts outside the filesys- tem hierarchy denoted by prefix. This part reflects individual ele- ments of a file set. It is generated according to the type of a file set. A file generation set is characterized by its type. The follow- ing types are supported: The file set is a single plain file. One element of file set is used per incarnation of a xntpd server. This type does not perform any changes to file set mem- bers during runtime, however it provides an easy way of separat- ing files belonging to different xntpd server incarnations. The set member filename is built by appending a dot (.) to concate- nated prefix and filename strings, and appending the decimal representation of the process id of the xntpd server process. One file generation set element is created per day. The term day is based on UTC. A day is defined as the period between 00:00 and 24:00 UTC. The file set member suffix consists of a dot (.) and a day specification in the following form: YYYYMMDD YYYY is a four-digit year number (for example, 1992); MM is a two-digit month number; and DD is a two-digit day number. Thus, information written at December 10th, 1992 would be written to a file named prefixfilename.19921210. Any file set member con- tains data related to a certain week of a year. The term week is defined by computing "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 W, and a two-digit week number. For example, information from January, 10th 1992 would be writ- ten to a file with suffix 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. One generation file element is generated per year. The filename suffix con- sists of a dot and a four-digit year number. 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 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. Information is only written to a file generation set when this set is enabled. Output is prevented by specifying disable. It is convenient to be able to access the current element of a file generation set by a fixed name. This feature is enabled by specifying link and disabled using nolink. If link is speci- fied, 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 re- named appending a dot, the letter C, and the pid of the xntpd server process. When the number of links is greater than one, the file is unlinked. This allows the current file to be ac- cessed by a constant name. Enables writing of statistics records. The following types of statistics are supported: En- ables recording of loop filter statistics information. Each up- date of the local clock outputs a line of the following form to the file generation set named "loopstats": 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. Enables recording of peer statis- tics information. This includes statistics records of all peers of a NTP server and of the 1-pps signal, where present and con- figured. Each valid update appends a line of the following form to the current element of a file generation set named "peer- stats": 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. Enables recording of clock driver statistics informa- tion. Each update received from a clock driver outputs a line of the following form to the file generation set named "clock- stats": 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 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. Statistic files are managed using file generation sets (see the filegen description). The information obtained by enabling sta- tistics recording allows analysis of temporal properties of a xntpd server. It is usually only useful to primary servers or maybe main campus servers. Indicates the full path of a direc- tory where statistics files should be created. This keyword al- lows the (otherwise constant) filegen filename prefix to be mod- ified for file generation sets used for handling statistics logs (see the description of the filegen statement). Miscellaneous Options Specifies the default delay to be used in cases where the delay cali- bration procedure between local and remote servers might fail due to network or server access controls. 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. 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. moni- tor yes|no authenticate yes|no These commands have been super- seded by the enable and disable commands. They are listed here for historical purposes. 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. Adds an addi- tional system variable. These variables can be used to distrib- ute additional information such as the access policy. If the variable of the form name=value is followed by the default key- word, the variable is listed as part of the default system vari- ables (ntpq rv command). These additional variables serve in- formational purposes only. They are not related to the protocol other that they can be listed. The known protocol variables al- ways override any variables defined by the the setvar mechanism. There are three special variables that contain the names of all variables of the same group. The sys_var_list holds the names of all system variables. The peer_var_list holds the names of all peer variables and the clock_var_list hold the names of the reference clock variables. trap host_address [port port_number] [interface interface_address] Configures a trap receiver at the given host address and port number, sending messages with the specified local interface address. If the port number is un- specified, a value of 18447 is used. If the interface address is not specified, the message is sent with a source address (the local interface the message is sent through). On a multihomed host, the interface used may vary from time to time with routing changes. The trap receiver generally logs event messages and other infor- mation from the server in a log file. While such monitor pro- grams may also request their own trap dynamically, configuring a trap receiver ensures that no messages are lost when the server is started. Variables Most variables used by the NTP protocol can be examined with the xntpdc (mode 7 messages) and the ntpq (mode 6 messages). Currently very few variables can be modified by using mode 6 messages. These variables are either created with the setvar directive or the leap warning vari- ables. The leap warning bits that can be set in the leapwarning vari- able (up to one month ahead). Both, the leapwarning and in the leapindication variable, have a slightly different encoding than the usual leap bits interpretation: The daemon passes the leap bits of its synchronization source (usual mode of operation). A leap second is added/deleted (operator forced leap second). Leap information from the synchronization source is ignored (thus LEAP_NOWARNING is passed on). Reference Clock Support The xntpd daemon includes support for a number of types of reference clocks. A reference clock is generally (though not always) a radio timecode receiver that 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. For configuration purposes, xntpd treats reference clocks like normal NTP peers. However, unlike normal peers, reference clocks are referred to by an invalid IP address. Reference clock addresses are of the form 127.127.t.u, where t is an integer denoting the clock type and u indicates the type-specific unit number, in the range 0-3, that is used to identify 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 de- vice is normally specified by adding a soft link /dev/device%d to the particular hardware device involved. The device is compiled in xntpd according to the clock type. The following table lists the supported reference clock types, device names, clock names, and descriptions: tab(@); lfHB lfHB lfHB lfHB l l l l . _ Type@Device@Name@Description _ 1@(none)@LOCAL@Undisciplined Local Clock 3@pst@WWV_PST@PSTI/Traconex WWV/WWVH Receiver 4@wwvb@WWVB_SPEC@Spectracom WWVB Receiver 18@acts@NIST_ACTS@NIST Automated Computer Time Service 25@true@TRUE- TIME@GPS TrueTime _ Reference clocks are configured using a server statement in the config- uration file. Typically, this is the only command necessary to config- ure a reference clock. The following is the format for this command: server 127.127.t.u [prefer] ode m] In the preceding command: Specifies the clock type number. Specifies the unit number. This is typically 1, but can range from 0-3. Modi- fies the clock selection algorithm. Specifies a clock mode for those clock drivers that support multiple modes of operation. Reference clock support provides the fudge command, which can be used to configure reference clocks in special ways. This command must fol- low the corresponding server command in the configuration file. The following is the format for this command: fudge 127.127.t.u [stratum num] [refid id] [time1 secs] [time2 secs][flag1 0|1] [flag2 0|1] [flag4 0|1] Specifies a number in the range 0 (zero) to 15, if you want to override the default stratum as- signed by xntpd. Specifies a four-character, null-terminated ASCII string, if you want to override the default reference identifier as- signed by xntpd. Specifies a fixed-point decimal number (in seconds) to be added to the time offset produced by xntpd. This provides a way to correct a systematic error or bias by a particular clock. Specifies a fixed-point decimal number that is interpreted in a clock-dependent way. A flag whose interpretation depends on the clock receiving it. A flag whose interpretation depends on the clock receiving it. Enables detailed status monitoring and event recording. The data collected are written to the clockstats file maintained by the filegen utility (See xntpd(8)). This file is normally processed by a cron job run once per day to produce summary statistics and performance data. The clock drivers, and the addresses used to configure them, are de- scribed as follows: 127.127.1.u - Undisciplined Local Clock This driver can have the following applications: Allow a machine to use its own system clock as a reference clock, using no outside clock dis- cipline source. This is useful if you want to use NTP in an isolated environment with no radio clock or NIST modem available. Choose a ma- chine that has a good clock oscillator and configure it with this sup- port. Set the clock using the best means available. Then, point all the other machines at this one or use broadcast (not multicast) mode to distribute time. 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 useful if that server has an ovenized oscillator. For this you would configure this clock at a higher stratum (3 or 4) to prevent the server's stratum from falling below that. An external dis- cipline source is available, such as the NIST "lockclock" program, which synchronizes the local clock using a telephone modem and the NIST Automated Computer Time Service (ACTS), or the Digital Time Synchro- nization Service (DTSS), which runs on DCE machines. In this case, set the stratum to zero, indicating a bona fide stratum-1 source. Use this with caution since there is no easy way to telegraph through 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 ex- ceed 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 support is in use. The algorithm is designed so that the local clock support is not 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 support is selected for synchronization and all other discipline sources are ig- nored. This behavior is intended for use when an external discipline source controls the system clock. Fudge Factors By default, the stratum for this driver LCLSTRATUM is set at 3 and the reference ID is set to LCL. Both can be changed by the fudge command or the xntpdc utility. Never configure this driver to operate at a stratum that might disrupt a client with access to a bona fide primary server, unless the local clock oscillator is reliably disciplined by another source. Never configure a server that 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 para- meter adjusts the frequency (in ppm). Both parameters are additive; that is, they add increments in time or frequency to the present val- ues. Note: The frequency cannot be changed when the kernel modifica- tions are in use. The fudge flag1 and fudge flag2 bits set the corre- sponding 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 automati- cally when the leap takes place; they must be turned off manually after the leap event. 127.127.4.u - Spectracom WWVB Receiver This driver supports the Spectracom Model 8170 and Netclock/2 WWVB Syn- chronized Clock. This clock has proven a reliable source of time, ex- cept 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 DIP switches on this clock should be set to 24-hour display, AUTO DST off, time zone 0 (UTC), data format 0 or 2, and baud rate 9600. 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> In the preceding format: Denotes on-time. Denotes hours, minutes, and seconds. Is a synchronization flag. A space (" ") indicates in syn- chronization; a question mark (?) indicates out of synchronization. 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 In the preceding format: Denotes on-time. Is a synchronization flag. A space (" ") indicates in synchronization; a question mark (?) indi- cates out of synchronization. Is a quality indicator. A space (" ") indicates locked and A,B,C, or D indicates unlocked. Denotes year (as broadcast). Denotes day of year. Denotes hours, minutes, seconds, and 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, but either A,B,C, or D when the time error is less than 10 ms, 100 ms, 500 ms, or 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 interpolates the format in use from the length of the mes- sage. 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 com- mand is set to 1, the driver retrieves this table and writes it to the clockstats file when the first timecode message of a new day is re- ceived. 127.127.18.u - 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 de- signed for use when neither a radio clock nor connectivity to Internet time servers is available. For the best accuracy, the individual tele- phone 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 mo- dem dial string will differ depending on local telephone configuration, 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 mil- lisecond or two, but may need correction due to the delay characteris- tics of the individual modem involved. For undetermined reasons, some modems work with the ACTS echo-delay measurement scheme and some do not. This driver tries to do the best it can with what it gets. Ini- tial experiments with a Practical Peripherals 9600SA modem 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 (auto- matic), 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 en- abled using a fudge flags switch (see Fudge Factors). 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 in- dividual modem characteristics, the fudge flag2 switch should be set to disable the ACTS echo-delay scheme. In any case, the fudge time1 para- meter can be used to adjust the propagation delay as required. The ACTS call interval is determined in one the following ways: In man- ual mode, a call is initiated by setting fudge flag1 using xntpdc, ei- ther manually or by a cron job. In automatic mode, this flag is set by the peer timer, which is controlled by the sys_poll variable in re- sponse 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 con- figuration 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 call- ing program terminated if a valid clock update has been determined, no more numbers remain in the list, a device fault or timeout occurs, or fudge flag1 is reset manually using xntpdc. The NIST timecode message is transmitted at 1200 bps in the following format: jjjjj yy-mm-dd hh:mm:ss tt l uuu mmmmm UTC(NIST) * In the previous messages: Denotes the modified Julian day. Denotes the year, month, and day. Denotes the hours, minutes, and seconds. Is the DST indicator (see driver listing). Is the leap-second warning (see driver listing). Denotes DUT1 correction (see driver listing). De- notes modem calibration (see driver listing). Denotes an on-time char- acter. 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 time stamp is captured at the * character, as required by the ACTS specification, and used as the ref- erence 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 ten valid messages have been received, no message has been received for 15 seconds, or an # on-time character 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 correc- tion. 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 synchro- nization and all other discipline sources will be ignored. Ordinarily, the prefer keyword is used only in automatic mode when primary time is to be obtained through ACTS, and backup NTP peers used only when ACTS fails. Call Management Since ACTS is 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 complete or when no more numbers remain in the alternate path list; a device fault or timeout has occurred; 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 seconds. If the error is less than time2 for some number of times, the interval is increased, but not more than about 18 hours. With the default value of zero for fudge time2, the interval increases from 1000 seconds to the 4000-8000 second range, in which the expected accuracy should be in the 1-2 ms range. Setting fudge time2 to a large value, like 0.1 second, may result in errors of that order, but increase the call interval to the maximum. The exact value for each configuration depends on the modem and operating system involved; you might have to experiment. Manual call attempts can be made at any time by setting fudge flag1 us- ing xntpdc. For example, the following xntpdc command asks for a key identifier and password and, if authenticated by the server, sets flag1: fudge 127.127.18.1 flags 1 There might be a short delay until the expiration of the current poll timeout. The flag1 can be set from a cron job using the following steps: Create a file with the following contents: keyid 11 passwd dialup fudge 127.127.18.1 flags 1 quit Run the following program at specified times as required: /usr/local/bin/xntpdc file This driver supports at least one model of Kinemetrics/TrueTime Timing Receivers, the TrueTime GPS Model 151-601-1 XL-DC, and very likely oth- ers in the same model family that use the same timecode formats. The clocks are connected to a serial port. Up to four units, with unit numbers in the range 0 through 3, can be configured. The driver as- sumes the serial port device name is /dev/truex (for example, unit 1 at 127.127.25.1 opens the clock at /dev/true1) and that the clock is con- figured for 9600-baud operation. FILES Default name of the configuration file Conventional name of the drift file Conventional name of the key file RELATED INFORMATION Commands: ntp(1), ntpdate(8), ntpq(8), xntpd(8), xntpdc(8) Files: ntp.keys(4) Network Administration delim off ntp.conf(4)